lbaihao

I2C 总线设备

I2C 简介

I2C（Inter Integrated Circuit）总线是 PHILIPS 公司开发的一种半双工、双向二线制同步串行总线。I2C 总线传输数据时只需两根信号线，一根是双向数据线 SDA（serial data），另一根是双向时钟线 SCL（serial clock）。SPI 总线有两根线分别用于主从设备之间接收数据和发送数据，而 I2C 总线只使用一根线进行数据收发。

I2C 和 SPI 一样以主从的方式工作，不同于 SPI 一主多从的结构，它允许同时有多个主设备存在，每个连接到总线上的器件都有唯一的地址，主设备启动数据传输并产生时钟信号，从设备被主设备寻址，同一时刻只允许有一个主设备。如下图所示：

如下图所示为 I2C 总线主要的数据传输格式：

当总线空闲时，SDA 和 SCL 都处于高电平状态，当主机要和某个从机通讯时，会先发送一个开始条件，然后发送从机地址和读写控制位，接下来传输数据（主机发送或者接收数据），数据传输结束时主机会发送停止条件。传输的每个字节为8位，高位在前，低位在后。数据传输过程中的不同名词详解如下所示：

开始条件： SCL 为高电平时，主机将 SDA 拉低，表示数据传输即将开始。
从机地址： 主机发送的第一个字节为从机地址，高 7 位为地址，最低位为 R/W 读写控制位，1 表示读操作，0 表示写操作。一般从机地址有 7 位地址模式和 10 位地址模式两种，如果是 10 位地址模式，第一个字节的头 7 位是 11110XX 的组合，其中最后两位（XX）是 10 位地址的两个最高位，第二个字节为 10 位从机地址的剩下8位，如下图所示：

应答信号： 每传输完成一个字节的数据，接收方就需要回复一个 ACK（acknowledge）。写数据时由从机发送 ACK，读数据时由主机发送 ACK。当主机读到最后一个字节数据时，可发送 NACK（Not acknowledge）然后跟停止条件。
数据： 从机地址发送完后可能会发送一些指令，依从机而定，然后开始传输数据，由主机或者从机发送，每个数据为 8 位，数据的字节数没有限制。
重复开始条件： 在一次通信过程中，主机可能需要和不同的从机传输数据或者需要切换读写操作时，主机可以再发送一个开始条件。
停止条件： 在 SDA 为低电平时，主机将 SCL 拉高并保持高电平，然后在将 SDA 拉高，表示传输结束。
使用正点原子的潘多拉开发板的例程07_driver_temp_humi进行说明：

在drv_i2c.c文件中使用INIT_BOARD_EXPORT(hw_i2c_init);即RT-Thread中的自动化初始机制，经过层层调用，最终使用rt_device_register()函数将I2C总线注册至I/O设备管理器。函数调用的顺序如下：

hw_i2c_init(【drv_i2c.c】)--->rt_i2c_bit_add_bus(【i2c-bit-ops.c】)--->rt_i2c_bus_device_register(【i2c_core.c】)--->rt_i2c_bus_device_device_init(【i2c_dev.c】)--->rt_device_register(【device.c】)

【drv_i2c.c】：设置I2C总线名称、I2C总线具体操作的引脚、初始化I2C引脚、定义STM32对I2C引脚电平读和写的函数、定义STM32中uS级延时函数、使用hw_i2c_init函数将这些设置的内容传入系统

stm32_i2c_gpio_init
stm32_set_sda
stm32_set_scl_s
stm32_set_scl
stm32_get_sda
stm32_get_scl_s
stm32_get_scl
stm32_udelay
stm32_i2c_bus_unlock
hw_i2c_init
【i2c-bit-ops.c】：通过对drv_i2c.c文件中提供的对引脚电平操作函数的封装实现i2c中的起始信号、终止信号、数据传输等函数，最后调用rt_i2c_bit_add_bus函数将数据传输函数传入

