企业官网建设流程全解析

I2C 总线时钟拉伸问题排查全攻略：从示波器波形到协议层根因的完整分析

一、当 SCL 被从机拉低超过 20ms：一次温湿度传感器的通信故障排查

在产品调试阶段，通过 I2C 总线读取 SHT31 温湿度传感器数据时出现间歇性失败：大约每 20 次读取中有 1 次在 I2C 总线上收到 NACK 或超时。用示波器捕获 SCL 和 SDA 信号后发现，在主机发出测量命令（0x2C06）后，SCL 的第 9 个时钟脉冲低电平持续了约 15ms——之后主机强行拉高 SCL 发出 STOP 条件，导致通信中断。

这个故障的根因是时钟拉伸（Clock Stretching）。SHT31 在接收到测量命令后需要约 12ms 来完成模数转换（单次高精度模式），在此期间从机会将 SCL 保持为低电平以通知主机"数据尚未准备好"。而主机端的 I2C 驱动程序设置了 5ms 的超时，在 SCL 恢复高电平之前就判定通信失败。

时钟拉伸是 I2C 协议中一个容易被忽视但频繁引发通信故障的机制。本文从协议规范出发，结合示波器实测波形和 STM32 I2C 驱动的源码分析，完整覆盖时钟拉伸的触发原因、排查流程和解决方案。

二、时钟拉伸的协议机制与 I2C 总线状态机

I2C 协议（Philips/NXP 规范 6.0 版本）在 3.1.9 节明确规定了时钟拉伸行为：从机可以在任意第 9 个 SCL 脉冲之后将 SCL 线拉低，以暂停主机发送后续时钟。主机必须在释放 SCL 后检测到 SCL 保持低电平，等待 SCL 被从机释放（变为高电平）再继续发送。

sequenceDiagram participant M as I2C 主机 (MCU) participant S as I2C 从机 (SHT31) participant Bus as SCL 线 M->>Bus: 释放 SCL (开漏上拉) Bus-->>M: SCL 保持低电平 (从机尚未释放) Note over M,S: 主机检测到 SCL=0, 进入等待状态 S->>S: 内部数据处理 (测量转换 / EEPROM 写入) S->>Bus: 释放 SCL Bus-->>M: SCL 变为高电平 Note over M,S: 主机检测到 SCL=1, 继续发送下一个时钟 M->>Bus: 拉低 SCL, 开始下一个数据位 Note over M,S: ★ 时钟拉伸的本质：从机通过 SCL 线实现流控制 ★

关键硬件细节：

• I2C 总线使用开漏输出（Open-Drain），SCL 和 SDA 线通过上拉电阻接到 VDD。主机和从机都可以将 SCL 拉低，但不能主动拉高——高电平由上拉电阻被动实现。
• 这意味着一台设备将 SCL 拉低后，即使另一台设备试图释放 SCL，总线也维持低电平，直到所有设备都释放为止。
• 时钟拉伸是"与逻辑"的直接产物：SCL_bus = SCL_host AND SCL_slave。

STM32 的 I2C 外设通过状态寄存器检测时钟拉伸：

三、排查流程与代码实现

3.1 示波器波形分析：确认时钟拉伸

排查时钟拉伸问题的第一步是用示波器确认 SCL 线的实际波形。需要使用双通道：

• CH1: SCL（设置为下降沿触发，触发电平 1/2 VDD）
• CH2: SDA

关键观察点：

1. 测量 SCL 低电平最大持续时间。如果超过 I2C 协议规定的最大允许值（通常为频率的倒数 × 10，如 100kHz 模式下 100μs），说明从机可能在拉伸时钟。
2. 确认上拉电阻值是否合适。过大的上拉电阻（>10kΩ）会使上升沿变缓，可能被误判为时钟拉伸。

示波器波形记录 (SHT31 高精度模式, 100kHz I2C): SCL: ────┐ ┌────┐ ┌────────── (约 15ms 低电平) ───────────┐ │─────┘ │────┘ │ SDA: │ 数据... │ │ ACK │ └───────────┘ └──┘ 分析: - SCL 低电平持续约 15ms，远超正常 10μs 的周期。 - SDA 在 SCL 低电平期间保持稳定 (高电平)。 - 符合从机时钟拉伸的特征: 从机通过 SCL=0 暂停传输。

3.2 STM32 HAL I2C 超时与重试机制

