Python工具包，用于增强Saleae分析器

Saleae Logic内建分析器仅提供了几种基本选项来显示传输的字节，例如作为ASCII文本或几种数字格式之一。如果您正在使用将不仅仅是整数或文本数据编码到这些字节的设备，或者每个字节存储多个值，这些值需要您进行计算、导出数据以进行后期处理，或者将帧显示为二进制位以便您可以直接查看您关心的部分，会是什么样子？这正是计算机擅长的事情；为什么不让您的计算机来做呢？

这个Python库与特殊的“增强型”Saleae Logic分析器相结合，使您能够轻松增强显示的数据，以便为每个帧提供自己的文本和标记。现在，您可以专注于解决实际问题，而不是解释难以理解的十六进制值。

相关

• saleae-enrichable-spi-analyzer：支持增强的Saleae SPI分析器版本。
• saleae-enrichable-i2c-analyzer：支持增强的Saleae I2C分析器版本。

安装

注意：此版本需要Python 3.5！

如果您想使用最新版本，可以直接从PyPI安装

pip install saleae_enrichable_analyzer

要使用开发版本，只需克隆此存储库并运行

pip install .

捆绑的增强脚本

此库自带了一些增强脚本，您可以按照以下说明使用其中的任何一种。请注意，您可能需要在示例中将python替换为相关Python二进制的路径——如果您将此库安装到虚拟环境中，该路径应指向该环境的python，当然。

SPI

SC16IS75xx

支持NXP SC16IS75xx系列SPI UART芯片。

已知支持

• SC16IS740
• SC16IS750
• SC16IS752
• SC16IS760
• SC16IS762

可以通过以下增强脚本使用

python -m saleae_enrichable_analyzer.scripts.spi.SC16IS75xx

I2C

AD799x

支持Analog Devices AD799x系列I2C ADC芯片。

已知支持

• AD7991 (12位)
• AD7995 (10位)
• AD7999 (8位)

可以通过以下增强脚本使用；确保将BITS替换为您ADC提供的位数，以及将ADDRESS替换为您的设备基础2的I2C地址

python -m saleae_enrichable_analyzer.scripts.i2c.AD799x ADDRESS BITS

此外，您还可以提供--reference-voltage=VOLTAGE参数，以显示计算出的电压以及原始ADC值。

INA219

支持德州仪器INA219电流监控IC。

可以通过以下增强脚本使用；确保将ADDRESS替换为您的设备基础2的I2C地址

python -m saleae_enrichable_analyzer.scripts.i2c.INA219 ADDRESS

编写您的增强脚本

使用此功能就像创建自己的模块，该模块位于某处并从saleae_enrichable_analyzer.EnrichableAnalyzer中派生，并具有您想要使用的功能的方法；以下是一个基本示例

import sys
from typing import List, Optional

from saleae_enrichable_analyzer import (
    Channel, EnrichableAnalyzer, Marker, MarkerType
)


class MySimpleAnalyzer(EnrichableAnalyzer):
    def handle_bubble(
        self,
        packet_id: Optional[int],
        frame_index: int,
        start_sample: int,
        end_sample: int,
        frame_type: int,
        flags: int,
        direction: Channel,
        value: int
    ) -> List[str]:
        return [
            "This message will be displayed above every frame in the blue bubble"
        ]

    def handle_marker(
        self,
        packet_id: Optional[int],
        frame_index: int,
        sample_count: int,
        start_sample: int,
        end_sample: int,
        frame_type: int,
        flags: int,
        mosi_value: int,
        miso_value: int
    ) -> List[Marker]:
        markers = []

        if(miso_value == 0xff) {
            # This will show a "Stop" marker on the zeroth sample
            # of the frame on the MISO channel when its value is 0xff.
            markers.append(
                Marker(0, Channel.MISO, MarkerType.Stop)
            )
        }

        return markers

if __name__ == '__main__':
    MySimpleAnalyzer.run(sys.argv[1:])

