简介：面向STM32开发者的I2C从机模式配置资料，基于STM32F103与HAL库，适合需要掌握I2C协议从机通信、中断处理及调试方法的嵌入式工程师。压缩包共918个文件，以C源码、H头文件为主，辅以链接脚本、Keil工程配置与说明文档，整体约7.7MB，可直接对照工程文件学习从机地址配置、地址匹配中断开启、从机收发回调处理等关键环节。已有2466人学习下载。资料内含HAL库完整工程，覆盖从机初始化、中断服务与错误诊断，可快速复现从机收发流程；通过逻辑分析仪观察SDA/SCL时序，能帮助读者理解时钟同步、数据速率与ACK信号机制，避开地址冲突、总线挂死等常见问题。无论是课程设计还是产品原型验证，都能提供直接可用的代码参考与排错思路，适合入门到进阶的实践学习。 做嵌入式这几年，I2C算是打交道最多的总线之一。以前接传感器、接OLED屏，全是让STM32当主机主动往外发命令。直到最近做一个项目，STM32要被另一块主控板当成外设来轮询读取数据，我才把HAL库的I2C从机模式完整摸了一遍，中间踩了不少坑，有些坑甚至在中文资料里都很难搜到。这篇就把I2C从机模式的完整思路、核心配置和实操代码整理出来，给正准备做类似功能的你省点时间。
如果你要把STM32作为I2C从机接入现有系统，比如给树莓派、另一个MCU或者Linux主控提从设备，这篇文章会涉及从CubeMX配置到HAL库API调用，再到双机联调的完整流程，适合已经会跑I2C主机模式、但还没接过从机方向的开发者。
1. 从机模式到底是什么：先搞懂I2C的角色反转
1.1 主机问、从机答：I2C协议里的角色与地址
I2C是半双工同步通信，只有两根线，SCL时钟线和SDA数据线。所有设备都挂在同一条总线上，靠地址区分彼此。主机负责产生时钟、发起通信、决定什么时候结束通信，也就是整个通信的节奏控制方。从机则是被动的一方，被主机点名后才有机会发送或接收数据。
每个从机都有一个唯一的7位地址，比如0x33。主机发起通信时，先发送一个地址字节，这个字节的高7位是从机地址，最低位是读写方向标记：0表示主机要写数据给从机，1表示主机要从从机读数据。所以实际操作中0x33这个7位地址，在总线上体现为0x66（写）或者0x67（读）。这个左移1位的操作，正是新手最容易踩的坑，后面会详细说。
从机模式的关键在于：STM32不再主动发起传输，而是靠硬件检测到自己地址被匹配，然后触发中断，告诉CPU“有人叫你了”，CPU再根据请求方向去准备接收或者发送数据。听起来简单，但HAL库里从机模式的函数调用和中断回调流程，和主机模式差异非常大，如果不理解状态流程，代码很容易跑飞。
1.2 什么时候需要STM32做从机：典型应用场景
一个很常见的场景是：系统里有一颗主控MCU（性能强、资源多），它需要读取多个传感器模块的数据，每个模块用一颗STM32来做数据采集和预处理，这些STM32都被配置为I2C从机，主控通过I2C总线轮询每个从机地址来获取数据。这种结构下，STM32从机就相当于一个“智能传感器节点”，既减轻了主控的计算压力，又能分布式部署。
另一种场景是把STM32当成一个I2C外设扩展器。比如OLED屏、EEPROM、温湿度传感器都是I2C接口，当主机资源不够或者需要更多IO时，用一颗STM32作为智能外设，对外暴露I2C接口，对内可以接各种低速外设，甚至做协议转换。这本质上就是自己造一个“复合I2C设备”的过程。
我这次的项目就是第一种场景。一块ARM主控板通过I2C轮询读取两个STM32节点上报的状态数据，每个节点有独立的从机地址，节点内部完成ADC采样和数据处理，只在被询问时把最新结果送回总线。这就意味着STM32从机端代码必须足够健壮，任何一个字节的处理不当都可能卡住整条总线，影响另一个从机节点的正常通信。
2. 核心细节与工程配置：从CubeMX到HAL库API
2.1 CubeMX配置：从机地址填7位还是8位
用STM32CubeMX配置I2C为从机模式时，需要注意几个关键参数。首先是Parameter Settings里的I2C Speed Mode，这里配置的是从机自己的时序参数，可以理解为从机在SCL时钟沿附近保持数据的时间窗口。实际通信速率由主机的SCL决定，从机只是被动适配。但配置上建议设置为主机通信速率相同或更高的值，如果主机跑400kHz而这里配成100kHz，从机内部时序参数会过于保守，在快速通信时可能出现相位裕量不足的问题。
Address Configuration里的Slave Address就是本机的7位地址，比如填0x33。默认情况下Address Mode选7-bit。这里填的确实是7位地址，不需要左移。左移是在主机调用传输函数时才做的操作。
关键一步是NVIC设置里勾选I2C1 interrupt，这会使能I2C事件中断和错误中断，从机靠中断来判断地址匹配和字节收发。如果不勾选，HAL_I2C_Listen无法正常工作。另外注意，中断优先级不要太低，如果被其他低频高优先级中断频繁打断，SCL上可能出现超时风险，主机侧会报总线错误。
生成代码之后，I2C外设的初始化函数MX_I2C1_Init基本不用改，但地址相关的寄存器值需要确认一下。HAL库会自动帮你把7位地址左移一位填入OAR1寄存器，所以用户层看到的就是7位地址，这一点做得还算友好。
2.2 关键API与中断回调：HAL_I2C_Listen与三个回调函数的配合
从机模式的核心API其实不多，但调用关系必须搞清楚。启动从机监听用的是HAL_I2C_Listen，这个函数不会阻塞，它让I2C外设进入监听模式，一直等待总线上出现匹配本机地址的起始条件。地址匹配成功后，硬件触发中断，HAL库进入地址回调函数HAL_I2C_AddrCallback：
void HAL_I2C_AddrCallback(I2C_HandleTypeDef *hi2c, uint8_t TransferDirection, uint16_t AddrMatchCode)在这里，TransferDirection是从从机视角来定义的方向。I2C_DIRECTION_RECEIVE表示主机要写数据给从机（从机接收），I2C_DIRECTION_TRANSMIT表示主机要过来读数据（从机发送）。很多人在这个回调里搞反方向，导致发送接收逻辑颠倒，数据全乱。
地址匹配之后，必须在回调里调用HAL_I2C_Slave_Receive_IT或HAL_I2C_Slave_Transmit_IT来继续后面的数据收发。这两个函数需要传入接收或发送缓冲区以及数据长度。传输完成后，HAL库会进入对应的完成回调HAL_I2C_SlaveRxCpltCallback或HAL_I2C_SlaveTxCpltCallback。
注意一个细节：监听模式的退出条件比较复杂，有的HAL库版本里，一次地址匹配和数据传输完成后，从机会自动恢复监听，有的版本不会。保险的做法是在传输完成回调里手动再调用一次HAL_I2C_Listen，确保下一次主机访问时从机仍然在监听。这个动作我吃了不少亏，一开始从机只能响应第一次访问，第二次就完全没反应了，就是因为没重新挂监听。
2.3 上拉电阻和时钟：为什么波形总是不对
I2C总线是开漏结构，SDA和SCL两根线必须通过上拉电阻接到电源，否则总线无法主动拉高到高电平。STM32内部虽然也有上拉电阻，但阻值通常在30k到50k欧姆之间，对I2C来说太弱了，会直接拉长信号上升沿，导致通信速率上不去，甚至完全无法通信。所以外部必须加物理上拉电阻。
上拉电阻阻值选择有讲究。100kHz标准模式下用4.7k欧姆比较稳妥，400kHz快速模式下用2.2k欧姆会更可靠，总线上挂的设备越多，等效电容越大，越需要用更小的上拉电阻来保证上升沿时间。我实测过，挂一个从设备用4.7k没问题，挂三个以上设备时，波形边沿明显变圆，换成2.2k后立刻干净了。
调试时发现波形边沿严重畸变，除了上拉电阻，还要怀疑示波器探头电容。普通探头电容几十pF，探头点到SCL上相当于给总线加了个大电容，如果你用的是100MHz的简易示波器，这个问题在400kHz下特别明显。我当时一度以为是上拉电阻阻值不对，换了好几个阻值都没解决，最后拔掉探头，用逻辑分析仪测才恢复正常。
3. 实操过程：手把手写一个可用的从机程序
3.1 主循环与中断怎么搭配：状态机设计
从机程序不能像主机那样简单地调用一次阻塞收发就完事，因为主机什么时候来访问是未知的。通常的设计思路是：中断部分负责“接住”每一个字节和地址匹配事件，主循环负责数据处理和对外响应。
我的习惯是设计一个简单的状态机，用全局标志位记录从机当前的状态，比如下面这种：
#define IDLE 0 #define ADDR_MATCHED 1 #define RX_COMPLETE 2 #define TX_COMPLETE 3 volatile uint8_t i2c_state = IDLE; volatile uint8_t new_data_flag = 0; uint8_t rx_buf[8]; uint8_t tx_buf[8];中断回调里只更新状态和拷贝最小必要数据，不处理复杂逻辑。主循环检查标志位，发现有新数据就解析并准备下一次发送的数据。这种方式回调里没有耗时操作，不会拖慢I2C中断响应，也更符合嵌入式中断设计的基本原则。
当然你也可以在回调里直接处理，但如果数据量稍大，或者主循环有其他实时任务，就很容易出现中断嵌套和资源竞争问题。用标志位把实时性要求高的部分留在中断，把计算量大的部分挪到主循环，实际跑下来会稳定很多。
3.2 完整代码示例：接收主机命令并返回数据
下面给一个完整的从机收发示例。假设从机地址是0x33，主机发送2字节命令给从机，从机根据命令返回4字节的状态数据。
#define I2C_SLAVE_ADDR 0x33 #define CMD_LEN 2 #define DATA_LEN 4 uint8_t rx_buf[CMD_LEN]; uint8_t tx_buf[DATA_LEN]; volatile uint8_t i2c_state = IDLE; void I2C_Slave_Init(void) { // MX_I2C1_Init(); // CubeMX已经生成 HAL_I2C_Listen(&hi2c1); } void HAL_I2C_AddrCallback(I2C_HandleTypeDef *hi2c, uint8_t TransferDirection, uint16_t AddrMatchCode) { if (hi2c->Instance == I2C1) { if (TransferDirection == I2C_DIRECTION_RECEIVE) { // 主机写数据给从机（从机接收） HAL_I2C_Slave_Receive_IT(hi2c, rx_buf, CMD_LEN); } else { // 主机要从机发送数据（从机发送） HAL_I2C_Slave_Transmit_IT(hi2c, tx_buf, DATA_LEN); } } } void HAL_I2C_SlaveRxCpltCallback(I2C_HandleTypeDef *hi2c) { if (hi2c->Instance == I2C1) { i2c_state = RX_COMPLETE; new_data_flag = 1; HAL_I2C_Listen(&hi2c1); // 重新进入监听 } } void HAL_I2C_SlaveTxCpltCallback(I2C_HandleTypeDef *hi2c) { if (hi2c->Instance == I2C1) { i2c_state = TX_COMPLETE; HAL_I2C_Listen(&hi2c1); // 重新进入监听 } } int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_I2C1_Init(); I2C_Slave_Init(); while (1) { if (new_data_flag) { new_data_flag = 0; // 解析命令，更新tx_buf if (rx_buf[0] == 0x01) { tx_buf[0] = 0xAA; tx_buf[1] = 0xBB; tx_buf[2] = 0xCC; tx_buf[3] = 0xDD; } } } }需要注意，HAL_I2C_Slave_Receive_IT传入的缓冲区长度的含义，是指这台从机期望在这一次传输中收到的字节总数。如果主机实际发送的字节数比这个短，I2C总线上会出现时钟拉伸或者NACK，具体行为取决于HAL库版本和芯片型号。所以主机发数据的长度必须和从机这边设置的接收长度严格一致。在工程里最好用宏定义统一管理，并且在调试时对照两个设备端的长度参数。
3.3 用另一个STM32或者逻辑分析仪验证
从机程序写完，怎么验证它真的工作正常？最直接的办法是准备两个STM32开发板，一个配置成I2C主机，一个配置成从机，把SDA和SCL对应连上，两块板子共地。另外两块板子都要接上拉电阻，如果开发板上没有板载上拉，需要外接两个4.7k欧姆电阻到3.3V。
主机端代码用HAL_I2C_Master_Transmit和HAL_I2C_Master_Receive，注意手册或者设备树里写的7位地址0x33，在调用时要变成0x33 << 1也就是0x66传入DevAddress参数：
HAL_I2C_Master_Transmit(&hi2c1, (I2C_SLAVE_ADDR << 1), cmd_data, 2, 100); HAL_I2C_Master_Receive(&hi2c1, (I2C_SLAVE_ADDR << 1), recv_data, 4, 100);我第一次测试时，主机往从机地址0x33写数据，从机完全没反应，查了半天，最后发现主机用的DevAddress是0x33而不是左移后的0x66，地址字节最低位被当成了写标志，整个地址对不上。这个左移细节是I2C地址匹配失败的最高频原因，没有之一。
如果手头没有第二个STM32，有树莓派、Arduino或者USB转I2C适配器都可以做主机。用逻辑分析仪抓取波形是更直观的验证手段，可以直接看到主机发送的地址字节、ACK位、数据字节的时序是否符合I2C协议。从机模式下尤其建议抓波形，因为很多问题用代码逻辑根本看不出原因，波形一抓便知是什么阶段出的错。
4. 常见问题与排查技巧实录
4.1 从机不响应：地址、监听、上拉三大原因
地址不匹配是最常见的原因。排查时先确认主机传的地址是否已经左移1位，再确认从机CubeMX里配的7位地址是否和主机期望一致。很多I2C设备数据手册里给出的是8位地址（已经包含读写位），比如某传感器手册写“设备地址0xA6”，这其实是7位地址0x53左移一位后的值。如果直接把0xA6填进CubeMX的7位地址栏，就大错特错了。判断方法很简单：看硬件手册时，如果地址后面标注了W和R两种（比如0xA6/0xA7），那它给的就是8位地址，需要用0xA6 >> 1也就是0x53去配置从机。
忘了调用HAL_I2C_Listen是第二个高发问题。初始化完成后必须调用一次，否则从机外设根本没有进入监听状态。还有前面说的，一次传输完成后要根据HAL库版本判断是否重新调用HAL_I2C_Listen，我的建议是在Rx和Tx完成回调里都无条件重新调用一次，确保从机随时可以被再次匹配。
上拉电阻缺失是第三个典型问题。如果I2C总线上完全没有外部上拉，用示波器看SCL和SDA，高电平时波形是平的，电平拉不上来。这种情况无论是主机还是从机都无法正常通信。
我整理了一张排查顺序表，遇到问题按这个顺序查，能省不少时间：
| 现象 | 排查方向 | 解决方法 |
|---|---|---|
| 从机完全不响应，无任何中断触发 | 上拉电阻是否接好 | 给SCL和SDA加4.7k欧姆上拉到VCC |
| 从机有中断但AddrCallback不进入 | 地址匹配异常 | 用逻辑分析仪抓地址字节，确认7位地址和左移规则 |
| 地址匹配后数据传不完整 | 传输长度或监听状态 | 核对从机接收/发送长度与主机预期一致，传输完成后重新Listen |
| 通信一段时间后卡死 | 中断优先级不合理或回调耗时过长 | 回调里只置标志位，不在中断内做耗时操作 |
| 总线一直忙，主机发送超时 | 从机拉低SCL未释放 | 检查从机是否死循环或未调用HAL_I2C_Listen恢复监听 |
4.2 数据错位或卡死：长度匹配与总线恢复
数据错位的核心原因是从机配置的接收长度和主机实际发送长度不一致。打个比方，主机打算发3个字节，从机却设置了5个字节的接收长度，那么主机发完3个字节后，会继续等从机的ACK，从机却还在等剩下的2个字节，双方互相等待，总线直接卡死。这种情况通常表现为主机侧超时HAL_TIMEOUT，从机侧I2C状态寄存器卡在某个中间态。
遇到总线卡死，最简单粗暴的恢复方法是把主机和从机的发送接收长度统一调整正确，然后对两个设备都做一次复位或者重新上电。另外，I2C总线上如果出现异常状态，SCL被拉低不放，通常是某台从机内部状态机跑飞了，需要在代码里增加错误处理回调HAL_I2C_ErrorCallback，当出错时重新初始化I2C外设并重新监听：
void HAL_I2C_ErrorCallback(I2C_HandleTypeDef *hi2c) { if (hi2c->Instance == I2C1) { // 可以在这里统计错误次数，并使用I2C软件复位来恢复总线 __HAL_I2C_DISABLE(hi2c); __HAL_I2C_ENABLE(hi2c); HAL_I2C_Listen(hi2c); } }这个方法不能频繁调用，否则会掩盖真正的通信逻辑问题，但作为总线异常后的兜底恢复手段，在工业现场通信里还是很常见的。
另一个容易忽略的问题是中断优先级。I2C从机中断优先级如果设置得太低，在中断被其他高优先级中断抢占期间，主机的SCL时钟还在继续跳，如果达到I2C协议的timeout限制，主机就会放弃本次通信并报错。从机对时序的实时响应要求很高，所以I2C中断优先级不要低于1，绝对不要写成和SysTick同优先级或者更低。这算是我调了三天中断抢占问题后总结出的血泪教训。
4.3 多从机共存：地址冲突和总线时序
在同一条I2C总线上挂多个从机时，地址冲突要特别注意。每个从机的地址必须唯一，如果两个设备都是7位地址0x33，总线上就会出现地址碰撞，主机点名0x33时两个从机都会应答，数据直接错乱。对于STM32从机来说，可以在代码里定义一个地址变量，但I2C地址一旦编译进固件就是固定的，不可能运行时随意更改。比较灵活的做法是用IO引脚来扩展地址选择，比如用两个GPIO的电平组合决定设备使用哪一组地址，硬件上把拨码开关或跳线帽接到对应的地址引脚。
多从机并存时，总线上拉电阻也要重新评估。每增加一个从机，总线的等效电容就会增加，上拉电阻可能需要从4.7k降到2.2k甚至1k，否则高电平建立时间不够，总线上出现毛刺的概率会增大。如果挂了比较多从机，还要把通信速率适当降低，比如从400kHz降到100kHz，可靠性会明显提升。
如果你在一条I2C总线上同时挂了STM32从机、OLED屏、EEPROM这类设备，要注意不同设备的时序容限不一样。OLED一般能适应100kHz到400kHz，但一些老的EEPROM在400kHz下可能触发写周期时序问题。最常见的做法是全部跑100kHz标准模式，虽然慢一点，但兼容性最好。如果需要提升速度，建议用I2C多路复用器比如TCA9548A，把高速设备和低速设备分开挂到不同的总线段上，互不影响时序参数。
4.4 与主机频率的适配：一个容易忽视的时序细节
从机模式还有一个隐藏的时序细节，就是CubeMX里配置的I2C速率会影响从机内部时序参数的生成。有的开发者从机配置时选了400kHz，但主机实际跑的是100kHz，理论上从机应该能兼容更慢的速率，但某些STM32型号上，如果从机的时序寄存器配置不合理，反而可能出现建立时间不足的边界问题。
我踩过一次很隐蔽的坑：一块STM32G0从机，主机是Linux主控板，I2C总线跑的是100kHz，从机CubeMX里默认配了400kHz的Timing参数。通信大部分时候正常，但偶尔在温度升高或者电源纹波变大时，主机读回的数据偶发错位。后来把从机的Timing参数也改成100kHz对应的配置，问题就消失了。后来查参考手册才明白，从机的时序参数不仅影响自己采样SDA的时刻，还会影响SCL低电平期间从机内部时钟的同步逻辑。所以从机端的速率配置最好和主机保持一致，不要想当然地认为配高了就一定好。
5. 这次实操中积累的几个经验
调试I2C从机模式时，我最大的体会是：这和主机模式完全是两种调试思路。主机模式是自己掌握节奏，代码哪里不对可以随时停下来改；从机模式是被动响应，问题的表现往往是主机那边先超时或者报错，然后才反过来查从机。手里准备一个逻辑分析仪或者示波器，在从机调试里基本是必需品，靠打日志和printf的思路在这里效率很低。
另一个经验是关于HAL库版本的。不同版本的HAL库，I2C从机部分的实现细节有差异，尤其是Listen之后是否需要重新挂接、AddrCallback里hi2c->State的取值，不同系列芯片上会有不同表现。我代码里已经尽量做了不依赖内部状态的写法，但如果你换了一个新系列芯片，最好还是先跑一个最简单的回环测试，确认中断回调链路的完整流程，再往上堆业务逻辑。你也不需要死记硬背这些差异，遇到问题多翻一翻芯片对应的HAL头文件注释，比在网上找解答更快。
最后再分享一个小技巧，如果产品需要长期稳定运行，可以在I2C错误中断里加一个错误计数，定期上报给主机。这样即使总线偶尔出现异常，也能通过远程监控手段及时发现，而不是等到设备完全不工作了才去现场排查。好用的嵌入式通信代码不是一次写出来的，而是在不断暴露问题、修复问题的过程中磨出来的。
本文还有配套的精品资源，点击获取