/** * @file i2c_clock_stretch_handler.c * @brief 具备时钟拉伸容错能力的 I2C 驱动实现。 * * 设计要点: * 1. 使用独立硬件定时器替代 HAL 库的软件超时。 * 软件 Delay (DWT/循环) 在低功耗模式下不工作。 * 2. 重试策略: 超时后发送 STOP 条件 + 总线复位, 然后重试。 * 连续 3 次超时判定为永久故障。 * 3. 上拉电阻适配: 在 I2C Init 后通过读取 ISR 寄存器验证 * 总线空闲状态。 */ #include "stm32h7xx_hal.h" /* 时钟拉伸最大容忍时长 (ms): 根据最慢从机数据手册设定 */ #define I2C_CLOCK_STRETCH_TIMEOUT_MS 50U /* 最大重试次数: 超过后判定为硬件故障 */ #define I2C_MAX_RETRY_COUNT 3U /* 硬件定时器句柄 (用于精确超时) */ static TIM_HandleTypeDef *p_timeout_timer = NULL; /** * @brief I2C 超时定时器中断回调。 * * 当定时器溢出时, 说明 SCL 拉伸时间超过设定阈值。 * 通过设置 I2C 句柄的 ErrorCode 通知主流程终止当前传输。 */ static void i2c_timeout_isr(I2C_HandleTypeDef *hi2c) { if (hi2c == NULL) return; /* 设置超时错误标志 */ hi2c->ErrorCode |= HAL_I2C_ERROR_TIMEOUT; /* 强制停止当前传输: 发送 STOP 条件 */ /* 注意: 在 SCL 被从机拉低的期间, STOP 条件无法发出。 * 需要通过以下步骤恢复总线控制权: * 1. 禁用 I2C 外设 (PE=0) * 2. 将 SCL 和 SDA 引脚切换为 GPIO 输出模式 * 3. 手动产生 9 个 SCL 脉冲 (让从机释放总线) * 4. 发送 STOP 条件 * 5. 重新初始化 I2C 外设 */ } /** * @brief 时钟拉伸卡死时的总线恢复流程。 * * 原理: 当从机因异常 (如掉电、复位) 在数据发送中途 * 持续将 SDA 拉低时, 主机无法发送 STOP 条件。 * 此时需要发送额外的 SCL 脉冲让从机完成当前字节传输并释放 SDA。 * * 实现: 将 SCL 引脚临时切换为 GPIO 输出, 手动翻转电平。 */ static HAL_StatusTypeDef i2c_bus_recovery(I2C_HandleTypeDef *hi2c) { GPIO_InitTypeDef GPIO_InitStruct = {0}; uint32_t scl_pin, sda_pin; GPIO_TypeDef *scl_port, *sda_port; /* Step 1: 禁用 I2C 外设 */ hi2c->Instance->CR1 &= ~I2C_CR1_PE; /* Step 2: 获取 SCL/SDA 引脚信息 */ /* (实际实现需要从 hi2c 句柄中解析引脚编号, 此处简化展示) */ scl_pin = GPIO_PIN_6; /* 示例: PB6 */ sda_pin = GPIO_PIN_7; /* 示例: PB7 */ scl_port = GPIOB; sda_port = GPIOB; /* Step 3: 将 SCL 配置为开漏输出 (模拟 I2C 主机行为) */ GPIO_InitStruct.Pin = scl_pin; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_OD; GPIO_InitStruct.Pull = GPIO_NOPULL; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(scl_port, &GPIO_InitStruct); /* Step 4: 发送 9 个时钟脉冲 */ for (int i = 0; i < 9; i++) { /* SCL = 高 → 等待上升沿稳定 → SCL = 低 */ HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_SET); /* 延时约 5μs (100kHz I2C 周期的一半) */ for (volatile int d = 0; d < 240; d++) { __NOP(); } HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_RESET); for (volatile int d = 0; d < 240; d++) { __NOP(); } } /* Step 5: 生成 STOP 条件 (SCL=高时 SDA 拉高) */ HAL_GPIO_WritePin(scl_port, scl_pin, GPIO_PIN_SET); for (volatile int d = 0; d < 120; d++) { __NOP(); } HAL_GPIO_WritePin(sda_port, sda_pin, GPIO_PIN_SET); /* STOP */ /* Step 6: 恢复 I2C 引脚配置并重新初始化外设 */ GPIO_InitStruct.Pin = scl_pin | sda_pin; GPIO_InitStruct.Mode = GPIO_MODE_AF_OD; GPIO_InitStruct.Pull = GPIO_PULLUP; GPIO_InitStruct.Alternate = GPIO_AF4_I2C1; HAL_GPIO_Init(GPIOB, &GPIO_InitStruct); hi2c->Instance->CR1 |= I2C_CR1_PE; /* 重新使能 */ /* 验证总线已释放 */ if (HAL_I2C_IsDeviceReady(hi2c, 0x00, 3, 10) != HAL_OK) { return HAL_ERROR; /* 总线仍异常 */ } return HAL_OK; } /** * @brief 带时钟拉伸容错的 I2C 内存读取。 * * @param hi2c I2C 句柄 * @param dev_addr 从机地址 (7 位, 左对齐) * @param mem_addr 内部寄存器地址 * @param mem_addr_size 地址宽度 (I2C_MEMADD_SIZE_8BIT/16BIT) * @param p_data 数据缓冲区 * @param size 读取字节数 * @param timeout_ms 总体超时 (含时钟拉伸容忍) * @return HAL_StatusTypeDef */ HAL_StatusTypeDef i2c_read_with_stretch_tolerance( I2C_HandleTypeDef *hi2c, uint16_t dev_addr, uint16_t mem_addr, uint16_t mem_addr_size, uint8_t *p_data, uint16_t size, uint32_t timeout_ms) { HAL_StatusTypeDef status; uint8_t retry_count = 0; do { /* 启动硬件超时定时器 (单次模式) */ __HAL_TIM_SET_COUNTER(p_timeout_timer, 0); HAL_TIM_Base_Start_IT(p_timeout_timer); /* 执行标准 I2C 内存读取 */ status = HAL_I2C_Mem_Read( hi2c, dev_addr, mem_addr, mem_addr_size, p_data, size, timeout_ms ); /* 停止超时定时器 */ HAL_TIM_Base_Stop_IT(p_timeout_timer); if (status == HAL_OK) { return HAL_OK; /* 成功, 直接返回 */ } /* 检查是否为时钟拉伸超时 */ if (hi2c->ErrorCode & HAL_I2C_ERROR_TIMEOUT) { /* 发送 STOP 条件重置总线状态 */ HAL_I2C_Master_Abort_IT(hi2c, dev_addr); retry_count++; if (retry_count >= I2C_MAX_RETRY_COUNT) { /* 连续超时, 可能为硬件故障, 尝试总线恢复 */ status = i2c_bus_recovery(hi2c); return (status == HAL_OK) ? HAL_ERROR : HAL_ERROR; } } else { /* 非超时错误 (NACK/BERR/ARLO), 直接返回 */ return status; } } while (retry_count < I2C_MAX_RETRY_COUNT); return HAL_ERROR; }

