RV1126B平台I2C驱动ADS1115实战：从硬件接线到应用层代码

1. 项目概述与核心思路

最近在折腾瑞芯微RV1126B这块板子，用的是EASY-EAI Nano-TB开发套件。项目里需要接几个传感器和一个小屏幕，I2C总线是绕不开的。虽然Linux内核已经把I2C驱动封装得很好了，但真要在应用层把它用起来、用稳了，特别是结合具体的硬件（比如我这里用的ADS1115模数转换器），还是有不少细节需要捋清楚。网上的资料要么太理论，只讲协议；要么太零散，给个代码就跑。所以，我把自己从硬件接线、环境搭建、代码编写到调试排错的全过程整理了一下，重点不是复述协议，而是分享在RV1126B这个具体平台上，如何快速、可靠地驱动一个真实I2C设备的实战经验。

这篇文章适合已经有一定Linux嵌入式基础，手头有EASY-EAI Nano-TB或类似RV1126/RV1109平台开发板，正准备或正在使用I2C外设的朋友。我会假设你已经搭好了基本的交叉编译环境，能编译和部署程序到板子上。我们的目标很明确：不深究波形时序，而是聚焦于如何利用Linux提供的标准接口，快速完成从设备树配置、应用层代码编写到数据读取的完整流程，并附上我踩过的坑和验证过的稳定方案。

2. RV1126B的I2C硬件资源与驱动框架解析

2.1 开发板I2C资源盘点与选择

EASY-EAI Nano-TB开发板为了保持接口的灵活性和体积，并没有把所有芯片的I2C控制器都引出来。根据官方资料，它主要预留并引出了一路I2C资源，标记为IIC_5。这一点非常重要，直接决定了我们硬件接线的目标引脚。

首先，我们需要确认这路I2C在Linux系统内对应的设备节点。通常，瑞芯微的SoC会集成多个I2C控制器，内核会根据设备树的配置，将它们依次编号为/dev/i2c-0、/dev/i2c-1……。对于EASY-EAI Nano-TB，其引出的IIC_5很可能对应的是/dev/i2c-2或/dev/i2c-4，具体需要查看板级设备树(dts)文件或直接在板子上查看。最直接的方法是登录开发板终端，执行ls /dev/i2c*命令。在我的板子上，显示有/dev/i2c-0到/dev/i2c-4，结合原理图，确认连接到物理接口IIC_5的是/dev/i2c-2。这里是个关键点：代码里打开的I2C设备节点必须和硬件连接的实际控制器匹配，否则操作会失败。

注意：不同版本的固件或自定义设备树可能会改变I2C控制器的编号。务必以你实际系统内的/dev目录下的文件为准。如果找不到对应的i2c设备节点，可能是内核配置中未启用该控制器驱动，需要检查内核配置或设备树。

2.2 Linux I2C子系统与用户空间接口

为什么在Linux下我们可以像读写文件一样操作I2C设备？这得益于Linux内核完善的I2C子系统。它分为三层：

1. I2C核心层：提供统一的框架和API，管理适配器（控制器）和驱动。
2. I2C总线驱动层（适配器驱动）：针对具体SoC的I2C控制器硬件，比如RV1126B的I2C IP核，实现底层的寄存器读写、中断处理、时钟控制等。
3. I2C设备驱动层（客户端驱动）：针对具体的I2C从设备，如ADS1115、EEPROM、触摸屏等，定义设备的地址、寄存器映射、读写方法等。

对于应用开发者，我们绝大多数时候并不需要去写内核设备驱动。内核的I2C核心层通过i2c-dev模块，向我们暴露了标准的字符设备接口。当我们在内核配置中启用CONFIG_I2C_CHARDEV后，系统就会为每个I2C控制器生成一个/dev/i2c-N的设备文件。我们只需要在用户空间，使用open()、ioctl()、read()、write()等标准系统调用，就能通过这个“文件”与I2C总线上的设备通信。

ioctl()是其中的灵魂，它用于发送控制命令，最重要的两个命令是：

• I2C_SLAVE或I2C_SLAVE_FORCE：设置我们要通信的从设备地址。
• I2C_RDWR：进行复杂的组合读写（一次I2C事务内包含写和读），这对于需要先发送寄存器地址再读数据的设备（如ADS1115）非常高效。

为了方便，EASY-EAI的示例代码里对这几个系统调用进行了封装，形成了iic_init,iic_set_addr,iic_read,iic_write等函数，让我们可以更直观地操作。

2.3 硬件接线实战与ADS1115模块简介

