调试 I2C/SPI 设备时很多时候问题并不是“代码写错了”而是总线上根本没有按照预期跑出波形。比如驱动里读写 EEPROM 能执行完寄存器却全 0xFF或者 SPI 屏幕花屏明明 MOSI 有数据颜色却不对。这类问题最有效的排查手段不是一遍遍读数据手册而是抓下信号直接用逻辑分析仪或示波器做 I2C/SPI 信号解码把总线上实际传输的地址、命令和数据全部翻出来看一遍。信号解码的价值在于它不需要打断系统运行只需要把 SCL/SDA、CLK/MOSI/MISO/CS 对应接到采集通道上软件捕获后就能自动解析成“从机地址、寄存器地址、读写方向、ACK 应答、数据字节”这样的人类可读信息。不管是裸机开发、STM32CubeMX 生成的工程还是 Linux I2C/SPI 用户态调试这套思路都通用。这篇文章以免费开源的 PulseView/sigrok 工具链为例按“硬件准备 → 通道连接 → 采集解析 → 故障反向定位”的顺序把 I2C/SPI 信号解码的完整流程写清楚。前半部分先解决“怎么解出来”后半部分解决“解出来了怎么判断问题”。1. I2C/SPI 信号解码核心能力速览能力项说明解码对象I2C、SPI、UART 等多类同步/异步串行总线波形最低硬件I2C 2 通道SCL、SDASPI 建议 4 通道CLK、CS、MOSI、MISO推荐工具逻辑分析仪 PulseView/sigrok免费开源无需额外授权采样率要求一般建议为总线时钟的 8 倍以上I2C 100k/400k 用 4M/8M 采样率较稳输出形式时间轴波形 协议解码注释可导出数据清单单帧解析能力I2C 起始/停止条件、从机地址、读写位、ACK、寄存器地址、数据块SPI 解析能力CS 片选边界、CLK 极性与相位、MOSI/MISO 数据、命令/数据拆分批量处理sigrok-cli 可对保存的捕获文件批量离线解码适合场景黑屏/花屏调试、传感器寄存器读取异常、EEPROM 读写失败、总线时序冲突排查对大多数 8 位/32 位 MCU 调试场景来说8 通道、采样率 20M 左右的入门级逻辑分析仪已经够用。I2C 本身就是漏极开路加外部上拉SPI 通常是推挽输出逻辑分析仪不需要额外的电平转换配件就能直接测量只要共地即可。2. I2C/SPI 到底在解码什么2.1 I2C 需要关注的信息字段I2C 是一种两线制总线SCL 提供时钟SDA 传输数据。若只看波形单次通信里至少包含START 起始条件SCL 高电平时SDA 从高电平跳变到低电平。从机地址 读写位地址通常按 7 位寻址后面跟 1 位 R/W。ACK/NACK 应答从机在收到自己的地址或每个字节后拉低 SDA表示应答。寄存器地址很多 I2C 传感器的第一段数据就是寄存器地址。数据字节实际读写的寄存器内容。很多朋友会混淆“7 位地址”和“8 位地址”。比如 EEPROM 器件地址 0x50 通常是 7 位地址发送时向左移一位写操作变成 0xA0读操作变成 0xA1。逻辑分析仪解码器显示“0x50, WRITE”这个 0x50 就是器件地址本身如果代码里直接写“0xA0”其实是指带读写位的完整首字节。理解这一点才能把解码结果和驱动里的设备地址对起来。2.2 SPI 需要关注的信息字段SPI 与 I2C 不同它本质上是移位寄存器加片选控制没有帧格式里的地址概念。一次完整通信主要由以下部分构成CS/SS 片选信号通常低电平有效CS 拉低代表从机被选中。SCLK 时钟决定数据采样的节奏。CPOL/CPHA空闲电平和数据采样边沿。MOSI主机输出、从机输入。MISO从机输出、主机输入。某根信号线上有没有数据必须结合 CS 和 SCLK 一起看。CS 没有拉低时即使 MOSI 持续翻转大多数从机也会忽略这些数据这在多个 SPI 设备共享同一根 MOSI/SCLK 总线的场景里尤其关键。2.3 解码器与示波器/逻辑分析仪的关系示波器适合看“电压是否正常、上升沿缓不缓、有没有振铃”逻辑分析仪适合看“高低电平状态和时间顺序”。I2C/SPI 解码工具实际上是把采集到的数字波形送给软件解码器处理。常用的 sigrok 项目内置了大量协议解码器而 PulseView 则提供了一个图形界面连接逻辑分析仪后可以直接查看每根通道上的电平变化和解码结果。3. 环境准备与工具选择3.1 硬件侧准备设备作用逻辑分析仪采集 I2C/SPI 波形至少 8 通道更灵活杜邦线/测试夹连接被测板卡的信号脚与逻辑分析仪通道USB 延长线方便操作避免搬动被测设备被测板卡电源测量前确认目标系统已经正常上电连接原则是逻辑分析仪的 GND 必须与被测板卡的 GND 相连否则采样信号会飘。接着把 SDA、SCL、CLK、CS、MOSI、MISO 按顺序分配到通道并在软件里记住具体的通道编号。通道接线的常见坑只接了 SDA/SCL没有接 GND采样波形杂乱。SDA 和 SCL 接反解码结果全部乱码。SPI 的 MOSI 和 MISO 接反只看到主机发指令看不到从机返回的数据。杜邦线太长或接触不良造成信号振铃和丢采样点。3.2 软件侧准备推荐先装 PulseView。它自带 sigrok 解码器界面能同时显示原始波形和解码结果。想要批量处理捕获文件时再安装 sigrok-cli 命令行工具。# PulseView 负责图形界面采集 # sigrok-cli 负责无界面离线解析 sudo apt install pulseview sigrok-cliWindows 环境可以直接下载 pulseview 官方便携包解压后运行 pulseview.exe。不同操作系统的安装命令不同重点是通过设备驱动能正确识别逻辑分析仪。3.3 采样率设置I2C 标准模式 100kHz、快速模式 400kHz理论上 1M 采样率就能看到一帧但实际波形有上升沿、毛刺、尖峰最好设置 4M 或 8M 采样率。SPI 的 SCLK 从几百 kHz 到几十 MHz 都有若总线时钟是 1MHz建议至少 8M 采样率若是 20MHz 的高速 SPI普通入门逻辑分析仪可能力不从心需要更高采样率设备。采样率设置示例I2C 400kHz → 采样率 8M SPI 1MHz → 采样率 8M 或 12M SPI 10MHz → 采样率尽量 50M 以上3.4 触发功能逻辑分析仪支持“边沿触发”“协议触发”等。实际调试时如果问题只在某次读写后出现不要盲目从开始一直抓。可以设置 SDA 下降沿触发捕获起始条件或设置 CS 下降沿触发捕获 SPI 事务边界。PulseView 的触发设置会随不同硬件固件而变化核心思路是先找到目标事务发生的时间点再回看完整波形。4. I2C 信号解码实操流程4.1 接线与通道映射假设抓一块 I2C EEPROM 的写入过程信号I2C 方向逻辑分析仪通道SCL主机输出CH0SDA双向CH1GND-GND在 PulseView 里添加解码器 I2C并配置Decoder: I2C SCL Channel: Channel 0 SDA Channel: Channel 1 Address format: 7-bit如果从机使用 10 位地址也要在解码器配置里选对应格式。4.2 执行一次总线操作接好线后在 MCU 上运行一个最简单的写寄存器程序向设备地址 0x50 写入寄存器 0x00数据 0x55。或者用 Linux 下的 i2c-tools 发起一次写操作。# Linux 下使用 i2c-tools 测试具体地址和寄存器需要按设备手册填写 i2cset -y 2 0x50 0x00 0x55没必要为了抓波形刻意加快代码执行。点击 PulseView 上的 Run 后再执行命令等波形稳定后再 Stop。4.3 观察解码结果如果一切正常解码器会直接标注出类似下面的信息流START Slave address 0x50, WRITE ACK Register address 0x00 ACK Data 0x55 ACK STOP解码输出只是示意图不同版本的 PulseView 注释方式略有差异但顺序基本一致。看到这个序列说明 I2C 控制器已经完成了“地址 寄存器地址 数据”的基础帧。接下来把 0x55 改成 0xAA 再抓一次观测数据字节是否同步变化可以确认写入路径。4.4 I2C 读操作怎么判断读操作和写操作最大的不同是要先写寄存器地址再发起重复起始条件或 STOP 后重启把方向改成 READ。解码结果会类似START Slave address 0x50, WRITE ACK Register address 0x00 ACK REPEATED START Slave address 0x50, READ ACK Data 0x55 NACK STOP末尾的 NACK 通常代表主机主动结束本次读操作不一定是错误。只有地址阶段出现 NACK才表示没有从机应答。4.5 I2C 地址扫描技巧不确定传感器地址时可以写一个地址扫描程序。总线上依次发送 7 位地址的写操作检查有没有 ACK。也可以直接在 PulseView 里抓整个扫描过程查看哪些地址在总线上得到了应答。这是判断地址位、SA0/SA1 引脚配置是否正确的有效方法。比如某颗传感器如果 SA0 引脚接法不同实际地址会相差 1扫描结果能立刻看出来。5. SPI 信号解码实操流程5.1 接线与通道映射SPI 读写方向明确逻辑分析仪至少需要 3 到 4 个通道。以读取 SPI Flash 的 JEDEC ID 为例信号方向逻辑分析仪通道SCLK主机输出CH0CS/SS主机输出CH1MOSI主机输出CH2MISO从机输出CH3GND-GND在 PulseView 添加 SPI 解码器Decoder: SPI CLK Channel: Channel 0 CS# Channel: Channel 1 MOSI Channel: Channel 2 MISO Channel: Channel 3 CPOL: 0 CPHA: 05.2 SPI 模式为什么必须手动核对SPI 没有像 I2C 那样在协议层携带模式协商信息只能靠从机数据手册确定 CPOL/CPHA。解码器配置的 CPOL/CPHA 错了不仅数据解出来是错的屏幕显示也会异常。常见的四类模式模式CPOLCPHA空闲时钟采样边沿Mode 000低电平上升沿Mode 101低电平下降沿Mode 210高电平下降沿Mode 311高电平上升沿软件模拟 SPI 时时序往往也是照着这四种模式中的一种实现的。如果 GPIO 模拟的 SPI 在示波器上看不到连续时钟或 CS 和 CLK 关系不对解码结果自然会乱。5.3 SPI 读 Flash ID 实际操作大多数 SPI Flash 支持发送 0x9F 命令读取 JEDEC ID。主机先把 CS 拉低发送命令 0x9F然后发送若干空字节Flash 会在 MISO 上返回 Manufacturer ID 和 Device ID。# Linux 下读取 SPI Flash ID 的通用命令模板实际设备路径按环境调整 flashrom -p linux_spi:dev/dev/spidev0.0 -r /tmp/test.bin如果只是抓解码可以先用 MCU 或开发板执行一次最简单的读 ID 操作。PulseView 解码器会显示 CS 从高拉低、CLK 开始翻转、MOSI 上出现 0x9F、随后 MISO 返回 ID 字节。CS 拉高后这一帧结束。如果解码结果里 MISO 一直为低或高优先检查从机是否真的被 CS 选中。多个设备共用 SPI 总线的场景中常见原因是代码里没有把当前设备对应的 GPIO 片选拉低而只拉了 CS 高电平把器件隔离了。5.4 SPI 屏幕数据流解码SPI 屏幕初始化或刷图时总线上会有大量数据。除了控制命令外还有 RGB 像素数据。若想快速判断屏幕黑屏/花屏是通信层还是应用配置问题可以在初始化阶段抓波形重点核对RESET 引脚时序是否正常。CS 是否正确保持低电平。有没有写入 LCD 初始化命令。像素数据有没有在两个字节内被写错位置。如果是 ST7789、ST7735 这类常见 SPI LCD寄存器配置写错通常能看到“命令正确但后续数据量不符”这时解码波形能定位到具体是哪个命令后面少发了数据。5.5 硬件片选与软件片选SPI 从机选择既可以用 MCU 的硬件片选引脚也可以把任意 GPIO 拉低模拟片选。信号解码时两者没有区别。但软件片选会引入一个问题GPIO 到 CLK 的时序依赖代码执行顺序可能造成 CS 刚拉低CLK 还没准备好从机已经开始采集。逻辑分析仪抓到的波形里CS 和第一个 CLK 沿的时间间隔很小甚至重叠。遇到这种情况可以在 CS 拉低后加几个空延时保证片选有效后再启动硬件 SPI 或翻转软件时钟。6. 从解码结果反向排查总线问题6.1 没有 START 或 CS 不变化如果 PulseView 里根本没解出 STARTSCL 也没有时钟翻转大概率是主机程序没有发起通信或者总线引脚被复用方向配置错误。先用示波器/万用表确认 SCL 引脚是否被拉到确定电平再检查 STM32CubeMX 等工具生成的引脚复用配置。6.2 有波形但地址一直 NACKI2C 从机地址看起来配置正确但抓波形发现地址阶段后没有 ACK。优先排查从机供电是否正常。SDA 是否被拉低过久或上拉电阻缺失。总线上是否有多个地址冲突。I2C 总线是否没有共地。从机地址是高 7 位还是 8 位读写位是否被多移了一位。6.3 SPI 能发出数据从机不响应SPI 没有 ACK 机制判断从机是否收到数据只能看 MISO。如果 MISO 始终不变化可能是从机接收到了数据但命令本身不支持或者 MISO 通道接错也可能是从机处于写保护/睡眠状态。解码器里如果 CS 与 CLK 对应关系正确但 MISO 一直是高阻态需要检查从机是否有 MISO 使能引脚以及它是否被 CS 正确拉低。6.4 数据低位在前还是高位在前部分 SPI/I2C 器件支持位序配置。大多数人习惯高位在前但传感器、LCD 或 Flash 可能使用低位在前。解码器通常默认高位在前如果所有命令看起来都被反向了例如 0x01 变成 0x80要检查器件是否配置成 LSB first。这不是总线接线问题而是驱动配置问题解码波形能把这类顺序错误直观暴露出来。6.5 信号质量导致的毛刺I2C 属于开漏结构外部上拉太弱、总线电容过大会导致上升沿变缓软件采样时可能把毛刺误判成额外 START。SPI 时钟频率较高长飞线容易产生振铃也会让解码结果里多出很多无效位。出现这种情况时不要急着改代码先降低通信速率看解码是否正确。若降速后一切正常基本就是信号完整性问题。7. I2C/SPI 解码常见问题与排查方法问题现象可能原因排查方式解决方案解码器显示无有效数据未接 GND 或通道接反检查连接抓已知信号验证重新连接并确认通道映射I2C 出现乱码 START/STOP采样率不够或噪声干扰提高采样率降低总线速度设置至少 8 倍采样率I2C 从机地址 NACK地址错误、器件未上电、地址冲突扫描 I2C 地址核对器件手册与 SA0 引脚SPI 解码输出为空未正确配置 CS 通道确认 CS 极性选低电平有效的 CS#SPI 数据全为 0xFFMISO 未接、从机未应答检查从机供电和 CS调整片选逻辑SPI 解出的数据像是“镜像”CPOL/CPHA 配置错误或 LSB/MSB 位序问题查看 SCLK 空闲电平和采样沿更正 SPI 模式、检查位序配置软件模拟 SPI 偶尔解出多余数据GPIO 翻转时 CLK 抖动观察时钟沿前后电平增加延时保证建立时间和保持时间共地后数据仍不稳定杜邦线过长缩短连接检查接触使用短线或加屏蔽8. 让信号解码更工程化的细节8.1 先抓“已知数据”再抓“异常数据”调试任何 I2C/SPI 从机之前先跑一个确定性的操作比如读一次设备 ID 或写一个固定寄存器值。如果这个确定性步骤能正确解码说明工具链和接线没问题后续抓到的异常才可能是设备问题。否则解码工具本身接错了会误导排查方向。8.2 用 sigrok-cli 批量处理保存的波形PulseView 可以把捕获内容保存为.sr文件。这类文件可以被 sigrok-cli 重新解析适合批量复看多次抓取的波形。这里给出两个模板命令实际通道编号需要按自己保存的文件内容调整# 解析 I2C 捕获文件并打印解码注释 sigrok-cli -i i2c_capture.sr -P i2c:sda1:scl0 -A i2c# 解析 SPI 捕获文件并打印解码注释 sigrok-cli -i spi_flash_read.sr -P spi:clk0:cs1:mosi2:miso3:cpol0:cpha0 -A spi通过命令行解析可以把大量.sr文件放入同一个目录后写 Shell 循环批量处理把解码文本保存为日志再和 Git 提交记录对应起来。这样能够回查“改了哪些代码之后总线行为发生了什么变化”。8.3 规范保存通道映射通道接法每次可能不同如果只保存波形没有保存通道映射下一次回看时很容易忘记 SDA 在 CH0 还是 CH1。建议实际调试时在项目里放一个probe_config.md文件# Probe Mapping 2025-XX-XX I2C_SCL: CH0 I2C_SDA: CH1 GND: GND同理SPI 的 CLK、CS、MOSI、MISO 都要记录。这对团队协作和后续复现问题都很有帮助。8.4 解码前设置足够长的采集时间逻辑分析仪缓冲有限。采样率越高可捕获的时间窗口越短。调试 I2C 初始化流程时如果只抓了很短一段时间可能没覆盖到异常那条命令。可以先设置较长时间窗口、适当降低采样率确认事件大致位置再提高采样率抓关键片段。8.5 不要只依赖自动解码还要结合数据手册解码器给出的地址、数据和 ACK 只是总线协议层的解释。某些器件会有特殊字节序、命令码扩展或包长度规则自动解码并不了解这些。比如 I2C 传感器内部有多个 bank 的寄存器解码后看到的是“连续写寄存器 0x10-0x1F”但代码逻辑其实先执行了 bank 切换命令。此时不能只看单个 I2C 帧要把前端几个解码帧连起来读。8.6 对总线帧做编号标记PulseView 的解码注释会显示每条记录的时间偏移但默认不显示帧序号。遇到几十帧连续命令时可以借助解码器输出或手动标记把写寄存器的帧分成“帧 0、帧 1、帧 2”再与驱动源码里的语句逐条对应。这种逐句对应方式比只看最后错误结果高效得多。8.7 测完及时导出报告信号解码很容易出现“看着波形找到了原因但修完代码后没留证据”的情况。建议把关键波形截图、解码文本、通道映射、设备配置一起导出为一份 Markdown 调试报告。后续排查同类问题可以直接复用而不必重新接一次线。9. 总结与后续可以尝试的方向这篇文章里没有停留在“怎么读代码”的层面核心是把 I2C/SPI 信号解码当成交互链路调试手段I2C 重点看 START/STOP、地址、ACK、寄存器地址和数据。SPI 重点先确定 CPOL/CPHA 和 CS再观察 MOSI/MISO。工具建议选择 PulseView/sigrok 加 8 通道逻辑分析仪成本低、上手快。实验前先准备一条“已知数据”通路优先验证采样率和接线。保存波形时同步记录通道映射才能保证离线或批量解码有意义。对于刚接触 I2C/SPI 的工程师最值得先做的一次验证是找一个 I2C EEPROM 或带寄存器地址的传感器执行一次“写寄存器 0x00 数据 0x55”再用逻辑分析仪抓出完整地址帧。这次验证能一次性熟悉 START、写地址、ACK、写数据、STOP 几个核心概念。SPI 方面优先找一块 SPI Flash 读取 ID因为它的命令最简单MISO 返回相对容易确认。信号解码只是调试链路的一半另一半是把“解出来的帧”和“芯片手册里的寄存器和命令格式”对齐。每当解码结果看起来不合逻辑时不要先怀疑解码器先核对设备实际型号和手册时序因为很多总线异常并不是协议层错误而是寄存器位宽、片选有效电平或 SPI 工作模式不匹配。整条调试链路跑通之后再遇到 I2C 屏幕不亮、SPI Flash 读 ID 全 0xFF、传感器读回乱跳这类问题就可以先用这套方法快速把物理层和协议层切分开定位效率会高很多。
