ESP32学习笔记（17）——I2C接口使用

Posted 2021-05-16 Leung_ManWah

一、I2C简介

I2C（Inter-Integrated Circuit ,内部集成电路) 总线是一种由飞利浦 Philip 公司开发的串行总线。是两条串行的总线，它由一根数据线（SDA）和一根 时钟线（SDL）组成。两条线都需要上拉电阻。I2C 总线上可以接多个 I2C 设备，每个器件都有一个唯一的地址识别。同一时间只能有一个主设备，其他为从设备。通常 MCU 作为主设备控制，外设作为从设备。

ESP32有两个I2C控制器（也称为端口），负责处理I2C总线上的通信。每个I2C控制器都可以作为主机或从机运行。

ESP-IDF 编程指南——I2C

二、API说明

以下 I2C 接口位于 driver/include/driver/i2c.h。

2.1 i2c_param_config

2.2 i2c_driver_install

2.3 i2c_cmd_link_create

2.4 i2c_master_start

2.5 i2c_master_write_byte

2.6 i2c_master_write

2.7 i2c_master_read_byte

2.8 i2c_master_read

2.9 i2c_master_stop

2.10 i2c_master_cmd_begin

2.11 i2c_cmd_link_delete

三、编程流程

3.1 设置通信参数

要建立I2C通信，请先配置驱动程序。这是通过设置结构的参数来完成的i2c_config_t：

• 设置I2C操作模式-从机或主机i2c_mode_t

• 配置通讯引脚

  • 为SDA和SCL信号分配GPIO引脚
  • 设置是否启用ESP32的内部上拉电路

• （仅限主机）设置I2C时钟速度

• （仅限从机）配置以下内容

  • 是否启用10位地址模式
  • 定义从机地址

之后，初始化给定I2C端口的配置。为此，调用函数i2c_param_config()并将端口号和结构传递给该函数i2c_config_t。

配置示例（主机）：

int i2c_master_port = 0;
i2c_config_t conf = {
    .mode = I2C_MODE_MASTER,
    .sda_io_num = I2C_MASTER_SDA_IO,         // select GPIO specific to your project
    .sda_pullup_en = GPIO_PULLUP_ENABLE,
    .scl_io_num = I2C_MASTER_SCL_IO,         // select GPIO specific to your project
    .scl_pullup_en = GPIO_PULLUP_ENABLE,
    .master.clk_speed = I2C_MASTER_FREQ_HZ,  // select frequency specific to your project
    // .clk_flags = 0,          /*!< Optional, you can use I2C_SCLK_SRC_FLAG_* flags to choose i2c source clock here. */
};

配置示例（从机）：

int i2c_slave_port = I2C_SLAVE_NUM;
i2c_config_t conf_slave = {
    .sda_io_num = I2C_SLAVE_SDA_IO,          // select GPIO specific to your project
    .sda_pullup_en = GPIO_PULLUP_ENABLE,
    .scl_io_num = I2C_SLAVE_SCL_IO,          // select GPIO specific to your project
    .scl_pullup_en = GPIO_PULLUP_ENABLE,
    .mode = I2C_MODE_SLAVE,
    .slave.addr_10bit_en = 0,
    .slave.slave_addr = ESP_SLAVE_ADDR,      // address of your project
};

3.2 驱动程序安装

配置I2C驱动程序后，通过i2c_driver_install()使用以下参数调用该函数来安装它：

• 端口号，来自的两个端口号之一 i2c_port_t

• 主机或从机，选自 i2c_mode_t

• （仅限从机）为发送和接收数据分配的缓冲区大小。由于I2C是以主机为中心的总线，因此，只有在主机请求时，数据才能从从机传输到主机。因此，从设备通常将具有一个发送缓冲区，从设备在其中写入应用程序数据。数据保留在发送缓冲区中，由主机自行决定是否由主机读取。

• 用于分配中断的标志（请参阅esp_hw_support / include / esp_intr_alloc.h中的ESP_INTR_FLAG_ *值）

3.3 运行I2C通信

安装I2C驱动程序后，ESP32已准备好与其他I2C设备通信。

ESP32的I2C控制器作为主设备负责与I2C从设备建立通信，并发送命令以触发从设备采取行动，例如进行测量并将读数发送回主设备。

为了更好地进行流程组织，驱动程序提供了一个称为“命令链接”的容器，该容器应填充一系列命令，然后传递给I2C控制器以执行。

3.3.1 作为主机通信

• 主机写
  下面的示例显示了如何为I2C主设备构建命令链接，以将n个字节发送给从设备。
  

1. 使用创建一个命令链接i2c_cmd_link_create()。
   然后，用要发送到从站的一系列数据填充它：

   1. 起始位-i2c_master_start()
   2. 从机地址- i2c_master_write_byte()。提供单字节地址作为此函数调用的参数。
   3. 数据-一个或多个字节作为参数i2c_master_write()
   4. 停止位-i2c_master_stop()

   这两个函数i2c_master_write_byte()和i2c_master_write()具有一个额外的参数指定所述主是否应当确保它已经接收到ACK位。