四、时钟拉伸的阈值设定与硬件替代方案

时钟拉伸的容错设置需要在"容忍慢速从机"和"防止总线死锁"之间权衡：

1. 超时值的设定：超时值过短（<5ms）会导致正常需要时钟拉伸的传感器（如 BME280 在强制模式下的 8ms 测量时间）被误判为故障。超时值过长（>100ms）会阻塞主程序，影响其他实时任务。推荐策略是查询从机数据手册中的最大转换时间，将超时值设为其 1.5 倍。

2. 上拉电阻的影响：上拉电阻值过大（>10kΩ）会使 SCL 上升沿变缓（RC 时间常数 τ = R_pullup × C_bus）。在快速模式（400kHz）下，上升时间要求 <300ns。如果上升沿过慢且恰好落在 I2C 外设的采样窗口之外，可能触发虚假的拉伸超时。建议标准模式使用 4.7kΩ、快速模式使用 2.2kΩ 上拉。

3. DMA 模式下的特殊考量：当 I2C 以 DMA 模式运行时，时钟拉伸期间 DMA 不会暂停——控制器等待 SCL 释放，而 DMA 引擎等待控制器完成当前传输请求。如果从机的拉伸时间超过 DMA 的 FIFO 超时，需要在外设初始化时适当延长 DMA 流控超时参数。

4. 替代方案——中断模式：对于对时钟拉伸极度敏感的场景，可以放弃 I2C 的"命令-等待-读取"模式，改为：主机发出测量命令后主动释放总线并进入等待，由从机通过独立的 IRQ 引脚（如果从机支持）通知"数据就绪"，主机再启动第二次 I2C 传输读取结果。这种方式完全规避了时钟拉伸。

5. 适用于：传感器读取（温湿度、气压、距离）、EEPROM 写入、PMIC 配置等对实时性要求宽容的场景。不适用于：需要严格时序的音频 Codec 配置、高速 ADC/DAC 数据流式传输（此时应使用 SPI 接口）。

五、总结

I2C 时钟拉伸是协议设计中的一个双刃剑特性：它赋予从机在数据未就绪时通过硬件信号暂停主机的权利，但同时引入了总线死锁的风险。排查时钟拉伸问题需要四步走：

1. 用示波器确认 SCL 低电平异常延长的波形特征，确认问题来自时钟拉伸而非电气噪声。
2. 查阅从机数据手册，获取最大转换时间和时钟拉伸时长参数。
3. 在驱动层使用硬件定时器替代软件超时循环，避免因中断关闭导致的虚假超时。
4. 实现总线恢复机制：当检测到持续的 SCL/SDA 异常时，通过 GPIO 位脉冲手动复位从机状态机。

在工程实践中，建议为所有 I2C 外设初始化时注册一个"时钟拉伸最大容忍时长"参数，由驱动框架统一管理超时和重试策略。对于采用多个 I2C 从机的系统，取所有从机中最大转换时间的 2 倍作为全局超时参数是一种保守但可靠的策略。