我选择ADS1115模块作为演示对象，因为它是一个典型的、带寄存器的I2C传感器，过程具有普遍参考意义。ADS1115是TI出品的一款16位高精度、低功耗模数转换器，有4个单端或2个差分输入通道，可通过I2C配置增益、数据速率和输入通道。

硬件连接示意图如下：

接线实操要点：

1. 电源确认：首先用万用表确认开发板I2C接口旁的3.3V和GND引脚电压正常。ADS1115模块的VDD必须接3.3V，接5V可能会损坏芯片。
2. 上拉电阻：I2C总线是开漏输出，SCL和SDA线必须通过上拉电阻接到电源（3.3V）。幸运的是，EASY-EAI Nano-TB开发板在IIC_5接口上大概率已经内置了上拉电阻（通常是4.7kΩ或10kΩ）。如果你使用杜邦线连接一个自己焊接的模块，且模块上没有上拉电阻，则必须在总线上（SCL和SDA）各添加一个上拉电阻到3.3V，否则通信无法进行。
3. 地址选择：务必根据ADS1115模块上ADDR引脚的实际接法，在代码中设置正确的设备地址。地址错误是最常见的“设备无响应”问题来源。
4. 线长与干扰：I2C标准模式速率100kbps，快速模式400kbps。在面包板上用杜邦线连接，线长尽量短（<20cm），并避免与电机、继电器等大电流器件靠得太近，防止干扰导致通信错误。

3. 开发环境搭建与例程源码剖析

3.1 编译环境准备与源码获取

EASY-EAI推荐在Ubuntu虚拟机中使用他们提供的Docker编译环境，这能保证库和工具链的一致性。步骤很常规：

# 1. 进入开发环境目录并启动（假设环境已按指南部署） cd ~/develop_environment ./run.sh # 此时会进入Docker容器内部 # 2. 在容器内创建并进入demo目录 cd /opt mkdir -p EASY-EAI-Nano-TB/demo cd EASY-EAI-Nano-TB/demo

接下来是获取源码。官方示例通常存放在网盘。下载后，你需要将整个08_IIC目录（或其他包含I2C例程的目录）上传到虚拟机中，并放置在上述demo目录下。你可以使用scp、sftp或者共享文件夹的方式。

实操心得：我更喜欢用scp命令从宿主机直接拷贝到Docker容器映射的目录。首先在宿主机找到Docker容器挂载到本地的路径，或者使用docker cp命令。更简单的方法是，在启动Docker时通过-v参数将宿主机的某个目录（如~/share）挂载到容器内的/mnt/share，这样源码放在宿主机~/share里，在容器内就能直接访问/mnt/share了。

3.2 例程编译与部署的深层解析

进入例程目录后，执行./build.sh。这个脚本干了以下几件关键事：

1. 设置交叉编译工具链：指定编译器为arm-rockchip830-linux-uclibcgnueabihf-gcc，针对RV1126B的ARM Cortex-A7核心。
2. 定义编译参数：如优化等级-O2，定义宏等。
3. 链接必要的库：RV1126B的SDK可能提供了一些硬件相关的库（如媒体处理库），但纯I2C操作一般只依赖标准C库。
4. 执行编译：将main.c、iic.c、ads1115.c等源文件编译链接成可执行文件test-ads1115。
5. 自动部署：通过scp或adb将生成的可执行文件推送到开发板的/userdata目录。这一步隐含了一个重要前提：你的开发板必须与编译主机在同一网络，并且开启了SSH服务，脚本里预设的IP地址和密码需要正确。

编译可能遇到的问题及解决：

• 错误：找不到交叉编译器：检查build.sh中CROSS_COMPILE变量的路径是否正确，或者检查工具链是否已正确安装并加入PATH环境变量。
• 错误：找不到头文件：检查-I参数指定的头文件路径是否存在，特别是commonApi目录是否在正确位置。
• 部署失败：连接超时：检查开发板IP地址是否变更，网络是否通畅。可以尝试手动scp部署：scp test-ads1115 root@192.168.1.xxx:/userdata/。

3.3 核心API封装层解读

例程中的commonApi/iic.c文件是对Linux原生I2C系统调用的一个简易封装，让我们来分析其实现，这有助于理解底层原理：