2. 通过调用触发I2C控制器执行命令链接i2c_master_cmd_begin()。一旦触发执行，就不能修改命令链接。

3. 传输命令后，通过调用释放命令链接使用的资源i2c_cmd_link_delete()。

• 主机读
  下面的示例显示了如何为I2C主机构建命令链接以从从机读取n个字节。
  
  与写入数据相比，第4步中的命令链接不是使用i2c_master_write...函数而是使用i2c_master_read_byte()或i2c_master_read()。同样，配置步骤5中的最后一次读取，以便主机不提供ACK位。

• 写或读指示
  发送从机地址后（请参见上图两个步骤中的步骤3），主机会和从机进行写入或读取。

有关主机实际操作的信息隐藏在从机地址的最低有效位中。

因此，主机发送的用于将数据写入从机的命令链接包含该地址，如下所示：(ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE

i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE, ACK_EN);

同样，从从站读取的命令链接如下所示：

i2c_master_write_byte(cmd, (ESP_SLAVE_ADDR << 1) | I2C_MASTER_READ, ACK_EN);

3.3.2 作为从机通信

安装I2C驱动程序后，ESP32已准备好与其他I2C设备通信。

该API为从机提供以下功能

• i2c_slave_read_buffer()
  当主机将数据写入从机时，从机将自动将其存储在接收缓冲区中。这允许从机应用程序i2c_slave_read_buffer()自行决定调用该函数。如果接收缓冲区中没有数据，此函数还具有一个参数，用于指定块时间。这将允许从机应用程序在指定的超时时间内等待数据到达缓冲区。

• i2c_slave_write_buffer()
  发送缓冲区用于存储从设备要以FIFO顺序发送给主设备的所有数据。数据将一直保留在那里，直到主设备请求为止。该函数i2c_slave_write_buffer()具有一个参数，用于指定发送缓冲区已满时的阻止时间。这将允许从机应用程序在指定的超时时间内等待发送缓冲区中足够的可用空间。

四、ESP32作为主机与BH1750光照强度传感器通信

根据 esp-idf\\examples\\peripherals\\i2c\\i2c_self_test 中的例程修改
SCL 为 GPIO23
SDA 为 GPIO18

#include <stdio.h>
#include "esp_log.h"
#include "driver/i2c.h"

static const char *TAG = "i2c-example";

#define I2C_MASTER_SCL_IO GPIO_NUM_23           /*!< gpio number for I2C master clock */
#define I2C_MASTER_SDA_IO GPIO_NUM_18           /*!< gpio number for I2C master data  */
#define I2C_MASTER_NUM 1                        /*!< I2C port number for master dev */
#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 WRITE_BIT I2C_MASTER_WRITE              /*!< I2C master write */
#define READ_BIT I2C_MASTER_READ                /*!< I2C master read */
#define ACK_CHECK_EN 0x1                        /*!< I2C master will check ack from slave*/
#define ACK_CHECK_DIS 0x0                       /*!< I2C master will not check ack from slave */
#define ACK_VAL 0x0                             /*!< I2C ack value */
#define NACK_VAL 0x1                            /*!< I2C nack value */

#define BH1750_SLAVE_ADDR   0x23 // 从机地址
#define BH1750_PWR_DOWN     0x00 // 关闭模块
#define BH1750_PWR_ON       0x01 // 打开模块等待测量指令
#define BH1750_RST          0x07 // 重置数据寄存器值在PowerOn模式下有效
#define BH1750_CON_H        0x10 // 连续高分辨率模式，1lx，120ms
#define BH1750_CON_H2       0x11 // 连续高分辨率模式，0.5lx，120ms
#define BH1750_CON_L        0x13 // 连续低分辨率模式，4lx，16ms
#define BH1750_ONE_H        0x20 // 一次高分辨率模式，1lx，120ms，测量后模块转到PowerDown模式
#define BH1750_ONE_H2       0x21 // 一次高分辨率模式，0.5lx，120ms，测量后模块转到PowerDown模式
#define BH1750_ONE_L        0x23 // 一次低分辨率模式，4lx，16ms，测量后模块转到PowerDown模式

SemaphoreHandle_t print_mux = NULL;

/**
 @brief I2C驱动初始化
 @param 无
 @return 无
*/
int I2C_Init(void)
{
    int i2c_master_port = I2C_MASTER_NUM;
    i2c_config_t conf;
    conf.mode = I2C_MODE_MASTER;
    conf.sda_io_num = I2C_MASTER_SDA_IO;
    conf.sda_pullup_en = GPIO_PULLUP_ENABLE;
    conf.scl_io_num = I2C_MASTER_SCL_IO;
    conf.scl_pullup_en = GPIO_PULLUP_ENABLE;
    conf.master.clk_speed = I2C_MASTER_FREQ_HZ;
    i2c_param_config(i2c_master_port, &conf);
    return i2c_driver_install(i2c_master_port, conf.mode, I2C_MASTER_RX_BUF_DISABLE, I2C_MASTER_TX_BUF_DISABLE, 0);
}

