STM32F103 硬件 I2C 通信全流程调试实录：从寄存器配置到总线死锁恢复

文章目录

- 摘要
- 前言
- [I2C 协议核心原理](#I2C 协议核心原理)
- 硬件选型与接线
- 软件配置与寄存器映射
- - [CubeMX 配置与寄存器对照](#CubeMX 配置与寄存器对照)
  - [CCR 寄存器计算过程](#CCR 寄存器计算过程)
  - [CR1 和 CR2 关键配置](#CR1 和 CR2 关键配置)
  - 容易遗漏的步骤
  - 核心驱动代码
- 测试验证
- - 功能测试
  - [理论 vs 实测对照](#理论 vs 实测对照)
  - 上拉电阻对通信稳定性的影响
- 故障排查实录
- - [故障一：BUSY 标志卡死，START 无法生成](#故障一：BUSY 标志卡死，START 无法生成)
  - [故障二：写入成功但读回数据全为 0xFF](#故障二：写入成功但读回数据全为 0xFF)
  - [故障三：通信 intermittently 失败，错误率约 0.1%](#故障三：通信 intermittently 失败，错误率约 0.1%)
  - 故障四：多设备通信时地址冲突
- 总结
- 参考资料

摘要

STM32F103 的硬件 I2C 外设一直是嵌入式开发中的高频调试对象------总线死锁、从机无应答、波形畸变等问题在项目初期几乎不可避免。本文以 STM32F103C8T6 为平台，以 AT24C02 EEPROM 为通信对象，从 I2C 协议的时序原理出发，逐寄存器拆解 CubeMX 每个配置项背后的硬件含义，并给出完整的 HAL 库驱动代码（含返回值校验、超时保护和总线恢复）。实测在 400kHz 快速模式下，连续读写 10 000 次零错误，上拉电阻从 1kΩ 调到 10kΩ 的对比数据也一并给出。文中穿插了三次实际调试中遇到的典型故障及其完整排查过程。

前言

I2C 总线因为只需两根线就能挂接多个设备，在传感器、EEPROM、RTC 等低速外设中用得非常多。但在实际项目中，硬件 I2C 的调试体验往往不如 UART 和 SPI 顺畅------通信失败时没有直观的报错信息，示波器抓到的波形有时也很难一眼看出问题所在。

笔者在最近一个项目中需要同时挂载 EEPROM（AT24C02）、加速度计（LIS3DH）和 OLED 屏（SSD1306）三个 I2C 设备，从硬件连线到软件调通花了将近一周。期间遇到了总线死锁、BUSY 标志卡死、上拉电阻选值不当等典型问题，每一个都花了不少时间定位。

本文的目标是把这套调试经验完整记录下来：从 I2C 时序的基本原理，到 CubeMX 配置中每个参数对应的寄存器位，再到实际出问题时怎么用示波器和逻辑分析仪一步步定位。如果你正在调 I2C 通信，希望这篇文章能帮你少走一些弯路。本文完整工程代码可在 CSDN 下载频道获取（VIP 免费）。

前置条件：读者需要了解 I2C 协议的基本概念（起始条件、停止条件、ACK/NACK），有 STM32 HAL 库的基本使用经验。开发环境为 STM32CubeMX 6.9.0 + Keil MDK 5.38 + STM32F1xx HAL 库 1.8.5。

I2C 协议核心原理

信号线与数据格式

I2C 总线由 SCL（时钟线）和 SDA（数据线）两根线组成，两条线都需要外接上拉电阻。总线空闲时，SCL 和 SDA 都被拉高到高电平。通信时，主机产生 SCL 时钟，SDA 上的数据在 SCL 高电平期间必须保持稳定，只有在 SCL 低电平期间才能改变------这一点和 SPI 的 CPOL/CPHA 机制有本质区别，SPI 是主从共享时钟，而 I2C 的时钟完全由主机掌控。

起始条件（START）是 I2C 通信的起点：SCL 保持高电平时，SDA 从高到低跳变。停止条件（STOP）则相反：SCL 保持高电平时，SDA 从低到高跳变。这两个特殊条件不占用数据位，它们的存在让从机能够识别一帧传输的开始和结束。

寻址与数据传输方向

起始条件之后，主机发送的第一个字节是 7 位从机地址加 1 位读写位。读写位为 0 表示写操作（主机→从机），为 1 表示读操作（从机→主机）。以 AT24C02 为例，其器件地址为 1010，加上 A2/A1/A0 三个引脚的电平（本例全部接地，即 000），完整地址字节为 10100000（0xA0），写操作；读操作则为 10100001（0xA1）。

从机收到与自己地址匹配的字节后，会在第 9 个时钟周期拉低 SDA 发送 ACK 应答。如果主机收到的是 NACK，通常意味着从机不在线、地址错误或从机忙。

主机发送与接收状态流转

#mermaid-svg-wol8CXvZ5QYw5ABs{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-wol8CXvZ5QYw5ABs .error-icon{fill:#552222;}#mermaid-svg-wol8CXvZ5QYw5ABs .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-wol8CXvZ5QYw5ABs .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-wol8CXvZ5QYw5ABs .marker{fill:#333333;stroke:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs .marker.cross{stroke:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-wol8CXvZ5QYw5ABs p{margin:0;}#mermaid-svg-wol8CXvZ5QYw5ABs defs #statediagram-barbEnd{fill:#333333;stroke:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs g.stateGroup text{fill:#9370DB;stroke:none;font-size:10px;}#mermaid-svg-wol8CXvZ5QYw5ABs g.stateGroup text{fill:#333;stroke:none;font-size:10px;}#mermaid-svg-wol8CXvZ5QYw5ABs g.stateGroup .state-title{font-weight:bolder;fill:#131300;}#mermaid-svg-wol8CXvZ5QYw5ABs g.stateGroup rect{fill:#ECECFF;stroke:#9370DB;}#mermaid-svg-wol8CXvZ5QYw5ABs g.stateGroup line{stroke:#333333;stroke-width:1;}#mermaid-svg-wol8CXvZ5QYw5ABs .transition{stroke:#333333;stroke-width:1;fill:none;}#mermaid-svg-wol8CXvZ5QYw5ABs .stateGroup .composit{fill:white;border-bottom:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs .stateGroup .alt-composit{fill:#e0e0e0;border-bottom:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs .state-note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-wol8CXvZ5QYw5ABs .state-note text{fill:black;stroke:none;font-size:10px;}#mermaid-svg-wol8CXvZ5QYw5ABs .stateLabel .box{stroke:none;stroke-width:0;fill:#ECECFF;opacity:0.5;}#mermaid-svg-wol8CXvZ5QYw5ABs .edgeLabel .label rect{fill:#ECECFF;opacity:0.5;}#mermaid-svg-wol8CXvZ5QYw5ABs .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wol8CXvZ5QYw5ABs .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-wol8CXvZ5QYw5ABs .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wol8CXvZ5QYw5ABs .edgeLabel .label text{fill:#333;}#mermaid-svg-wol8CXvZ5QYw5ABs .label div .edgeLabel{color:#333;}#mermaid-svg-wol8CXvZ5QYw5ABs .stateLabel text{fill:#131300;font-size:10px;font-weight:bold;}#mermaid-svg-wol8CXvZ5QYw5ABs .node circle.state-start{fill:#333333;stroke:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs .node .fork-join{fill:#333333;stroke:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs .node circle.state-end{fill:#9370DB;stroke:white;stroke-width:1.5;}#mermaid-svg-wol8CXvZ5QYw5ABs .end-state-inner{fill:white;stroke-width:1.5;}#mermaid-svg-wol8CXvZ5QYw5ABs .node rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs .node polygon{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs #statediagram-barbEnd{fill:#333333;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-cluster rect{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wol8CXvZ5QYw5ABs .cluster-label,#mermaid-svg-wol8CXvZ5QYw5ABs .nodeLabel{color:#131300;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-cluster rect.outer{rx:5px;ry:5px;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-state .divider{stroke:#9370DB;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-state .title-state{rx:5px;ry:5px;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-cluster.statediagram-cluster .inner{fill:white;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-cluster.statediagram-cluster-alt .inner{fill:#f0f0f0;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-cluster .inner{rx:0;ry:0;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-state rect.basic{rx:5px;ry:5px;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-state rect.divider{stroke-dasharray:10,10;fill:#f0f0f0;}#mermaid-svg-wol8CXvZ5QYw5ABs .note-edge{stroke-dasharray:5;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-note rect{fill:#fff5ad;stroke:#aaaa33;stroke-width:1px;rx:0;ry:0;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-note text{fill:black;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram-note .nodeLabel{color:black;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagram .edgeLabel{color:red;}#mermaid-svg-wol8CXvZ5QYw5ABs #dependencyStart,#mermaid-svg-wol8CXvZ5QYw5ABs #dependencyEnd{fill:#333333;stroke:#333333;stroke-width:1;}#mermaid-svg-wol8CXvZ5QYw5ABs .statediagramTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-wol8CXvZ5QYw5ABs :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 总线释放(SCL=1,SDA=1)
主机发起通信
START条件建立
7位地址+R/W位
ACK(写模式)
ACK(读模式)
NACK
主机继续读
主机读完最后一字节
空闲
发送START
发送地址
等待ACK
发送数据
接收数据
错误处理
发送ACK
发送NACK
发送STOP

这个状态流转是理解后续所有寄存器配置和故障排查的基础。每一步状态切换都对应着 STM32 I2C 外设内部状态机（由 SR1 和 SR2 寄存器反映）的特定标志位变化。

一次完整的写操作时序

以向 AT24C02 地址 0x10 写入数据 0x5A 为例，主机发起的完整时序如下：
AT24C02 从机 STM32 主机 AT24C02 从机 STM32 主机 #mermaid-svg-CeHtSgQV14D8hmaK{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-CeHtSgQV14D8hmaK .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-CeHtSgQV14D8hmaK .error-icon{fill:#552222;}#mermaid-svg-CeHtSgQV14D8hmaK .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-CeHtSgQV14D8hmaK .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-CeHtSgQV14D8hmaK .marker{fill:#333333;stroke:#333333;}#mermaid-svg-CeHtSgQV14D8hmaK .marker.cross{stroke:#333333;}#mermaid-svg-CeHtSgQV14D8hmaK svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-CeHtSgQV14D8hmaK p{margin:0;}#mermaid-svg-CeHtSgQV14D8hmaK .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CeHtSgQV14D8hmaK text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-CeHtSgQV14D8hmaK .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CeHtSgQV14D8hmaK .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-CeHtSgQV14D8hmaK .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-CeHtSgQV14D8hmaK .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-CeHtSgQV14D8hmaK #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-CeHtSgQV14D8hmaK .sequenceNumber{fill:white;}#mermaid-svg-CeHtSgQV14D8hmaK #sequencenumber{fill:#333;}#mermaid-svg-CeHtSgQV14D8hmaK #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-CeHtSgQV14D8hmaK .messageText{fill:#333;stroke:none;}#mermaid-svg-CeHtSgQV14D8hmaK .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CeHtSgQV14D8hmaK .labelText,#mermaid-svg-CeHtSgQV14D8hmaK .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-CeHtSgQV14D8hmaK .loopText,#mermaid-svg-CeHtSgQV14D8hmaK .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-CeHtSgQV14D8hmaK .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-CeHtSgQV14D8hmaK .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-CeHtSgQV14D8hmaK .noteText,#mermaid-svg-CeHtSgQV14D8hmaK .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-CeHtSgQV14D8hmaK .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CeHtSgQV14D8hmaK .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CeHtSgQV14D8hmaK .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-CeHtSgQV14D8hmaK .actorPopupMenu{position:absolute;}#mermaid-svg-CeHtSgQV14D8hmaK .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-CeHtSgQV14D8hmaK .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-CeHtSgQV14D8hmaK .actor-man circle,#mermaid-svg-CeHtSgQV14D8hmaK line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-CeHtSgQV14D8hmaK :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 内部编程周期 ~5ms START 条件 (SDA↓ while SCL=1) 地址字节 0xA0 (1010 0000, W=0) ACK (第9个时钟拉低SDA) 内存地址 0x10 ACK 数据字节 0x5A ACK STOP 条件 (SDA↑ while SCL=1)

读操作的时序稍有不同：主机先发送地址字节和内存地址（与写操作相同），然后发送 Repeated START，再发送读地址字节 0xA1（R/W=1），之后从机在每个时钟周期输出一个数据位，主机发送 ACK 表示继续读，最后一个字节后主机发送 NACK 并紧跟 STOP 条件。

标准模式与快速模式对比

参数	标准模式（Sm）	快速模式（Fm）
SCL 频率	100 kHz	400 kHz
上升时间要求	≤1000 ns	≤300 ns
下降时间要求	≤300 ns	≤300 ns
总线电容	≤400 pF	≤400 pF
典型上拉电阻	4.7 kΩ	2.2~4.7 kΩ

本文以快速模式（400kHz）为例进行配置和测试。选择快速模式而非标准模式的原因是：项目中有三个 I2C 设备，标准模式下完成一轮三设备轮询需要约 300μs，快速模式下缩短到约 80μs，对主循环的阻塞更小。

相关阅读：STM32硬件I2C主从通信实战：从零搭建到避坑指南 --- 对硬件 I2C 的完整配置流程有很好的补充

硬件选型与接线

核心器件

本设计使用 STM32F103C8T6 作为主控，AT24C02（2Kbit I2C EEPROM）作为通信对象。选择 AT24C02 的原因很简单：它是最常见的 I2C 从设备，协议简单（只有字节写和页写两种写操作），适合用来验证 I2C 通信的可靠性。

接线方案

STM32 引脚	连接目标	说明
PB6	AT24C02 SCL	I2C1 时钟线
PB7	AT24C02 SDA	I2C1 数据线
3.3V	AT24C02 VCC	供电 3.3V
GND	AT24C02 GND	共地
GND	AT24C02 A0/A1/A2	地址引脚全部接地，器件地址 = 0xA0
3.3V	SCL 上拉	通过上拉电阻接 3.3V
3.3V	SDA 上拉	通过上拉电阻接 3.3V

上拉电阻的选择

上拉电阻的取值直接影响 I2C 波形的上升时间和通信可靠性。阻值太小，低电平_VOL 可能超标（规范要求 ≤0.4V）；阻值太大，上升沿太缓，400kHz 下可能无法满足 ≤300ns 的要求。

这里涉及一个配置级决策：为什么选 4.7kΩ 而不是 1kΩ 或 10kΩ？STM32F103 的 GPIO 输出低电平驱动能力典型值为 8mA（灌电流），按 V_OL ≤ 0.4V 计算，最小允许电阻 = 3.3V / 8mA ≈ 412Ω。而上升时间 t_r 与总线电容 C_b 和上拉电阻 R_p 的关系近似为 t_r ≈ 0.8473 × R_p × C_b。假设板级寄生电容约 100pF，用 4.7kΩ 时 t_r ≈ 398ns（略超 300ns 规范但实测可用），用 2.2kΩ 时 t_r ≈ 186ns（满足规范）。

实际测试中，我用 1kΩ、2.2kΩ、4.7kΩ 和 10kΩ 四种阻值分别测试了 400kHz 通信的稳定性，结果如下：

上拉电阻	上升时间（实测）	低电平 VOL（实测）	400kHz 通信	建议
1 kΩ	85 ns	0.12 V	稳定	可用，但功耗偏大
2.2 kΩ	180 ns	0.18 V	稳定	推荐（快速模式）
4.7 kΩ	380 ns	0.22 V	偶发错误	标准模式可用
10 kΩ	820 ns	0.25 V	频繁失败	不推荐用于 400kHz

最终选用 2.2kΩ。这个结果也说明，数据手册上推荐的 4.7kΩ 在标准模式下没问题，但快速模式下偏保守。

相关阅读：STM32模拟I²C通信时上拉电阻的配置技巧 --- 不同总线电容下的上拉电阻计算方法

软件配置与寄存器映射

CubeMX 配置与寄存器对照

CubeMX 极大简化了外设配置流程，但"简化"也意味着很多关键参数被藏在图形界面背后。下面逐项说明每个配置对应的寄存器含义，这样即使不用 CubeMX，也能直接操作寄存器。

I2C1 基本配置（I2C 选项卡）：

CubeMX 配置项	设置值	对应寄存器	说明
I2C Speed Mode	Fast Mode	---	选择快速模式（400kHz）
I2C Clock Speed (Hz)	400000	I2C_CCR	目标 SCL 频率
Duty Cycle	Duty2/1	I2C_CCR $14$ (DUTY)	快速模式下 T_low/T_high = 2:1
Rise Time (ns)	300	I2C_TRISE	最大上升时间配置

时钟源配置：

I2C 外设时钟来自 APB1。STM32F103 的 APB1 时钟在本文配置中为 36MHz（HCLK=72MHz，APB1 二分频）。I2C_CCR 和 I2C_TRISE 寄存器的时基来自这个 36MHz 时钟，由 I2C_CR2 的 FREQ $5:0$ 位记录（值为 36，单位 MHz）。

CCR 寄存器计算过程

CCR（Clock Control Register）的值决定了 SCL 的高低电平持续时间。快速模式下，当 DUTY=0（T_low/T_high = 2:1）时：

复制代码

T_high = CCR × T_PCLK1
T_low  = 2 × CCR × T_PCLK1
T_scl  = T_high + T_low = 3 × CCR × T_PCLK1

其中 T_PCLK1 = 1/36MHz ≈ 27.78ns。目标 SCL = 400kHz，即 T_scl = 2.5μs：

复制代码

CCR = T_scl / (3 × T_PCLK1) = 2500ns / (3 × 27.78ns) ≈ 30

验证：T_high = 30 × 27.78 = 833ns，T_low = 60 × 27.78 = 1667ns，T_scl = 2500ns → f_SCL = 400kHz。

TRISE 寄存器的值限制上升时间：最大允许 TRISE = (最大上升时间 / T_PCLK1) + 1 = (300ns / 27.78ns) + 1 ≈ 11.8，取整为 11。

CR1 和 CR2 关键配置

寄存器	位	名称	设置	说明
CR1	0	PE	1	I2C 外设使能
CR1	10	ACK	1	ACK 应答使能
CR1	11	POS	0	ACK 作用于当前字节（非下一字节）
CR1	13	START	软件写1	产生起始条件
CR1	14	STOP	软件写1	产生停止条件
CR2	5:0	FREQ	36	APB1 时钟频率（MHz）
CR2	12:10	ITERREN	1	错误中断使能
CR2	13:10	ITEVTEN	1	事件中断使能

容易遗漏的步骤

CubeMX 生成的初始化代码中有几个容易被忽略但必须手动补充的环节：

1. I2C 复位后必须等待 BUSY 标志清零

STM32F1 的 I2C 外设在复位后，SR2 的 BUSY 标志可能因为引脚电平不稳定而置位。如果此时直接发起通信，START 条件无法生成。HAL 库的 HAL_I2C_Init() 内部会检查 BUSY 标志，但如果引脚配置顺序不对（先配 I2C 功能再配 GPIO 开漏模式），BUSY 会一直卡着。正确的初始化顺序是：先配置 GPIO 为开漏输出，再初始化 I2C 外设，最后调用 __HAL_I2C_DISABLE() 再 __HAL_I2C_ENABLE() 做一次软复位。

2. GPIO 开漏模式配置

I2C 的 SCL 和 SDA 必须配置为开漏输出（Open-Drain），不能是推挽输出。推挽模式下，当从机试图拉低 SDA 发送 ACK 时，会与主机的推挽高电平形成短路，可能导致 GPIO 损坏。CubeMX 通常会自动配置为开漏模式，但如果在代码中手动修改了 GPIO 配置，务必确认这一点。

3. 时钟使能不能遗漏

__HAL_RCC_I2C1_CLK_ENABLE() 必须在 GPIO 和 I2C 初始化之前调用。如果遗漏，所有寄存器写入都是无效的，但不会有任何报错------这是 HAL 库"静默失败"的典型表现。

核心驱动代码

c 复制代码

/* ============================================================
 * I2C1 初始化（CubeMX 生成 + 手动补充的恢复逻辑）
 * 硬件：STM32F103C8T6, APB1 = 36MHz
 * ============================================================ */
static void MX_I2C1_Init(void)
{
    hi2c1.Instance             = I2C1;
    hi2c1.Init.ClockSpeed      = 400000;           /* 400kHz 快速模式 */
    hi2c1.Init.DutyCycle       = I2C_DUTYCYCLE_2;  /* T_low/T_high = 2:1 */
    hi2c1.Init.OwnAddress1     = 0x00;             /* 主机模式，不使用从机地址 */
    hi2c1.Init.AddressingMode  = I2C_ADDRESSINGMODE_7BIT;
    hi2c1.Init.DualAddressMode = I2C_DUALADDRESS_DISABLE;
    hi2c1.Init.GeneralCallMode = I2C_GENERALCALL_DISABLE;
    hi2c1.Init.NoStretchMode   = I2C_NOSTRETCH_DISABLE; /* 允许时钟拉伸 */

    if (HAL_I2C_Init(&hi2c1) != HAL_OK)
    {
        Error_Handler();  /* 初始化失败必须捕获，不能静默继续 */
    }

    /* 关键：配置模拟滤波器，滤除 50ns 以下的毛刺 */
    if (HAL_I2CEx_ConfigAnalogFilter(&hi2c1, I2C_ANALOGFILTER_ENABLE) != HAL_OK)
    {
        Error_Handler();
    }

    /* 关键：数字滤波器配置为 2 个 PCLK 周期 */
    if (HAL_I2CEx_ConfigDigitalFilter(&hi2c1, 2) != HAL_OK)
    {
        Error_Handler();
    }
}

/* ============================================================
 * AT24C02 单字节写入
 * 参数：mem_addr --- EEPROM 内部地址（0~255）
 *       data     --- 待写入字节
 * 返回：HAL_StatusTypeDef
 * ============================================================ */
HAL_StatusTypeDef EEPROM_WriteByte(uint16_t mem_addr, uint8_t data)
{
    HAL_StatusTypeDef status;

    /* 器件地址：1010 + A2A1A0(000) + W(0) = 0xA0 */
    status = HAL_I2C_Mem_Write(&hi2c1,
                               0xA0,              /* DevAddress */
                               mem_addr,          /* MemAddress */
                               I2C_MEMADD_SIZE_8BIT,
                               &data,             /* pData */
                               1,                 /* Size */
                               100);              /* Timeout: 100ms */

    if (status != HAL_OK)
    {
        /* 通信失败时执行总线恢复 */
        I2C_BusRecovery();
        return status;
    }

    /* AT24C02 写入周期最大 5ms，必须等待 */
    HAL_Delay(5);
    return HAL_OK;
}

/* ============================================================
 * AT24C02 随机读取
 * 内部先写地址字节，再重复起始后读数据
 * ============================================================ */
HAL_StatusTypeDef EEPROM_ReadByte(uint16_t mem_addr, uint8_t *pData)
{
    HAL_StatusTypeDef status;

    status = HAL_I2C_Mem_Read(&hi2c1,
                              0xA0,
                              mem_addr,
                              I2C_MEMADD_SIZE_8BIT,
                              pData,
                              1,
                              100);

    if (status != HAL_OK)
    {
        I2C_BusRecovery();
        return status;
    }
    return HAL_OK;
}

/* ============================================================
 * I2C 总线恢复函数
 * 场景：从机意外拉低 SDA 导致总线死锁
 * 原理：手动发送 9 个 SCL 脉冲，让从机释放 SDA
 * ============================================================ */
void I2C_BusRecovery(void)
{
    GPIO_InitTypeDef GPIO_InitStruct = {0};

    /* 第一步：禁用 I2C 外设，释放 GPIO */
    __HAL_I2C_DISABLE(&hi2c1);

    /* 第二步：将 SCL 配置为推挽输出，SDA 配置为输入 */
    GPIO_InitStruct.Pin   = GPIO_PIN_6;  /* PB6 = SCL */
    GPIO_InitStruct.Mode  = GPIO_MODE_OUTPUT_PP;
    GPIO_InitStruct.Pull  = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH;
    HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

    GPIO_InitStruct.Pin  = GPIO_PIN_7;   /* PB7 = SDA */
    GPIO_InitStruct.Mode = GPIO_MODE_INPUT;
    GPIO_InitStruct.Pull = GPIO_PULLUP;
    HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

    /* 第三步：发送最多 9 个 SCL 脉冲，直到 SDA 释放 */
    for (uint8_t i = 0; i < 9; i++)
    {
        if (HAL_GPIO_ReadPin(GPIOB, GPIO_PIN_7) == GPIO_PIN_SET)
        {
            break;  /* SDA 已释放，停止发脉冲 */
        }
        HAL_GPIO_WritePin(GPIOB, GPIO_PIN_6, GPIO_PIN_RESET);
        HAL_Delay(1);  /* 约 1ms 半周期，足够慢 */
        HAL_GPIO_WritePin(GPIOB, GPIO_PIN_6, GPIO_PIN_SET);
        HAL_Delay(1);
    }

    /* 第四步：发送 STOP 条件（SDA 低→高，SCL 高） */
    GPIO_InitStruct.Pin  = GPIO_PIN_7;
    GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
    HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

    HAL_GPIO_WritePin(GPIOB, GPIO_PIN_7, GPIO_PIN_RESET);
    HAL_Delay(1);
    HAL_GPIO_WritePin(GPIOB, GPIO_PIN_6, GPIO_PIN_SET);
    HAL_Delay(1);
    HAL_GPIO_WritePin(GPIOB, GPIO_PIN_7, GPIO_PIN_SET);  /* STOP: SDA↑ while SCL=1 */
    HAL_Delay(1);

    /* 第五步：恢复 GPIO 为 I2C 开漏复用模式 */
    GPIO_InitStruct.Pin       = GPIO_PIN_6 | GPIO_PIN_7;
    GPIO_InitStruct.Mode      = GPIO_MODE_AF_OD;
    GPIO_InitStruct.Pull      = GPIO_PULLUP;
    GPIO_InitStruct.Speed     = GPIO_SPEED_FREQ_HIGH;
    HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);

    /* 第六步：重新使能 I2C 外设 */
    __HAL_I2C_ENABLE(&hi2c1);
}

上面这段总线恢复代码中，初始化顺序有严格的依赖关系：必须先禁用 I2C 外设再操作 GPIO，恢复 GPIO 后重新使能 I2C。如果顺序反了，I2C 外设会抢占 GPIO 控制权，手动脉冲无法生效。

相关阅读：I2C死锁排查：总线卡死不要直接断电，手动翻SCL恢复通信的完整过程 --- 对总线死锁的排查思路有更详细的展开

测试验证

功能测试

在 400kHz 快速模式下，对 AT24C02 的 0~255 地址空间执行"写入→读回→比对"的完整循环。测试代码在 main 函数的 while(1) 中运行，每轮写入一个递增的 pattern 值，立即读回并通过 UART 打印结果。

c 复制代码

/* 主循环中的测试逻辑 */
uint8_t write_pattern = 0;
uint32_t error_count  = 0;
uint32_t total_count  = 0;

while (1)
{
    for (uint16_t addr = 0; addr < 256; addr++)
    {
        uint8_t tx_data = (uint8_t)(write_pattern + addr);

        if (EEPROM_WriteByte(addr, tx_data) != HAL_OK)
        {
            error_count++;
            printf("[ERR] Write fail @ addr=%d, pattern=0x%02X\r\n",
                   addr, tx_data);
        }

        uint8_t rx_data = 0;
        if (EEPROM_ReadByte(addr, &rx_data) != HAL_OK)
        {
            error_count++;
            printf("[ERR] Read fail @ addr=%d\r\n", addr);
        }
        else if (rx_data != tx_data)
        {
            error_count++;
            printf("[ERR] Mismatch @ addr=%d: expect=0x%02X, got=0x%02X\r\n",
                   addr, tx_data, rx_data);
        }

        total_count++;
    }

    write_pattern++;
    printf("[OK] Round %d done, total=%lu, errors=%lu\r\n",
           write_pattern, total_count, error_count);
}

连续运行 40 轮（每轮 256 字节，共 10240 次读写），错误计数为 0。UART 输出如下：

复制代码

[OK] Round 1 done, total=256, errors=0
[OK] Round 2 done, total=512, errors=0
...
[OK] Round 40 done, total=10240, errors=0

理论 vs 实测对照

对照 1 --- 时序参数：

参数	理论值（CCR 计算）	实测值（逻辑分析仪）	偏差	原因
SCL 周期	2500 ns	2498 ns	-0.08%	APB1 时钟精度
T_high	833 ns	835 ns	+0.24%	同上
T_low	1667 ns	1663 ns	-0.24%	同上
起始条件保持时间	≥4.7μs（规范）	5.2μs	---	HAL 库内部延时

对照 2 --- 写入时间：

操作	理论值	实测值	说明
单字节写入（含 HAL 开销）	~0.5 ms	0.62 ms	HAL 状态机轮询开销
单字节写入（含 EEPROM 写入周期）	5 ms	5.0 ms	AT24C02 数据手册典型值
单字节读取	~0.3 ms	0.38 ms	含地址发送+数据接收

两处对照的偏差均在可接受范围内。时序偏差主要来自 APB1 时钟源（内部 RC 振荡器 vs 外部晶振）的精度差异，如果项目对时序精度要求高，建议使用外部晶振（HSE）。

上拉电阻对通信稳定性的影响

前文已经给出了四种阻值的静态参数对比。这里进一步测试了在不同上拉电阻下，连续通信 10000 次的错误率：

上拉电阻	线长 10cm 错误率	线长 30cm 错误率	线长 50cm 错误率
1 kΩ	0/10000	0/10000	2/10000
2.2 kΩ	0/10000	0/10000	12/10000
4.7 kΩ	3/10000	47/10000	386/10000
10 kΩ	156/10000	1240/10000	3720/10000

线长增加相当于增大了总线寄生电容，上升时间变长，错误率明显上升。这组数据说明：在 400kHz 下，如果走线较长（>30cm），上拉电阻应选 2.2kΩ 甚至更低；短距离走线可以用 4.7kΩ 但需要验证稳定性。

故障排查实录

故障一：BUSY 标志卡死，START 无法生成

现象：系统上电后第一次 I2C 通信就失败，HAL_I2C_Mem_Write 返回 HAL_BUSY。用万用表测量 SDA 引脚为低电平（约 0.3V），SCL 为高电平。

排查过程 ：最初以为是 AT24C02 没有上电，用万用表测 VCC 引脚确认是 3.28V，排除供电问题。然后怀疑是上电时序问题------STM32 启动比 AT24C02 快，可能在 AT24C02 还没准备好时主机就开始通信了。在 HAL_I2C_Init() 前面加了 100ms 延时，问题依旧。

接着用示波器抓取上电瞬间的波形，发现 STM32 的 PB7（SDA）在上电过程中有一个短暂的低电平脉冲（约 2μs），这是因为 GPIO 在复位默认状态下是浮空输入，而 I2C 外设此时还未初始化，SDA 线上的噪声被 AT24C02 误判为 START 条件，AT24C02 进入接收状态并拉低 SDA 等待后续时钟。但主机此时还没开始通信，SCL 保持高电平，AT24C02 就一直拉着 SDA 不放------这就是 BUSY 标志卡死的根因。

解决方案 ：在 HAL_I2C_Init() 之前，先将 PB6/PB7 配置为推挽输出并输出高电平，维持 1ms 后再切换为开漏复用模式。这样上电过程中 SDA 不会被意外拉低。另外，在初始化代码中增加了 BUSY 超时检测：如果 BUSY 标志超过 10ms 未清零，执行一次总线恢复。

故障二：写入成功但读回数据全为 0xFF

现象：EEPROM_WriteByte(0x10, 0x5A) 返回 HAL_OK，但紧接着 EEPROM_ReadByte(0x10, &rx) 读回的值为 0xFF。

排查过程：首先确认写入操作确实返回了 HAL_OK，说明 I2C 通信链路是通的。怀疑是写入没有真正生效------AT24C02 的写入需要内部编程周期（最大 5ms），如果在写入完成前就发起读操作，可能读到的是写入前的值（0xFF 是 EEPROM 擦除后的默认值）。

用逻辑分析仪抓取波形发现，写入完成后立即发起读操作，两次操作之间没有间隔。AT24C02 在收到 STOP 条件后开始内部编程，此时如果主机马上发 START，AT24C02 不会响应地址（因为它正忙于写入），但 HAL 库的 HAL_I2C_Mem_Read 设置了 100ms 超时，在超时之前 AT24C02 完成了写入并响应了读请求------所以读到的应该是写入后的值才对。

进一步检查发现，问题出在地址上：写入时 mem_addr = 0x10，但读操作调用时误写成了 EEPROM_ReadByte(0x100, &rx)------地址 0x100 超出了 AT24C02 的 256 字节地址空间（2Kbit = 256 字节），地址回绕到了 0x00，而 0x00 地址没有被写入过，所以读到 0xFF。

解决方案：修正地址参数，并在读取函数中增加地址范围检查：

c 复制代码

if (mem_addr >= 256)  /* AT24C02 地址空间 0~255 */
{
    return HAL_ERROR;
}

故障三：通信 intermittently 失败，错误率约 0.1%

现象：长时间运行（>1小时）后，偶尔出现 HAL_ERROR 返回，没有规律。

排查过程：错误率很低（约 1/1000），首先怀疑是电磁干扰。用示波器观察 SCL/SDA 波形，发现偶尔有一个时钟周期的 SCL 高电平期间，SDA 上出现了一个约 50ns 的尖峰毛刺。这个毛刺可能是附近开关电源的噪声耦合到 I2C 走线上。

查看 STM32 参考手册 RM0008 的 I2C 章节，确认 STM32F1 的 I2C 外设内置了模拟滤波器和数字滤波器。模拟滤波器可以滤除 50ns 以下的毛刺，数字滤波器可以配置滤除 1~15 个 PCLK 周期的毛刺。初始代码中只开启了模拟滤波器，没有配置数字滤波器。

解决方案：在初始化代码中增加数字滤波器配置（已在上面的核心代码中体现），设置为滤除 2 个 PCLK 周期（约 56ns）以下的毛刺。配置后连续运行 24 小时，错误计数为 0。

故障四：多设备通信时地址冲突

现象：单独通信时 AT24C02 和 LIS3DH 都正常，但挂到同一条 I2C 总线上后，LIS3DH 通信失败。

排查过程：用逻辑分析仪抓取波形，发现主机发送 LIS3DH 的地址 0x32（写）后，AT24C02 也在总线上响应了------因为 AT24C02 的地址是 0xA0，与 0x32 不冲突，理论上不应该响应。

进一步检查发现，LIS3DH 的 SA0 引脚悬空了，导致其地址不确定（SA0 悬空时内部弱上拉，地址可能是 0x32 也可能是 0x30）。将 SA0 明确接到 GND 后，地址固定为 0x32，通信恢复正常。

这个故障的教训是：I2C 从设备的地址配置引脚绝对不能悬空，必须明确接高或接低。悬空状态下，引脚电平受寄生电荷和漏电流影响，可能在上电时随机确定，导致地址不可预测。

总结

本文围绕 STM32F103 的硬件 I2C 通信，从协议原理到寄存器配置、从驱动代码到实际调试，完整记录了一套可复用的工程实践。几个核心要点值得强调：上拉电阻的取值不是"随便选个 4.7kΩ"，快速模式下 2.2kΩ 更稳妥；CubeMX 生成的代码必须补充 BUSY 标志检测和总线恢复逻辑，否则上电死锁是大概率事件；所有 HAL 函数的返回值都必须检查，静默失败是 I2C 调试中最难排查的隐患。

本文的方案适用于 STM32F1 系列的硬件 I2C1/I2C2 外设，对于 STM32F4、STM32L4 等系列，I2C 外设的寄存器布局有所不同（特别是 TIMINGR 寄存器取代了 CCR/TRISE），但调试思路和总线恢复方法是通用的。

已知的局限性：本文没有覆盖 I2C 从机模式的实现（STM32 可以作为从机响应其他主机的请求），也没有讨论 DMA 方式传输 I2C 数据（适合大数据量场景如 OLED 刷屏）。此外，10-bit 地址寻址模式在本文中未涉及。

如需获取本文完整代码和更多实战项目，可开通 CSDN 技术会员。

版本备注

硬件平台：STM32F103C8T6 + AT24C02（ST 原装 + 国产兼容 tested）

软件版本：STM32CubeMX 6.9.0 + Keil MDK 5.38 + STM32F1xx HAL 1.8.5

兼容说明：STM32F103 全系列（C8T6/RCT6/ZET6）可直接使用；STM32F4/L4 系列需调整 I2C 寄存器配置（TIMINGR 方式）；GD32F103 基本兼容但 I2C 外设行为有细微差异

API 变更风险：HAL 库 1.8.x 的 HAL_I2C_Mem_Write/Read 函数签名与 1.6.x 一致，但内部超时处理逻辑有变化------1.6.x 在超时时不清理 BUSY 标志，1.8.x 会自动清理。如果从旧版本升级，注意检查超时后的总线状态

参考资料

ST RM0008: STM32F103xx Reference Manual, Chapter 26 I2C
ST AN2820: I2C bus expansion with GPIO on STM32 microcontroller
AT24C02 Datasheet (Microchip), Rev. 2023A
NXP UM10204: I2C-bus specification and user manual, Rev. 6

相关阅读：

嵌入式开发实战：I2C死锁的5种常见场景及快速恢复技巧 --- 5 种死锁场景的分类和对应恢复策略

当模拟I2C读取AS5600数据不稳?手把手教你用逻辑分析仪抓波形并调试STM32代码 --- 逻辑分析仪抓 I2C 波形的实操方法

别再只重启了！给IIC从机加个'看门狗'：用STM32 HAL库实现通信超时自动恢复 --- 超时自动恢复的完整实现方案