// iic_init: 打开I2C控制器设备文件 int iic_init(const char *device) { int fd = open(device, O_RDWR); // 以可读写方式打开，如 "/dev/i2c-2" if (fd < 0) { perror("Failed to open the i2c bus"); } return fd; } // iic_set_addr: 设置从设备地址 int iic_set_addr(int fd, uint8_t addr) { // 使用ioctl命令I2C_SLAVE，告诉内核后续读写针对哪个从设备 if (ioctl(fd, I2C_SLAVE, addr) < 0) { perror("Failed to set i2c device address"); return -1; } return 0; } // iic_write: 向I2C设备写入数据 int iic_write(int fd, uint8_t addr, uint8_t *buf, uint32_t len) { // 注意：这里先调用了iic_set_addr，确保地址已设置 iic_set_addr(fd, addr); // 直接使用write系统调用。一次I2C事务：START + 设备地址(写) + 数据 + STOP if (write(fd, buf, len) != len) { perror("iic write failed"); return -1; } return len; } // iic_read: 从I2C设备读取数据 int iic_read(int fd, uint8_t addr, uint8_t *buf, uint32_t len) { iic_set_addr(fd, addr); // 直接使用read系统调用。一次I2C事务：START + 设备地址(读) + 接收数据 + STOP if (read(fd, buf, len) != len) { perror("iic read failed"); return -1; } return len; }

封装层的局限性分析：这种write/read的封装简单直观，但对应的是最简单的I2C事务。对于像ADS1115这种需要“先写寄存器地址，再读数据”的操作，它用了两次独立的I2C事务（先iic_write发送指针，再iic_read读数据）。这虽然可行，但效率不是最高的，因为产生了两次START-STOP过程。更高效的方法是使用I2C_RDWRioctl，在一个原子操作内完成“写寄存器地址-读数据”的组合事务。不过，对于低速传感器，这种简化封装完全够用，且代码更清晰。

4. ADS1115驱动实现与数据读取全流程

4.1 ADS1115寄存器配置详解

要读取ADS1115的转换结果，必须正确配置其内部的配置寄存器。相关的宏定义通常在ads1115.h中：

#define ADS1115_ADDRESS 0x48 // ADDR引脚接地时的设备地址 #define ADS1015_REG_POINTER_CONVERT 0x00 // 转换结果寄存器地址 #define ADS1015_REG_POINTER_CONFIG 0x01 // 配置寄存器地址 // 配置寄存器高位字节 (Config High Byte) 示例 // OS[15]: 单次转换启动位 (1: 启动一次转换) // MUX[14:12]: 输入多路选择 (000: AIN0-AIN1差分, 001: AIN0-AIN3差分... 100: AIN0单端) // PGA[11:9]: 可编程增益放大器设置 (000: ±6.144V, 001: ±4.096V ...) // MODE[8]: 工作模式 (0: 连续转换, 1: 单次转换) #define CONFIG_REG_H_DEFAULT 0xC1 // 例如：单次转换，AIN0单端输入，±4.096V增益，单次模式 #define CONFIG_REG_L_DEFAULT 0x83 // 例如：128SPS数据速率，禁用比较器

配置过程在ads1115_config_register函数中完成：