/**
 @brief I2C写数据函数
 @param slaveAddr -[in] 从设备地址
 @param regAddr -[in] 寄存器地址
 @param pData -[in] 写入数据
 @param dataLen -[in] 写入数据长度
 @return 错误码
*/
int I2C_WriteData(uint8_t slaveAddr, uint8_t regAddr, uint8_t *pData, uint16_t dataLen)
{
    int ret;
    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
    i2c_master_start(cmd);
    i2c_master_write_byte(cmd, (slaveAddr << 1) | WRITE_BIT, ACK_CHECK_EN);
    if(NULL != regAddr)
    {
        i2c_master_write_byte(cmd, regAddr, ACK_CHECK_EN);
    }
    i2c_master_write(cmd, pData, dataLen, ACK_CHECK_EN);
    i2c_master_stop(cmd);
    ret = i2c_master_cmd_begin(1, cmd, 1000 / portTICK_RATE_MS);
    i2c_cmd_link_delete(cmd);
    return ret;
}

/**
 @brief I2C读数据函数
 @param slaveAddr -[in] 从设备地址
 @param regAddr -[in] 寄存器地址
 @param pData -[in] 读出数据
 @param dataLen -[in] 读出数据长度
 @return 错误码
*/
int I2C_ReadData(uint8_t slaveAddr, uint8_t regAddr, uint8_t *pData, uint16_t dataLen)
{
    int ret;
    i2c_cmd_handle_t cmd = i2c_cmd_link_create();
    i2c_master_start(cmd);
    i2c_master_write_byte(cmd, (slaveAddr << 1) | READ_BIT, ACK_CHECK_EN);
    if(NULL != regAddr)
    {
        i2c_master_write_byte(cmd, regAddr, ACK_CHECK_EN);
    }
    i2c_master_read(cmd, pData, dataLen, ACK_VAL);
    i2c_master_stop(cmd);
    ret = i2c_master_cmd_begin(1, cmd, 1000 / portTICK_RATE_MS);
    i2c_cmd_link_delete(cmd);
    return ret;
}

static void i2c_test_task(void *arg)
{
    int ret;
    uint8_t sensor_data[2] = {0};
    uint8_t sensor_data_h, sensor_data_l;
    int cnt = 0;
    uint8_t data;

    while (1) {
        ESP_LOGI(TAG, "test cnt: %d", cnt++);
        data = BH1750_PWR_ON;              // 发送启动命令
        I2C_WriteData(BH1750_SLAVE_ADDR, NULL, &data, 1);
        data = BH1750_ONE_L;               // 设置一次低分辨率模式，测量后模块转到PowerDown模式
        I2C_WriteData(BH1750_SLAVE_ADDR, NULL, &data, 1);
        vTaskDelay(30 / portTICK_RATE_MS); // 设置完成后要有一段延迟
        ret = I2C_ReadData(BH1750_SLAVE_ADDR, NULL, sensor_data, 2);
        sensor_data_h = sensor_data[0];
        sensor_data_l = sensor_data[1];
        // ret = i2c_master_sensor_test(I2C_MASTER_NUM, &sensor_data_h, &sensor_data_l);
        xSemaphoreTake(print_mux, portMAX_DELAY);
        if (ret == ESP_ERR_TIMEOUT) {
            ESP_LOGE(TAG, "I2C Timeout");
        } else if (ret == ESP_OK) {
            printf("*******************\\n");
            printf("MASTER READ SENSOR( BH1750 )\\n");
            printf("*******************\\n");
            printf("data_h: %02x\\n", sensor_data_h);
            printf("data_l: %02x\\n", sensor_data_l);
            printf("sensor val: %.02f [Lux]\\n", (sensor_data_h << 8 | sensor_data_l) / 1.2);
        } else {
            ESP_LOGW(TAG, "%s: No ack, sensor not connected...skip...", esp_err_to_name(ret));
        }
        xSemaphoreGive(print_mux);
        vTaskDelay(1000 / portTICK_RATE_MS);
    }
    vSemaphoreDelete(print_mux);
    vTaskDelete(NULL);
}

void app_main(void)
{
    print_mux = xSemaphoreCreateMutex();
    ESP_ERROR_CHECK(I2C_Init());
    xTaskCreate(i2c_test_task, "i2c_test_task_0", 1024 * 2, NULL, 10, NULL);
}

查看打印：

---

• 由 Leung 写于 2021 年 5 月 13 日

• 参考：第十二章 ESP32读取SHT30的温湿度（IIC）
　　　　ESP32 开发笔记(三）源码示例 10_IIC_ADXL345 使用IIC总线实现读取ADXL345角度加速度传感器