【产出】 > 能把 I2C 传感器或模块正确接到 Arduino 上(找对 SDA/SCL、配好上拉电阻、处理 3.3 V 与 5 V 混用),用地址扫描程序确认设备在线,看懂
endTransmission()的返回码,并用beginTransmission/write/requestFrom完成一次"写寄存器地址、读回数据"的标准操作。
【版本】 > 按 Arduino 官方 Wire 库语言参考和 docs.arduino.cc 的 I2C 教程编写,适用于 Arduino IDE 2.x 与 Arduino CLI。Wire 库随所有开发板支持包自带,无需另外安装。示例以 UNO R3 为例。
一、I2C 是怎么工作的
I2C 只用两根信号线:
| 线 | 名称 | 作用 |
|---|---|---|
| SDA | 串行数据线 | 双向传数据 |
| SCL | 串行时钟线 | 由控制器(Arduino)产生时钟,所有设备按它同步 |
一条总线上有一个控制器(controller,旧称 master),可以挂多个外设(peripheral,旧称 slave)。每个外设有自己的地址。控制器发出的每条消息都以地址开头,只有地址匹配的那个设备才响应。地址后面跟一位,表示这次是读还是写。接收方每收完一个字节都要回一个应答(ACK),控制器收到应答才继续发下一个字节。
所以两根线就能挂一串传感器、显示屏、EEPROM,只要它们地址不冲突。
地址是 7 位的。 官方特别提醒:有些数据手册或例程写的是 8 位地址(把读写位也算进去了)。Wire 库全程使用 7 位地址,遇到 8 位地址要右移一位。例如手册写 0x78,Wire 里应该写 0x3C。7 位地址范围是 0–127,其中 0–7 是保留地址,可用的第一个地址是 8。
二、各板 SDA/SCL 在哪
以官方 Wire 参考的表格为准:
| 板子 | 默认 I2C(Wire) | 额外的 I2C | 备注 |
|---|---|---|---|
| UNO R3、UNO R3 SMD、UNO Mini Ltd | A4(SDA)、A5(SCL) | 数字排针一侧的 SDA/SCL 引脚也是这一路 | |
| UNO R4 Minima、UNO R4 WiFi | A4(SDA)、A5(SCL) | Qwiic 接口:D27(SDA)、D26(SCL) | 同上 |
| UNO WiFi Rev2、Zero | 20(SDA)、21(SCL) | ||
| Leonardo、Micro、Yún Rev2 | D2(SDA)、D3(SCL) | ||
| Nano 系列 | A4(SDA)、A5(SCL) | ||
| MKR 系列 | D11(SDA)、D12(SCL) | ||
| GIGA R1 WiFi | 20(SDA)、21(SCL) | I2C1:D102、D101;I2C2:D9、D8 | 用 Wire1.begin()、Wire2.begin() |
| Due | 20(SDA)、21(SCL) | I2C1:D70(SDA1)、D71(SCL1) | 用 Wire1.begin() |
| Mega 2560 Rev3 | D20(SDA)、D21(SCL) | 板上自带上拉电阻 |
UNO R3 上 A4/A5 和排针上标着 SDA/SCL 的两个引脚在板内是连通的,接哪一组都行,但这两组不能当成两路独立的 I2C。
【注意】 > 用了 I2C 的引脚就不要再当普通 IO 或模拟输入用。UNO 上用了 I2C 之后,A4、A5 不能再
analogRead();Mega 上 20、21 号引脚用作 I2C 时也不能挂外部中断。
三、上拉电阻
官方说明:SDA、SCL 上需要接上拉电阻。原因是 I2C 设备只会把线"拉低"或"松开",不会主动输出高电平;线松开时要靠上拉电阻把电平拉回高。没有上拉,总线永远是低或者悬空,通信无法进行。
| 情况 | 是否需要自己加上拉 |
|---|---|
| Mega 2560 | 官方说明 20、21 号引脚板上已有上拉 |
| 买来的传感器模块(小 PCB 板) | 大多数模块板上已经焊了上拉电阻,看原理图或板上丝印确认 |
| 直接用芯片、裸接 | 需要,SDA、SCL 各接一只电阻到电源 |
| 多个模块并联 | 每个模块都带上拉时,并联后总阻值变小;模块很多时可能需要去掉一部分 |
阻值常用 4.7 kΩ(常规 100 kHz 速度)或 2.2 kΩ 左右(400 kHz、线较长时)。阻值越小,上升沿越快,但设备拉低时要吸收的电流越大。
在 AVR 板(UNO、Nano、Mega 等)上,Wire 库的源码 twi.c 在 Wire.begin() 时会打开 SDA、SCL 的内部上拉。内部上拉阻值很大,只能在线很短、设备很少时勉强工作,不能代替外部上拉。另外它会把总线拉向 5 V,这一点在第八节混用电压时要注意。
四、第一步:地址扫描
接好线后先别急着写驱动,先确认设备能被找到、地址是多少。原理很简单:对每个地址执行一次空的写操作(只发地址、不发数据),看 endTransmission() 返回什么。返回 0 说明这个地址上有设备应答了。
#include <Wire.h>
void setup() {
Serial.begin(9600);
Wire.begin(); // 作为控制器加入总线
#if defined(WIRE_HAS_TIMEOUT)
Wire.setWireTimeout(3000, true); // 3000 微秒超时,超时后复位 Wire 硬件
#endif
Serial.println("I2C scanner");
}
void loop() {
byte found = 0;
for (byte addr = 8; addr < 120; addr++) {
Wire.beginTransmission(addr);
byte err = Wire.endTransmission();
if (err == 0) {
Serial.print("found 0x");
if (addr < 16) Serial.print('0');
Serial.println(addr, HEX);
found++;
} else if (err == 4 || err == 5) {
Serial.print("error ");
Serial.print(err);
Serial.print(" at 0x");
Serial.println(addr, HEX);
}
// err == 2 表示该地址没有设备应答,属于正常情况,不打印
}
Serial.print("done, ");
Serial.print(found);
Serial.println(" device(s)");
delay(5000);
}
打开串口监视器(9600),会每 5 秒扫描一次。比如接了常见的 0.96 寸 SSD1306 OLED 模块,一般会显示 found 0x3C(官方 I2C 教程里的 OLED 例子也用 0x3C)。
扫描范围从 8 开始是因为 0–7 为保留地址;到 119(0x77)为止,是因为 I2C 规范把 0x78–0x7F 也留作特殊用途。
扫不到设备时按顺序查:
- SDA、SCL 是否接反,是否接到了第二节表格里的正确引脚;
- GND 是否共地,模块是否通电;
- 有没有上拉电阻;
- 模块的供电电压和逻辑电压是否匹配(见第八节)。
【提示】 > 官方建议使用 Wire 时总是打开超时。没有超时的时候,总线被干扰卡住(比如某根线被拉低不放),程序会永远停在
endTransmission()里。WIRE_HAS_TIMEOUT宏只在支持超时功能的平台上才有定义,用#if defined(...)包起来,代码在不支持的板子上也能编译。
五、写数据:beginTransmission / write / endTransmission
向外设写数据是三步:
Wire.beginTransmission(address); // 1. 指定 7 位地址,开始组织一次发送
Wire.write(data); // 2. 把要发的字节放进发送缓冲区(可多次调用)
byte err = Wire.endTransmission(); // 3. 真正发到总线上,并返回结果
注意:write() 只是排队,数据在 endTransmission() 时才真正发出。所以出错时,错误码是 endTransmission() 返回的。
write() 的三种形式:
| 写法 | 发送内容 |
|---|---|
Wire.write(value) | 一个字节 |
Wire.write(string) | 一个字符串的各个字节 |
Wire.write(data, length) | 数组中的 length 个字节 |
返回值是写入的字节数,可以不看。
endTransmission() 的返回码(官方定义):
| 返回值 | 含义 | 常见原因 |
|---|---|---|
| 0 | 成功 | |
| 1 | 数据太长,发送缓冲区装不下 | 一次 write() 了太多字节 |
| 2 | 发送地址时收到 NACK | 地址写错、设备没接好或没上电 |
| 3 | 发送数据时收到 NACK | 设备不接受这个寄存器或数据,或设备正忙 |
| 4 | 其他错误 | 总线异常 |
| 5 | 超时 | 总线被卡住,需打开 setWireTimeout() 才会出现 |
官方提醒:Wire 库使用 32 字节的缓冲区,一次传输超出的字节会被直接丢掉。大块数据要分多次发。
endTransmission() 还可以带一个参数:
endTransmission(true)(默认):发完后发送停止信号,释放总线;endTransmission(false):发完后不释放总线,发送重复起始信号(restart),紧接着进行下一次操作,中间不会被别的控制器插进来。
六、读数据:requestFrom
byte n = Wire.requestFrom(address, quantity); // 默认读完发停止信号
byte n = Wire.requestFrom(address, quantity, stop);
返回值是外设实际返回的字节数。数据收下来后,用 Wire.available() 看还剩几个、Wire.read() 逐个取出。官方例程里特别注明:外设可能返回比请求更少的字节,所以要按 available() 来读,而不是假定一定收满。
Wire.requestFrom(8, 6); // 向地址 8 的设备请求 6 个字节
while (Wire.available()) {
char c = Wire.read();
Serial.print(c);
}
七、标准操作:先写寄存器地址,再读
绝大多数 I2C 传感器内部都是一组寄存器。读某个寄存器的通用步骤是:
- 写一次:发送要读的寄存器地址,用
endTransmission(false)保持总线不释放; - 读一次:
requestFrom()读回该寄存器(和随后几个寄存器)的内容。
下面把它封装成两个通用函数。设备地址和寄存器地址要按你所用芯片的数据手册填写,示例中的 0x68、0x75 只是占位,换成自己的值。
#include <Wire.h>
const byte DEV_ADDR = 0x68; // 换成扫描到的设备地址
const byte REG_ID = 0x75; // 换成数据手册里的寄存器地址
// 从 reg 开始连续读 len 个字节到 buf,返回实际读到的字节数
byte readRegs(byte dev, byte reg, byte *buf, byte len) {
Wire.beginTransmission(dev);
Wire.write(reg);
byte err = Wire.endTransmission(false); // 不释放总线,紧接着读
if (err != 0) {
Serial.print("write reg failed, code ");
Serial.println(err);
return 0;
}
byte n = Wire.requestFrom(dev, len);
byte i = 0;
while (Wire.available() && i < len) {
buf[i++] = Wire.read();
}
return i;
}
// 向 reg 写一个字节,返回 endTransmission() 的结果
byte writeReg(byte dev, byte reg, byte value) {
Wire.beginTransmission(dev);
Wire.write(reg);
Wire.write(value);
return Wire.endTransmission();
}
void setup() {
Serial.begin(9600);
Wire.begin();
#if defined(WIRE_HAS_TIMEOUT)
Wire.setWireTimeout(3000, true);
#endif
}
void loop() {
byte id;
if (readRegs(DEV_ADDR, REG_ID, &id, 1) == 1) {
Serial.print("reg value = 0x");
Serial.println(id, HEX);
} else {
Serial.println("read failed");
}
delay(1000);
}
多字节数据(如 16 位温度值)一次读出 2 个字节后自己拼接,高字节在前还是低字节在前,看芯片手册。
【提示】 > 默认时钟是标准模式。官方
Wire.setClock()接受 100000(标准模式)和 400000(快速模式),部分处理器还支持 10000、1000000、3400000。外设和走线都允许时,在Wire.begin()之后调用Wire.setClock(400000)可以提速。
八、3.3 V 与 5 V 器件混用
这是 I2C 接线最容易出问题的地方。UNO R3、Nano、Mega 是 5 V 逻辑;很多新传感器是 3.3 V 芯片,引脚不耐 5 V。
先看清楚你的模块属于哪一种:
| 模块类型 | 特征 | UNO(5 V)能否直接接 |
|---|---|---|
| 板上有稳压和电平转换 | 标着 VIN 支持 3–5 V,PCB 上有稳压芯片和电平转换管 | 可以 |
| 板上只有稳压,上拉接到 3.3 V | 能接 5 V 电源,但 SDA/SCL 上拉到 3.3 V | 多数情况能工作,但不规范,见下文 |
| 裸 3.3 V 芯片 | 只能接 3.3 V 电源 | 不能直接接,要加电平转换 |
为什么"上拉到 3.3 V 直接接 5 V 板"不规范:
- AVR 的 Wire 库会打开内部上拉,把 SDA/SCL 往 5 V 拉。它和模块上的 3.3 V 上拉形成分压,空闲时线上电压会高于 3.3 V,长期下去对不耐 5 V 的芯片不利;
- 反过来,5 V 芯片判断高电平需要较高的电压(ATmega328P 的数据手册规定为 0.7 × VCC,5 V 供电时是 3.5 V),3.3 V 的高电平低于这个门限,能不能被识别取决于具体芯片和温度,属于"碰巧能用"。
规范做法:在 5 V 与 3.3 V 之间加一个双向 I2C 电平转换模块(常见的是每路一只 MOSFET 加两侧上拉的方案),两侧各接各的电源,GND 共用。
官方 I2C 教程对两种常见连接器的说明也和这有关:Qwiic 在控制器一侧做了电平转换和稳压,外设一侧没有,所以 Qwiic 生态是 3.3 V 逻辑;STEMMA QT 没有这层处理,可以用 3.3 V 或 5 V 逻辑的模块,但需要你自己确认电平是否匹配。
【注意】 > 混用电压时,GND 必须连在一起,否则两边的"高、低电平"没有共同的参考点,通信不会正常。
九、常见问题速查
| 现象 | 可能原因 |
|---|---|
| 扫描什么都找不到 | 引脚接错、没共地、没上拉、模块没供电 |
| 扫描能找到,读数全是 0xFF 或 0 | 寄存器地址写错;没有先写寄存器地址就直接读 |
endTransmission() 返回 2 | 地址错误,常见是把 8 位地址直接填进了 Wire |
endTransmission() 返回 1 | 一次写入超过 32 字节 |
| 程序偶尔卡死在 I2C 调用 | 总线被干扰卡住,打开 setWireTimeout();同时检查线长和上拉 |
| 加了多个模块后不稳定 | 每个模块都带上拉,并联后阻值过小;或线太长 |
| UNO 上 A4/A5 读模拟量异常 | 这两个引脚已经被 I2C 占用 |
参考资料
- Arduino 语言参考:Wire https://docs.arduino.cc/language-reference/en/functions/communication/wire/
- Wire.beginTransmission() https://docs.arduino.cc/language-reference/en/functions/communication/wire/beginTransmission/
- Wire.write() https://docs.arduino.cc/language-reference/en/functions/communication/wire/write/
- Wire.endTransmission() https://docs.arduino.cc/language-reference/en/functions/communication/wire/endTransmission/
- Wire.requestFrom() https://docs.arduino.cc/language-reference/en/functions/communication/wire/requestFrom/
- Wire.read() https://docs.arduino.cc/language-reference/en/functions/communication/wire/read/
- Wire.setClock() https://docs.arduino.cc/language-reference/en/functions/communication/wire/setClock/
- Wire.setWireTimeout() https://docs.arduino.cc/language-reference/en/functions/communication/wire/setWireTimeout/
- Arduino 教程:Inter-Integrated Circuit (I2C) Protocol https://docs.arduino.cc/learn/communication/wire/
- AVR 核心 Wire 源码 twi.c:https://github.com/arduino/ArduinoCore-avr/blob/master/libraries/Wire/src/utility/twi.c
- 语言参考源文件:https://github.com/arduino/reference-en
评价 (0)