i2c_delay
i2c_delay2
SCL_H
i2c_start
i2c_restart
i2c_stop
i2c_waitack
i2c_writeb
i2c_readb
i2c_send_bytes
i2c_send_ack_or_nack
i2c_recv_bytes
i2c_send_address
i2c_bit_send_address4
i2c_bit_xfer
rt_i2c_bit_add_bus
【i2c_core.c】：实现i2c总线设备的注册、查找和数据传输函数

rt_i2c_bus_device_register
rt_i2c_bus_device_find
rt_i2c_transfer
rt_i2c_master_send
rt_i2c_master_recv
rt_i2c_core_init
【i2c_dev.c】：实现i2c_bus_device_read、i2c_bus_device_write、i2c_bus_device_control等I2C中的通用控制函数，通过rt_i2c_bus_device_device_init调用rt_device_register函数最终将I2C总线注册到I/O设备管理器中

i2c_bus_device_read
i2c_bus_device_write
i2c_bus_device_control
rt_i2c_bus_device_device_init

访问 I2C 总线设备

一般情况下 MCU 的 I2C 器件都是作为主机和从机通讯，在 RT-Thread 中将 I2C 主机虚拟为 I2C总线设备，I2C 从机通过 I2C 设备接口和 I2C 总线通讯，相关接口如下所示：

函数	描述
rt_device_find()	根据 I2C 总线设备名称查找设备获取设备句柄
rt_i2c_transfer()	传输数据

查找 I2C 总线设备

在使用 I2C 总线设备前需要根据 I2C 总线设备名称获取设备句柄，进而才可以操作 I2C 总线设备，查找设备函数如下所示，

rt_device_t rt_device_find(const char* name);复制错误复制成功

参数	描述
name	I2C 总线设备名称
返回	——
设备句柄	查找到对应设备将返回相应的设备句柄
RT_NULL	没有找到相应的设备对象

一般情况下，注册到系统的 I2C 设备名称为 i2c0 ，i2c1等，使用示例如下所示：

#define AHT10_I2C_BUS_NAME      "i2c1"  /* 传感器连接的I2C总线设备名称 */
struct rt_i2c_bus_device *i2c_bus;      /* I2C总线设备句柄 */

/* 查找I2C总线设备，获取I2C总线设备句柄 */
i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name);复制错误复制成功

数据传输

获取到 I2C 总线设备句柄就可以使用 rt_i2c_transfer() 进行数据传输。函数原型如下所示：

rt_size_t rt_i2c_transfer(struct rt_i2c_bus_device *bus,
                          struct rt_i2c_msg         msgs[],
                          rt_uint32_t               num);复制错误复制成功

参数	描述
bus	I2C 总线设备句柄
msgs[]	待传输的消息数组指针
num	消息数组的元素个数
返回	——
消息数组的元素个数	成功
错误码	失败

和 SPI 总线的自定义传输接口一样，I2C 总线的自定义传输接口传输的数据也是以一个消息为单位。参数 msgs[] 指向待传输的消息数组，用户可以自定义每条消息的内容，实现 I2C 总线所支持的 2 种不同的数据传输模式。如果主设备需要发送重复开始条件，则需要发送 2 个消息。

Note

注：此函数会调用 rt_mutex_take(), 不能在中断服务程序里面调用，会导致 assertion 报错。

I2C 消息数据结构原型如下：

struct rt_i2c_msg
{
    rt_uint16_t addr;    /* 从机地址 */
    rt_uint16_t flags;   /* 读、写标志等 */
    rt_uint16_t len;     /* 读写数据字节数 */
    rt_uint8_t  *buf;    /* 读写数据缓冲区指针　*/
}复制错误复制成功

从机地址 addr：支持 7 位和 10 位二进制地址，需查看不同设备的数据手册。

Note

注：RT-Thread I2C 设备接口使用的从机地址均不包含读写位，读写位控制需修改标志 flags。

标志 flags 可取值为以下宏定义，根据需要可以与其他宏使用位运算 “|” 组合起来使用。