int32_t ads1115_config_register(uint32_t fd, uint8_t configH, uint8_t configL) { // 要写入的数据：寄存器指针(0x01) + 配置高字节 + 配置低字节 uint8_t reg_data[3] = {ADS1015_REG_POINTER_CONFIG, configH, configL}; return iic_write(fd, ADS1115_ADDRESS, reg_data, sizeof(reg_data)); }

这个函数向ADS1115的配置寄存器（指针0x01）写入了两个字节的配置值。这里有一个关键细节：I2C传输时，很多设备（包括ADS1115）遵循“寄存器指针自动递增”的模式。当你写入一个寄存器地址后，后续的字节会自动写入到下一个连续的寄存器。但在这个例子里，我们只关心配置寄存器，所以一次性写完两个字节是没问题的。

4.2 数据读取与电压值换算

配置完成后，需要启动转换并读取结果。例程里ads1115_read_data函数的流程是：

1. 先向设备写入一个字节的ADS1015_REG_POINTER_CONVERT(0x00)，这相当于把内部的寄存器指针指向了“转换结果寄存器”。
2. 然后立即发起一次读操作，读取两个字节（16位数据）。
3. 将两个字节组合成一个16位有符号整数。

得到原始ADC值ad_val后，需要根据配置的PGA（增益）将其转换为实际的电压值。这是整个过程的数学核心。换算公式在ads1115_get_voltage_val函数的switch-case中体现：

double val = 0.0; switch((0x0E&configH)>>1) // 提取PGA位[11:9]，并右移1位得到索引 { case(0x00): // PGA = ±6.144V val = (double)ad_val * 187.5 / 1000000.0; // 分辨率 = 6.144V / 32768 = 187.5uV break; case(0x01): // PGA = ±4.096V val = (double)ad_val * 125 / 1000000.0; // 分辨率 = 4.096V / 32768 = 125uV break; // ... 其他增益档位 }

为什么是187.5uV？ADS1115是16位ADC，输出范围是-32768到+32767（有符号整数）。当PGA设置为±6.144V时，意味着输入电压从-6.144V到+6.144V，对应数字输出-32768到32767。所以，1个LSB（最低有效位）代表的电压值 = (6.144V * 2) / 65536 = 187.5微伏。同理，±4.096V档位时，1 LSB = (4.096 * 2) / 65536 = 125uV。

重要提示：ADS1115的输入电压必须在当前PGA设置的量程内。例如，如果设置PGA为±4.096V，那么输入AIN0的电压必须在GND-4.096V到GND+4.096V之间。如果超过，读到的值会固定在最大值（0x7FFF）或最小值（0x8000），代码中对此进行了检查并提示“超量程”。

4.3 主程序逻辑与稳定运行策略

主函数main的流程清晰体现了嵌入式传感器读数的典型模式：

1. 初始化：打开I2C设备文件(iic_init)，设置地址长度(7位)，设置从设备地址。
2. 配置：调用ads1115_get_voltage_val，该函数内部会先配置寄存器。
3. 循环读取：在一个while(1)循环中，每隔2秒读取一次电压值并打印。
4. 清理：退出循环后（本例中不会退出），关闭设备文件(iic_release)。

关于时序和延时的经验：在ads1115_get_voltage_val函数中，配置寄存器后有一个usleep(100 * 1000)，即100ms的延时。这个延时非常关键，它有两个作用：

• 等待转换完成：ADS1115在单次转换模式下，从启动转换到结果就绪需要一定时间，这个时间取决于设置的数据速率（Data Rate）。例如128SPS时，转换时间约7.8ms。100ms的等待给予了充足的时间。
• 总线稳定：避免连续发起I2C操作过快，导致总线状态未恢复。

在实际产品中，更好的做法不是固定延时，而是去查询配置寄存器的最高位（OS位），当该位由1变0时，表示转换完成。或者使用中断引脚（ALERT/RDY）。但对于快速验证和大多数应用，固定延时足够简单可靠。

5. 进阶应用与深度调试技巧

5.1 使用i2c-tools进行硬件诊断

在编写和调试代码之前或之中，强烈建议使用Linux社区强大的i2c-tools来验证硬件连接和基本通信。它可以直接在开发板上运行。

# 1. 安装i2c-tools (如果板子文件系统已包含) opkg update opkg install i2c-tools # 2. 探测I2C总线上的设备 i2cdetect -y 2 # 假设我们的总线是i2c-2

这条命令会扫描I2C-2总线上从地址0x03到0x77的所有设备。如果ADS1115连接正确且地址为0x48，你应该能看到48这个数字显示出来，而不是--。这是硬件和底层驱动正常的第一证明。

# 3. 读取ADS1115的ID寄存器（如果支持）或任意寄存器进行测试 # 首先，写入一个字节的寄存器指针（例如，指向设备ID寄存器，如果已知的话） # 然后，读取若干字节。但更通用的方法是使用i2cget（需知道寄存器地址格式） # 对于ADS1115，我们可以尝试读取配置寄存器 i2cget -y 2 0x48 0x01 w # 从地址0x48的设备，读取寄存器0x01（配置寄存器）的值（16位，word）

如果这条命令能返回一个16进制数（如0x8583），说明I2C通信完全正常，你可以根据数据手册解析这个配置值。如果返回错误（如Error: Read failed），则说明通信失败，需要检查硬件连接、电源、上拉电阻和设备地址。

5.2 实现高效的组合传输（I2C_RDWR）

如前所述，例程中先写后读的方式效率稍低。我们可以使用ioctl的I2C_RDWR命令进行优化。下面是一个改进版的ads1115_read_data函数示例：

int16_t ads1115_read_data_enhanced(uint32_t fd) { struct i2c_rdwr_ioctl_data packets; struct i2c_msg messages[2]; uint8_t reg_addr = ADS1015_REG_POINTER_CONVERT; uint8_t rx_data[2] = {0}; // 第一个消息：写入寄存器地址（无STOP） messages[0].addr = ADS1115_ADDRESS; messages[0].flags = 0; // 写 messages[0].len = 1; messages[0].buf = &reg_addr; // 第二个消息：读取数据 messages[1].addr = ADS1115_ADDRESS; messages[1].flags = I2C_M_RD; // 读 messages[1].len = 2; messages[1].buf = rx_data; packets.msgs = messages; packets.nmsgs = 2; if (ioctl(fd, I2C_RDWR, &packets) < 0) { perror("Failed to perform combined I2C transaction"); return -1; } int16_t data = (rx_data[0] << 8) | rx_data[1]; return data; }

这种方法将“写寄存器指针”和“读数据”合并为一次I2C事务：START + 地址(写) + 寄存器指针 + RESTART + 地址(读) + 数据 + STOP。它更符合I2C协议的标准用法，减少了总线操作次数，在多点通信或高数据速率场景下更有优势。注意：使用I2C_RDWR需要包含<linux/i2c-dev.h>和<linux/i2c.h>头文件。

5.3 多设备管理与错误重试机制

在实际项目中，一条I2C总线上可能挂载多个设备。管理它们的关键是确保每次操作前正确设置目标设备地址。封装一个简单的设备管理器是好的实践：

typedef struct { int bus_fd; uint8_t addr; char name[32]; } i2c_device_t; i2c_device_t dev_ads1115 = { .bus_fd = -1, .addr = 0x48, .name = "ADS1115"}; i2c_device_t dev_eeprom = { .bus_fd = -1, .addr = 0x50, .name = "24C02"}; int i2c_device_init(i2c_device_t *dev, const char* bus_path) { if (dev->bus_fd < 0) { dev->bus_fd = iic_init(bus_path); if (dev->bus_fd < 0) return -1; } if (iic_set_addr(dev->bus_fd, dev->addr) < 0) return -1; printf("Device %s initialized on %s, addr 0x%02X\n", dev->name, bus_path, dev->addr); return 0; }

对于工业或可靠性要求高的场景，I2C通信需要增加错误重试机制。因为I2C容易受到瞬时干扰。

int iic_write_with_retry(int fd, uint8_t addr, uint8_t *buf, uint32_t len, int max_retries) { int retry = 0; int result; while (retry < max_retries) { result = iic_write(fd, addr, buf, len); if (result == len) { return result; // 成功 } retry++; usleep(10 * 1000); // 重试前稍作等待 fprintf(stderr, "I2C write failed, retrying (%d/%d)...\n", retry, max_retries); } fprintf(stderr, "I2C write failed after %d retries.\n", max_retries); return -1; }

6. 常见问题排查与实战心得

6.1 问题速查表

6.2 调试心得与进阶建议

1. 示波器/逻辑分析仪是终极武器：当软件排查无从下手时，用示波器看SCL和SDA的波形。检查START/STOP条件、ACK信号、数据位是否正常。可以清晰看到是主机没发信号，还是从机没回复ACK。

2. 上拉电阻的取值：虽然4.7kΩ或10kΩ是常用值，但最佳值取决于总线电容和通信速度。总线越长、设备越多，电容越大，上升沿越缓，可能导致超时。可以适当减小上拉电阻（如2.2kΩ）以增强驱动能力，但会增加功耗。用示波器观察上升时间，确保满足协议要求。

3. RV1126B的I2C控制器驱动：如果遇到极其顽固的通信问题，可以尝试调整内核驱动参数。例如，通过设备树可以修改I2C时钟频率(clock-frequency)。默认可能是100kHz，对于某些老设备可能需要调低。也可以检查是否有重复起始信号（Repeated START）的支持问题。

4. 从机地址的7位与8位：Linux I2C子系统使用7位设备地址。而有些设备手册会给出8位地址（包含读写位）。务必注意转换：7位地址是8位地址右移1位。例如，ADS1115的8位写地址是0x90，读地址是0x91。其7位地址就是0x90 >> 1 = 0x48。

5. 代码健壮性：在生产代码中，要对所有I2C函数调用进行严格的返回值检查，并记录错误日志。考虑加入看门狗机制，如果传感器长时间无响应，能触发系统复位或报警。

这次在RV1126B上折腾I2C和ADS1115，让我再次体会到嵌入式开发中“软硬结合”的真谛。原理图、万用表、逻辑分析仪这些硬件工具，与i2c-tools、内核日志这些软件工具同等重要。把Linux提供的标准接口用熟用稳，能解决90%的通信问题。剩下的10%，就需要你沉下心来，对照波形和数据手册，一点点抠细节了。最后，分享一个习惯：每接入一个新的I2C设备，我都会先建一个简单的测试程序，只做最基本的读写验证，通了之后再叠加上层的业务逻辑，这样能最快地定位问题是出在硬件连接、驱动配置还是应用逻辑上。