以下描述的方法可以实现与Saleae Logic的交互。

如果您想看到简单的具体示例，可以参考以下内容

• simple_SC16IS7xx.py：实现一个简单的增强器，用于显示SC16IS7xx系列SPI UART的寄存器、通道和数据。
• simple_ad7995.py：实现一个功能更完整的增强器，用于显示AD7995 I2C ADC的详细配置和读取数据。

还请注意，scripts目录中也包含示例，但它们在功能上可能更高级。

handle_bubble

    def handle_bubble(
        self,
        packet_id: Optional[int],
        frame_index: int,
        start_sample: int,
        end_sample: int,
        frame_type: int,
        flags: int,
        direction: Channel,
        value: int
    ) -> List[str]:
        return []

为此帧设置气泡文本（在框架上方蓝色显示的文本）。默认情况下不显示气泡。建议您返回多个长度不同的字符串。

handle_marker

    def handle_marker(
        self,
        packet_id: Optional[int],
        frame_index: int,
        sample_count: int,
        start_sample: int,
        end_sample: int,
        frame_type: int,
        flags: int,
        value1: int,   # SPI: MOSI; I2C: SDA
        value2: int,   # SPI: MISO; I2C: Undefined
    ) -> List[Marker]:
        return []

返回在给定样本点显示的标记。默认情况下不显示标记。

此方法可以用于除了显示标记以外的其他原因——如果您的脚本需要以接收到的顺序接收所有数据帧，它也是有用的。在这种情况下，您可以在方法体中记录您的数据包，并返回一个空列表。有关该策略的具体示例，请参阅基本I2CAnalyzer类。

handle_tabular

    def handle_tabular(
        self,
        packet_id: Optional[int],
        frame_index: int,
        start_sample: int,
        end_sample: int,
        frame_type: int,
        flags: int,
        value1: int,   # SPI: MOSI; I2C: SDA
        value2: int,   # SPI: MISO; I2C: Undefined
    ) -> List[str]:
        return []

在“解码协议”表格部分中显示的数据。由于Saleae Logic的限制：如果实现，此方法必须为每个请求返回结果数组中确切相同数量的字符串；如果您尝试这样做，您可能会看到以下错误（sic）“错误：分析器结果中字符串的数量在不同显示基之间不同”后面跟着一个SIGSEGV。

调试您的增强脚本

如果Saleae Logic在使用您的增强脚本时崩溃，几乎可以肯定是您的脚本而不是Saleae Logic的故障。幸运的是，通过使用内置的日志功能进行调试非常简单。

默认情况下，日志会写入stderr，但由于我们大多数人不在终端中运行Saleae Logic，所以输出并不立即可见。要在非终端模式下查看日志输出，可以使用以下两个标志

• --loglevel=级别：设置报告输出的级别。在调试时，您可能想使用--loglevel=DEBUG。有效的选项（按可闻性的顺序排列）包括CRITICAL、ERROR、WARNING、INFO和DEBUG。所选级别的输出将包括所有较低可闻性级别的输出。
• --logpath=路径：设置写入日志输出的文件路径。

注意，当使用捆绑的增强脚本时，这些标志必须跟在模块名称之后。例如，要调试捆绑的AD799x增强脚本（它本身需要两个位置参数），您可以在Saleae Logic中的“增强脚本”中设置以下内容

python -m saleae_enrichable_analyzer.scripts.i2c.AD799x --loglevel=DEBUG --logpath=/tmp/logic_debug.log 12 0101000

如果您正在调试自己编写的脚本，则只需在脚本路径后提供标志

python /path/to/your/enrichment/script.py --loglevel=DEBUG --logpath=/tmp/logic_debug.log

无论您是否已启用将日志写入文件，日志消息都会继续写入stderr，并且如果您发现脚本编写的日志输出不够揭示，运行Saleae Logic在终端中查看Saleae Logic和您的脚本交织的日志输出可能会有所帮助。