1. 从裸机位操作换成 ESP-IDF:一次 I2C 主机收发的完整起步
拿到一块开发板,想让主控通过 I2C 从传感器或模块里读回几个字节,很多人的第一反应是网上找一段裸机位操作代码,自己翻转 SCL、等 ACK。真用上代码开发工具 ESP-IDF 之后,这条路可以换一种走法:驱动层已经把时序、ACK、超时封装好,你只需要把宏定义填对、把 i2c_master_write_read_device 这类接口调顺。这篇就围绕一个最小可跑的 I2C 主机例子,写清配置结构体、两种收发接口、参数怎么设,以及在真机上最容易翻车的地方。适合刚上手 ESP-IDF、手里已有 I2C 模块、想尽快把数据读出来的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 在代码开发工具 ESP-IDF 里配 I2C 主机:宏定义、时钟与驱动安装
2.1 先把引脚和端口固定成宏
工程建好之后别急着写收发逻辑,先把会反复改的东西提到文件头。示例里这段宏定义建议原样抄一遍,改板子时只动这几行:
c复制#include <stdio.h>
#include "driver/i2c.h"
#define I2C_MASTER_SCL_IO 22 // I2C master clock pin
#define I2C_MASTER_SDA_IO 21 // I2C master data pin
#define I2C_MASTER_NUM I2C_NUM_0 // I2C port number
#define I2C_MASTER_FREQ_HZ 100000 // I2C master clock frequency
#define I2C_MASTER_TX_BUF_DISABLE 0 // I2C master doesn't need buffer
#define I2C_MASTER_RX_BUF_DISABLE 0 // I2C master doesn't need buffer
#define I2C_MASTER_TIMEOUT_MS 1000
#define DEVICE_ADDRESS 0x28 // I2C device address
#define WRITE_CMD 0x01 // Command to be sent to the device
这里每个宏都不是摆设。I2C_MASTER_SCL_IO 和 I2C_MASTER_SDA_IO 直接对应你板子上引出来的两根线,接反了不会编译报错,只会在运行时报超时;I2C_MASTER_NUM 选的是端口号,示例用 I2C_NUM_0,意味着这条总线归 0 号控制器管,后面所有接口都得传同一个值;I2C_MASTER_FREQ_HZ 写的是 100000,也就是 100 kHz 标准速率,换成 400 kHz 快速模式时只改这一个宏就行,但要从设备手册确认它撑得住;I2C_MASTER_TIMEOUT_MS 是单次操作最多等多久,1000 毫秒对慢速模块够用;两个 *_BUF_DISABLE 都定义成 0,意思是主机侧不需要驱动层再挂环形缓冲区,收发直接走调用参数。
从设备地址和命令字单独拎出来也很关键。DEVICE_ADDRESS 填的是 7 位地址,WRITE_CMD 是你要先发给从设备的命令/寄存器号。把它们和引脚宏分开放,是为了换一个从设备时只改这两行,不会顺手把引脚也改乱。
2.2 i2c_config_t 里每个字段在管什么
真正初始化总线的是 i2c_config_t,示例里的赋值长这样:
c复制i2c_config_t conf = {
.mode = I2C_MODE_MASTER,
.sda_io_num = I2C_MASTER_SDA_IO,
.sda_pullup_en = GPIO_PULLUP_ENABLE,
.scl_io_num = I2C_MASTER_SCL_IO,
.scl_pullup_en = GPIO_PULLUP_ENABLE,
.master.clk_speed = I2C_MASTER_FREQ_HZ,
};
字段和取值对应关系如下,照着表核一遍比盯着代码猜快:
| 字段 | 例子里的值 | 作用 |
|---|---|---|
mode |
I2C_MODE_MASTER |
当前芯片作主机,主动发时钟 |
sda_io_num |
21 | 数据线接的 GPIO |
sda_pullup_en |
GPIO_PULLUP_ENABLE |
打开 SDA 内部上拉 |
scl_io_num |
22 | 时钟线接的 GPIO |
scl_pullup_en |
GPIO_PULLUP_ENABLE |
打开 SCL 内部上拉 |
master.clk_speed |
100000 | 主机输出的 SCL 频率 |
两个上拉字段容易被忽略。I2C 是开漏总线,没有上拉就拉不出高电平,波形看着像一条塌下去的直线。示例开了内部上拉,短距离、单从设备时通常能跑;线拉得长、从设备多或者速率提到 400 kHz 时,内部上拉往往偏弱,得在外面补 4.7k 左右的电阻。这个差别在示波器上看不出「对错」,只体现在读数据稳不稳,后面排查章节还会碰到。
master.clk_speed 只对主机模式有意义。填太低会让一次传输拖很久,填太高超过从设备能力就会 NACK 或读回乱码。我一般先用 100000 把链路跑通,确认数据和手册对得上,再考虑往上调。
2.3 i2c_param_config 与 i2c_driver_install 的分工
配置结构体填好之后,示例连着调了两个函数:
c复制i2c_param_config(I2C_MASTER_NUM, &conf);
i2c_driver_install(I2C_MASTER_NUM, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
这两个函数不是二选一,而是先配参数、再装驱动,顺序不能反。i2c_param_config 把结构体里的引脚、速率换算成控制器寄存器里的分频和时序,它只写硬件配置,不申请任何资源;i2c_driver_install 才真正把驱动挂上去,创建中断、分配上下文。第二个参数直接复用 conf.mode,保证装驱动时的角色和配置时一致。
后三个参数值得单独说一下。示例把 I2C_MASTER_RX_BUF_DISABLE 和 I2C_MASTER_TX_BUF_DISABLE 传进去,两个值都是 0,含义是主机不需要驱动层再维护环形缓冲区,收发的数据缓冲区由调用方自己提供。最后一个参数 0 是中断分配标志,主机轮询式收发用默认值即可。这三个位置如果填错,编译能过,运行时却可能一直等不到数据——因为驱动拿到的缓冲长度和你以为的不一样。
调用完这两个函数,总线就处于可用状态,可以进 app_main 后面的收发逻辑了。此时还没有任何一次真正的 I2C 传输,从设备也没被访问过,所以别在这一步就判断「设备没反应」,真正的握手在下一章的收发接口里。
3. 写后读:i2c_master_write_read_device 的寄存器式时序
3.1 为什么很多从设备要先发一个命令字
大部分 I2C 从设备不是「读它就吐数据」,而是要先收到一个命令字或寄存器地址,才知道你要哪一段内容。这个动作在协议上是一次写加一次读,中间夹一个重复起始位(Repeated Start),总线不被别的设备抢走。自己用两次独立调用拼,容易在两次之间被其他主机插进来;i2c_master_write_read_device 把这两段合成一次原子操作,正好对应这种「先发地址、再读数据」的器件。
示例里的 WRITE_CMD 就是那个命令字,值 0x01,read_buffer[10] 是准备接 10 个字节的接收缓冲。这两者的顺序、长度都体现在函数参数里,写错任何一个,读回来的就不是你要的寄存器。
3.2 完整代码与逐参数说明
c复制void app_main(void) {
i2c_config_t conf = {
.mode = I2C_MODE_MASTER,
.sda_io_num = I2C_MASTER_SDA_IO,
.sda_pullup_en = GPIO_PULLUP_ENABLE,
.scl_io_num = I2C_MASTER_SCL_IO,
.scl_pullup_en = GPIO_PULLUP_ENABLE,
.master.clk_speed = I2C_MASTER_FREQ_HZ,
};
i2c_param_config(I2C_MASTER_NUM, &conf);
i2c_driver_install(I2C_MASTER_NUM, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
uint8_t write_buffer = WRITE_CMD;
uint8_t read_buffer[10]; // Buffer to store the read data
esp_err_t ret = i2c_master_write_read_device(
I2C_MASTER_NUM,
DEVICE_ADDRESS,
&write_buffer,
sizeof(write_buffer),
read_buffer,
sizeof(read_buffer),
pdMS_TO_TICKS(I2C_MASTER_TIMEOUT_MS)
);
if (ret == ESP_OK) {
printf("Data read from device: ");
for (int i = 0; i < sizeof(read_buffer); i++) {
printf("%02x ", read_buffer[i]);
}
printf("\n");
} else {
printf("I2C read failed\n");
}
i2c_driver_delete(I2C_MASTER_NUM);
}
第一个参数 I2C_MASTER_NUM 是端口,必须和初始化时的一致,换成 I2C_NUM_1 就会在一条没配过的总线上操作。第二个 DEVICE_ADDRESS 是从设备的 7 位地址,示例填 0x28。第三、四个参数是写缓冲区和它的长度,这里只发一个字节的命令字,所以传 &write_buffer 和 sizeof(write_buffer);第五、六个是读缓冲区和读长度,sizeof(read_buffer) 正好是 10。最后一个 pdMS_TO_TICKS(I2C_MASTER_TIMEOUT_MS) 把 1000 毫秒换算成系统节拍,作为这次传输等待完成的上限。
提示:
sizeof(write_buffer)里write_buffer是单字节变量,结果是 1,没问题;但如果你后面把它改成指针,sizeof就变成指针宽度了,收发长度会瞬间不对。我一般养成习惯,长度要么明确写常量,要么用数组名去取。
3.3 返回值和读缓冲区的处理
函数返回 esp_err_t,只有等于 ESP_OK 才算整段「写命令 + 读数据」都成功。示例在成功分支里用 %02x 把每个字节按两位十六进制打出来,这一步别省。I2C 的很多问题不是「读不到」,而是「读到了但内容不对」,只有把原始字节打出来和器件手册对照,才能判断是地址错、命令错还是时序错。
失败分支只打印 I2C read failed,实际调试时会显得信息太少。可以在这行前面加一句把 ret 的值也打出来,因为不同错误码指向的原因不一样:NACK 类多半是地址或器件没接好,超时类多半是总线上拉、速率或者器件卡住。先分清是哪一类,再去改参数,比盲目换引脚快得多。
读缓冲区的大小要和从设备实际能返回的字节数对齐。示例固定读 10 个字节,如果你的器件一次只给 2 个寄存器,多读的部分会被器件按自己的方式处理,可能是补 0xFF,也可能直接 NACK。长度不对,后面解析就全乱。
最后一行 i2c_driver_delete(I2C_MASTER_NUM) 是收尾。示例在这个最小程序里跑完就删掉,实际项目中如果后面还要继续用总线,就不要提前删;反过来,如果同一端口反复初始化却不删,下一次 i2c_driver_install 会因为资源已占用而失败。
4. 代码开发工具的另一条写路径:i2c_master_write_to_device 的字节缓冲区
4.1 只写不读的典型场景
不是所有操作都要读回数据。给从设备发一条控制命令、写一组配置寄存器、触发一次采样,这些都是一次性写入,不需要紧接着读。示例给的就是这种场景:把 {0x01, 0x02, 0x03, 0x04} 四个字节一口气发出去,用 i2c_master_write_to_device,不用准备接收缓冲区。
判断用哪个接口很简单:如果动作里包含「我要读回结果」,用 write_read;如果只是「告诉器件做某事」,用 write_to_device。两者底层都是往总线发数据,区别只在于前者多发了一个重复起始位并转入接收阶段。用错了不会崩,但会多一次没必要的读,或者读回的是无关内容。
4.2 代码与缓冲区长度的坑
c复制void app_main(void) {
i2c_config_t conf = {
.mode = I2C_MODE_MASTER,
.sda_io_num = I2C_MASTER_SDA_IO,
.sda_pullup_en = GPIO_PULLUP_ENABLE,
.scl_io_num = I2C_MASTER_SCL_IO,
.scl_pullup_en = GPIO_PULLUP_ENABLE,
.master.clk_speed = I2C_MASTER_FREQ_HZ,
};
i2c_param_config(I2C_MASTER_NUM, &conf);
i2c_driver_install(I2C_MASTER_NUM, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
uint8_t write_buffer[] = {0x01, 0x02, 0x03, 0x04}; // Data to be sent to the device
esp_err_t ret = i2c_master_write_to_device(
I2C_MASTER_NUM,
DEVICE_ADDRESS,
write_buffer,
sizeof(write_buffer),
pdMS_TO_TICKS(I2C_MASTER_TIMEOUT_MS)
);
if (ret == ESP_OK) {
printf("Data written to device successfully\n");
} else {
printf("I2C write failed\n");
}
i2c_driver_delete(I2C_MASTER_NUM);
}
和 write_read 比,参数从七个缩到五个:少了一个读缓冲区指针和一个读长度,其余含义完全一致。sizeof(write_buffer) 这里是 4,因为 write_buffer 是真正的数组;如果换成 uint8_t *write_buffer = ... 再取 sizeof,拿到的是指针宽度,长度就会错成 4 或 8 字节,器件收到的内容也跟着错位。这种错误编译器不报,只能靠串口打日志或者逻辑分析仪抓波形发现。
写入成功的判断同样只看 ret == ESP_OK。但要注意,「写成功」只代表总线上有 ACK、数据发出去了,不代表器件真的执行了。有些命令需要器件内部处理时间,紧接着发下一条会被 NACK;示例没有处理这个间隔,如果你的器件手册写了「写命令后等待若干毫秒」,就得在两次写之间自己加延时。这个细节在入门示例里往往省略,但换到真实器件上很关键。
4.3 两种接口怎么选
把两条路径摆在一起对照,选型一目了然:
| 接口 | 读写行为 | 典型用途 | 缓冲区 |
|---|---|---|---|
i2c_master_write_to_device |
只写 | 发命令、写配置、触发动作 | 只需 write_buffer |
i2c_master_write_read_device |
先写后读 | 读寄存器、读测量值 | write_buffer + read_buffer |
我的习惯是先从 write_read 入手,因为它同时覆盖了「发命令」和「收数据」两段时序,链路一旦通了,write_to_device 自然也就通了。反过来先只写、再单独调读,中间那段重复起始位要自己拼,反而更容易出问题。
5. 排查 I2C 收不到数据:五个现象、原因和改法
5.1 现象:write_read 一直返回失败,读缓冲区原封不动
原因优先怀疑接线和上拉。示例里 SDA 是 21、SCL 是 22,接反了编译和初始化都不报错,只有在真正发起传输时从设备收不到时钟或数据,返回 NACK 或超时。另一种情况是外部模块自带的上拉没接上、内部上拉又太弱,波形拉不到高电平,同样表现为一直失败。
解决分两步:先拿万用表确认 21 和 22 确实接到模块的 SDA、SCL 上,别把 SCL 接到 SDA;再核对模块上有没有上拉电阻,没有就在两根线上各补一个到电源的电阻。改完先跑 write_to_device 发一个字节看是否成功,确认总线通了再回到 write_read。
5.2 现象:传输成功,但读回来全是 0xFF 或 0x00
原因多半是 DEVICE_ADDRESS 和器件手册对不上。示例填 0x28,那是某一个具体器件的 7 位地址;换一个模块,地址就变了。也有把 8 位写地址(已经左移过一位)当成 7 位填进去的情况,总线上实际访问的成了另一个设备,返回自然是无效数据。
解决:翻器件手册确认 7 位地址,只改 DEVICE_ADDRESS 这一行,其他别动;如果手册给的是 8 位地址,右移一位再填。改完把读到的字节按 %02x 打出来,对照手册里寄存器的默认值,能对上一两个就说明地址对了。
5.3 现象:write_to_device 返回成功,器件却毫无反应
原因是数据组织错了。示例发的是 {0x01, 0x02, 0x03, 0x04},第一个字节常常被器件当作命令或寄存器地址,后面才是数据。如果你把顺序写反、或者多塞了一个字节,器件收到的是它不认识的命令,虽然总线给了 ACK,内部却没执行任何动作。
解决:对着手册把「命令字 + 数据」的字节序列重新排一遍,第一个字节放命令,后面放参数;长度用 sizeof(数组) 拿,别手写数字。改完先只发命令字节,确认器件有响应,再逐步加数据字节。
5.4 现象:跑一会儿就超时,重启后又正常
原因是超时时间或总线占用。示例的 I2C_MASTER_TIMEOUT_MS 是 1000,对大多数器件够用,但如果从设备在忙、需要较长处理时间,下一次传输就会在等待中耗尽超时。另一种是总线上有多个设备,某一次传输被拉长,后面的调用排队超时。
解决:先把 pdMS_TO_TICKS(I2C_MASTER_TIMEOUT_MS) 里的值调大,比如从 1000 提到 2000 观察是否还超时;如果确认是器件处理慢,就在两次传输之间按手册加延时。别一上来就把频率从 100000 往上调,速率越高对时序和上拉要求越严,反而更容易超时。
5.5 现象:第二次初始化失败或程序跑一遍就卡死
原因是驱动没释放。示例在 app_main 末尾调了 i2c_driver_delete(I2C_MASTER_NUM),如果同一端口在没删的情况下再次 i2c_driver_install,会因为资源已被占用而失败;反过来,如果业务里还要继续用总线,提前 delete 又会让后续调用全部报错。
解决:把「装驱动」和「删驱动」当成一对,初始化只做一次,退出或切换配置时才删。需要在运行中改速率或引脚时,先 delete 再重新 param_config + install,顺序不能颠倒。
6. 把十六进制日志和超时值当成固定动作
示例里那段 printf("%02x ", ...) 的循环,看着只是调试输出,其实是我验证 I2C 链路最省事的办法。每次改完地址、命令字或读长度,先把读回的字节原样打出来,和器件手册的寄存器表逐个对:能对上,说明地址和命令都对;对不上但长度对,多半是命令字选错了寄存器;长度都不对,回去查 sizeof 和读缓冲区大小。
我一般还会把超时值单独提出来观察。把 I2C_MASTER_TIMEOUT_MS 从 1000 临时改小到 100,如果每次都在固定位置超时,问题基本在器件响应而不是偶发干扰;如果改大之后失败消失,那就是等待时间不够,按手册补延时或者把值定在 2000 左右。这个二分法比反复换引脚有效得多。
验证顺序也有讲究:先只跑 write_to_device 发一个字节,确认返回 ESP_OK;再跑 write_read 读固定长度,确认字节内容合理;最后才把速率从 100000 往上调,每调一次都把日志重打一遍。三步都稳了,再把这段逻辑挪进正式工程。
血泪经验是,I2C 的问题八成出在三个地方:地址、上拉、长度。这三个对了,剩下的才是时序和器件本身。从那以后我每次接新模块,都强制先跑一遍「发一个字节、读固定长度、打十六进制」的最小闭环,再谈业务逻辑,省下不少来回。希望帮到你。