#define RT_I2C_WR              0x0000        /* 写标志，不可以和读标志进行“|”操作 */
#define RT_I2C_RD              (1u << 0)     /* 读标志，不可以和写标志进行“|”操作 */
#define RT_I2C_ADDR_10BIT      (1u << 2)     /* 10 位地址模式 */
#define RT_I2C_NO_START        (1u << 4)     /* 无开始条件 */
#define RT_I2C_IGNORE_NACK     (1u << 5)     /* 忽视 NACK */
#define RT_I2C_NO_READ_ACK     (1u << 6)     /* 读的时候不发送 ACK */
#define RT_I2C_NO_STOP         (1u << 7)     /* 不发送结束位 */复制错误复制成功

使用示例如下所示：

#define AHT10_I2C_BUS_NAME      "i2c1"  /* 传感器连接的I2C总线设备名称 */
#define AHT10_ADDR               0x38   /* 从机地址 */
struct rt_i2c_bus_device *i2c_bus;      /* I2C总线设备句柄 */

/* 查找I2C总线设备，获取I2C总线设备句柄 */
i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name);

/* 读传感器寄存器数据 */
static rt_err_t read_regs(struct rt_i2c_bus_device *bus, rt_uint8_t len, rt_uint8_t *buf)
{
    struct rt_i2c_msg msgs;

    msgs.addr = AHT10_ADDR;     /* 从机地址 */
    msgs.flags = RT_I2C_RD;     /* 读标志 */
    msgs.buf = buf;             /* 读写数据缓冲区指针　*/
    msgs.len = len;             /* 读写数据字节数 */

    /* 调用I2C设备接口传输数据 */
    if (rt_i2c_transfer(bus, &msgs, 1) == 1)
    {
        return RT_EOK;
    }
    else
    {
        return -RT_ERROR;
    }
}复制错误复制成功

I2C 从设备数据读写API

以下两个读写函数封装自 rt_i2c_transfer() 函数，用于读写I2C从设备的数据，更加简单易用，推荐使用。

向 I2C 从设备发送数据：

rt_size_t rt_i2c_master_send(struct rt_i2c_bus_device *bus,
                             rt_uint16_t               addr,
                             rt_uint16_t               flags,
                             const rt_uint8_t         *buf,
                             rt_uint32_t               count);复制错误复制成功

参数	描述
bus	I2C 总线设备句柄
addr	I2C 从设备地址
flags	标志位，可为上文提到的除 `RT_I2C_WR` `RT_I2C_RD`之外的其他标志位，可以进行 “\|” 操作
buf	待数据数据缓冲区
count	待发送数据大小（单位：字节）
返回	——
消息数组的元素个数	成功
错误码	失败

从 I2C 从设备读取数据，数据会放在缓冲区中：

rt_size_t rt_i2c_master_recv(struct rt_i2c_bus_device *bus,
                             rt_uint16_t               addr,
                             rt_uint16_t               flags,
                             rt_uint8_t               *buf,
                             rt_uint32_t               count);复制错误复制成功

参数	描述
bus	I2C 总线设备句柄
addr	I2C 从设备地址
flags	标志位，可为上文提到的除 `RT_I2C_WR` `RT_I2C_RD`之外的其他标志位，可以进行 “\|” 操作
buf	数据缓冲区
count	缓冲区大小（单位：字节，要大于等于最大接收到的数据长度）
返回	——
消息数组的元素个数	成功
错误码	失败

小技巧

有时，I2C数据需要通过多次函数拼接而成，通过如下方法，可以实现拼接发送一条I2C数据，数据内容为 prefix_buffer + buffer：

rt_i2c_master_send(_i2c_bus_dev, _addr, RT_I2C_NO_STOP, prefix_buffer, prefix_len); /* 只发送起始位，不发送停止位 */
rt_i2c_master_send(_i2c_bus_dev, _addr, RT_I2C_NO_START, buffer, len); /* 不发送起始位，只发送停止位 */复制错误复制成功