I2C 驱动程序

[English]

概述

I2C 是一种串行同步半双工式通信协议，总线上可以同时挂载多个主机和从机。I2C 总线由串行数据线 (SDA) 线和串行时钟线 (SCL) 线构成。这些线都需要上拉电阻。

I2C 具有简单且制造成本低廉等优点，主要用于低速外围设备的短距离通信（一英尺以内）。

ESP32 有两个 I2C 控制器（也称为端口），负责处理在 I2C 两根总线上的通信。每个控制器都可以设置为主机或从机。例如，可以同时让一个控制器用作主机，另一个用作从机。

驱动程序的功能

I2C 驱动程序管理在 I2C 总线上设备的通信，该驱动程序具备以下功能：

• 在主机模式下读写字节

• 支持从机模式

• 读取并写入寄存器，然后由主机读取/写入

使用驱动程序

以下部分将指导您完成 I2C 驱动程序配置和工作的基本步骤：

1. 配置驱动程序 - 设置初始化参数（如主机模式或从机模式，SDA 和 SCL 使用的 GPIO 管脚，时钟速度等）

2. 安装驱动程序- 激活一个 I2C 控制器的驱动，该控制器可为主机也可为从机

3. 根据是为主机还是从机配置驱动程序，选择合适的项目

   1. 主机模式下通信 - 发起通信（主机模式）

   2. 从机模式下通信 - 响应主机消息（从机模式）

4. 中断处理 - 配置和 I2C 中断服务

5. 用户自定义配置 - 调整默认的 I2C 通信参数（如时序、位序等）

6. 错误处理 - 如何识别和处理驱动程序配置和通信错误

7. 删除驱动程序- 在通信结束时释放 I2C 驱动程序所使用的资源

配置驱动程序

建立 I2C 通信第一步是配置驱动程序，这需要设置 i2c_config_t 结构中的几个参数：

• 设置 I2C 工作模式 - 从 i2c_mode_t 中选择主机模式或从机模式

• 设置 通信管脚

  • 指定 SDA 和 SCL 信号使用的 GPIO 管脚

  • 是否启用 ESP32 的内部上拉电阻

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

• （仅限从机模式）设置以下内容：

  • 是否应启用 10 位寻址模式

  • 定义 从机地址

然后，初始化给定 I2C 端口的配置，请使用端口号和 i2c_config_t 作为函数调用参数来调用 i2c_param_config() 函数。

在此阶段，i2c_param_config() 还将其他 I2C 配置参数设置为 I2C 总线协议规范中定义的默认值。有关默认值及修改默认值的详细信息，请参考 用户自定义配置。

安装驱动程序

配置好 I2C 驱动程序后，使用以下参数调用函数 i2c_driver_install() 安装驱动程序:

• 端口号，从 i2c_port_t 中二选一

• 主机或从机模式，从 i2c_mode_t 中选择

• （仅限从机模式）分配用于在从机模式下发送和接收数据的缓存区大小。I2C 是一个以主机为中心的总线，数据只能根据主机的请求从从机传输到主机。因此，从机通常有一个发送缓存区，供从应用程序写入数据使用。数据保留在发送缓存区中，由主机自行读取。

• 用于分配中断的标志（请参考 ESP_INTR_FLAG_* values in esp_system/include/esp_intr_alloc.h）

主机模式下通信

安装 I2C 驱动程序后， ESP32 即可与其他 I2C 设备通信。

ESP32 的 I2C 控制器在主机模式下负责与 I2C 从机设备建立通信，并发送命令让从机响应，如进行测量并将结果发给主机。

为优化通信流程，驱动程序提供一个名为 “命令链接” 的容器，该容器应填充一系列命令，然后传递给 I2C 控制器执行。

主机写入数据

下面的示例展示如何为 I2C 主机构建命令链接，从而向从机发送 n 个字节。

I2C command link - master write example

下面介绍如何为 “主机写入数据” 设置命令链接及其内部内容：

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_master_cmd_begin() 来触发 I2C 控制器执行命令链接。一旦开始执行，就不能再修改命令链接。

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

主机读取数据

下面的示例展示如何为 I2C 主机构建命令链接，以便从从机读取 n 个字节。

I2C command link - master read example

在读取数据时，在上图的步骤 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);

从机模式下通信

安装 I2C 驱动程序后， ESP32 即可与其他 I2C 设备通信。

API 为从机提供以下功能：

• i2c_slave_read_buffer()

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

• i2c_slave_write_buffer()

  发送缓存区是用于存储从机要以 FIFO 顺序发送给主机的所有数据。在主机请求接收前，这些数据一直存储在发送缓存区。函数 i2c_slave_write_buffer() 有一个参数，用于指定发送缓存区已满时的块时间。这将允许从机应用程序在指定的超时设定内等待发送缓存区中足够的可用空间。

在 peripherals/i2c 中可找到介绍如何使用这些功能的代码示例。

中断处理

安装驱动程序时，默认情况下会安装中断处理程序。但是，您可以通过调用函数 i2c_isr_register() 来注册自己的而不是默认的中断处理程序。在运行自己的中断处理程序时，可以参考 ESP32 的技术参考手册（PDF），以获取有关 I2C 控制器触发的中断描述。

调用函数 i2c_isr_free() 删除中断处理程序。

用户自定义配置

如本节末尾所述 配置驱动程序, 函数 i2c_param_config() 在初始化 I2C 端口的驱动程序配置时，也会将几个 I2C 通信参数设置为 I2C 总线协议规范 规定的默认值。 其他一些相关参数已在 I2C 控制器的寄存器中预先配置。

通过调用下表中提供的专用函数，可以将所有这些参数更改为用户自定义值。请注意，时序值是在 APB 时钟周期中定义。APB 的频率在 I2C_APB_CLK_FREQ 中指定。

其他可配置的 I2C 通信参数

要更改的参数	函数
SCL 脉冲周期的高电平和低电平	i2c_set_period()
在产生 启动 信号期间使用的 SCL 和 SDA 信号时序	i2c_set_start_timing()
在产生 停止 信号期间使用的 SCL 和 SDA 信号时序	i2c_set_stop_timing()
从机采样以及主机切换时，SCL 和 SDA 信号之间的时序关系	i2c_set_data_timing()
I2C 超时	i2c_set_timeout()
优先发送/接收最高有效位 (LSB) 或最低有效位 (MSB），可在 i2c_trans_mode_t 定义的模式中选择	i2c_set_data_mode()

上述每个函数都有一个 _get_ 对应项来检查当前设置的值。例如，调用 i2c_get_timeout() 来检查 I2C 超时值。

要检查在驱动程序配置过程中设置的参数默认值，请参考文件 driver/i2c.c 并查找带有后缀 _DEFAULT 的定义。

通过函数 i2c_set_pin() 可以为 SDA 和 SCL 信号选择不同的管脚并改变上拉配置。如果要修改已经输入的值，请使用函数 i2c_param_config()。

注解

ESP32 的内部上拉电阻范围为几万欧姆，因此在大多数情况下，它们本身不足以用作 I2C 上拉电阻。建议用户使用阻值在 I2C 总线协议规范 规定范围内的上拉电阻。

错误处理

大多数 I2C 驱动程序的函数在成功完成时会返回 ESP_OK ，或在失败时会返回特定的错误代码。实时检查返回的值并进行错误处理是一种好习惯。驱动程序也会打印日志消息，其中包含错误说明，例如检查输入配置的正确性。有关详细信息，请参考文件 driver/i2c.c 并用后缀 _ERR_STR 查找定义。

使用专用中断来捕获通信故障。例如，如果从机将数据发送回主机耗费太长时间，会触发 I2C_TIME_OUT_INT 中断。详细信息请参考 中断处理。

如果出现通信失败，可以分别为发送和接收缓存区调用 i2c_reset_tx_fifo() 和 i2c_reset_rx_fifo() 来重置内部硬件缓存区。

删除驱动程序

如果使用 i2c_driver_install() 建立 I2C 通信，一段时间后不再需要 I2C 通信，则可以通过调用 i2c_driver_delete() 来移除驱动程序以释放分配的资源。

应用示例

I2C 主机和从机示例：peripherals/i2c

API 参考

Header File

• driver/include/driver/i2c.h

Functions

esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode, size_t slv_rx_buf_len, size_t slv_tx_buf_len, int intr_alloc_flags)

I2C driver install.

Note

Only slave mode will use this value, driver will ignore this value in master mode.

Note

Only slave mode will use this value, driver will ignore this value in master mode.

Note

In master mode, if the cache is likely to be disabled(such as write flash) and the slave is time-sensitive, ESP_INTR_FLAG_IRAM is suggested to be used. In this case, please use the memory allocated from internal RAM in i2c read and write function, because we can not access the psram(if psram is enabled) in interrupt handle function when cache is disabled.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

• ESP_FAIL Driver install error

Parameters

• i2c_num: I2C port number

• mode: I2C mode( master or slave )

• slv_rx_buf_len: receiving buffer size for slave mode

Parameters

• slv_tx_buf_len: sending buffer size for slave mode

Parameters

• intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

esp_err_t i2c_driver_delete(i2c_port_t i2c_num)

I2C driver delete.

Note

This function does not guarantee thread safety. Please make sure that no thread will continuously hold semaphores before calling the delete function.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

esp_err_t i2c_param_config(i2c_port_t i2c_num, const i2c_config_t *i2c_conf)

I2C parameter initialization.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• i2c_conf: pointer to I2C parameter settings

esp_err_t i2c_reset_tx_fifo(i2c_port_t i2c_num)

reset I2C tx hardware fifo

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

esp_err_t i2c_reset_rx_fifo(i2c_port_t i2c_num)

reset I2C rx fifo

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

esp_err_t i2c_isr_register(i2c_port_t i2c_num, void (*fn)(void *), void *arg, int intr_alloc_flags, intr_handle_t *handle, )

I2C isr handler register.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• fn: isr handler function

• arg: parameter for isr handler function

• intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

• handle: handle return from esp_intr_alloc.

esp_err_t i2c_isr_free(intr_handle_t handle)

to delete and free I2C isr.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• handle: handle of isr.

esp_err_t i2c_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num, bool sda_pullup_en, bool scl_pullup_en, i2c_mode_t mode)

Configure GPIO signal for I2C sck and sda.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• sda_io_num: GPIO number for I2C sda signal

• scl_io_num: GPIO number for I2C scl signal

• sda_pullup_en: Whether to enable the internal pullup for sda pin

• scl_pullup_en: Whether to enable the internal pullup for scl pin

• mode: I2C mode

i2c_cmd_handle_t i2c_cmd_link_create(void)

Create and init I2C command link.

Note

Before we build I2C command link, we need to call i2c_cmd_link_create() to create a command link. After we finish sending the commands, we need to call i2c_cmd_link_delete() to release and return the resources.

Return

i2c command link handler

void i2c_cmd_link_delete(i2c_cmd_handle_t cmd_handle)

Free I2C command link.

Note

Before we build I2C command link, we need to call i2c_cmd_link_create() to create a command link. After we finish sending the commands, we need to call i2c_cmd_link_delete() to release and return the resources.

Parameters

• cmd_handle: I2C command handle

esp_err_t i2c_master_start(i2c_cmd_handle_t cmd_handle)

Queue command for I2C master to generate a start signal.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

esp_err_t i2c_master_write_byte(i2c_cmd_handle_t cmd_handle, uint8_t data, bool ack_en)

Queue command for I2C master to write one byte to I2C bus.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

• data: I2C one byte command to write to bus

• ack_en: enable ack check for master

esp_err_t i2c_master_write(i2c_cmd_handle_t cmd_handle, const uint8_t *data, size_t data_len, bool ack_en)

Queue command for I2C master to write buffer to I2C bus.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Note

If the psram is enabled and intr_flag is ESP_INTR_FLAG_IRAM, please use the memory allocated from internal RAM.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

• data: data to send

Parameters

• data_len: data length

• ack_en: enable ack check for master

esp_err_t i2c_master_read_byte(i2c_cmd_handle_t cmd_handle, uint8_t *data, i2c_ack_type_t ack)

Queue command for I2C master to read one byte from I2C bus.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Note

If the psram is enabled and intr_flag is ESP_INTR_FLAG_IRAM, please use the memory allocated from internal RAM.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

• data: pointer accept the data byte

Parameters

• ack: ack value for read command

esp_err_t i2c_master_read(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, i2c_ack_type_t ack)

Queue command for I2C master to read data from I2C bus.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Note

If the psram is enabled and intr_flag is ESP_INTR_FLAG_IRAM, please use the memory allocated from internal RAM.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

• data: data buffer to accept the data from bus

Parameters

• data_len: read data length

• ack: ack value for read command

esp_err_t i2c_master_stop(i2c_cmd_handle_t cmd_handle)

Queue command for I2C master to generate a stop signal.

Note

Only call this function in I2C master mode Call i2c_master_cmd_begin() to send all queued commands

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• cmd_handle: I2C cmd link

esp_err_t i2c_master_cmd_begin(i2c_port_t i2c_num, i2c_cmd_handle_t cmd_handle, TickType_t ticks_to_wait)

I2C master send queued commands. This function will trigger sending all queued commands. The task will be blocked until all the commands have been sent out. The I2C APIs are not thread-safe, if you want to use one I2C port in different tasks, you need to take care of the multi-thread issue.

Note

Only call this function in I2C master mode

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

• ESP_FAIL Sending command error, slave doesn’t ACK the transfer.

• ESP_ERR_INVALID_STATE I2C driver not installed or not in master mode.

• ESP_ERR_TIMEOUT Operation timeout because the bus is busy.

Parameters

• i2c_num: I2C port number

• cmd_handle: I2C command handler

• ticks_to_wait: maximum wait ticks.

int i2c_slave_write_buffer(i2c_port_t i2c_num, const uint8_t *data, int size, TickType_t ticks_to_wait)

I2C slave write data to internal ringbuffer, when tx fifo empty, isr will fill the hardware fifo from the internal ringbuffer.

Note

Only call this function in I2C slave mode

Return

• ESP_FAIL(-1) Parameter error

• Others(>=0) The number of data bytes that pushed to the I2C slave buffer.

Parameters

• i2c_num: I2C port number

• data: data pointer to write into internal buffer

• size: data size

• ticks_to_wait: Maximum waiting ticks

int i2c_slave_read_buffer(i2c_port_t i2c_num, uint8_t *data, size_t max_size, TickType_t ticks_to_wait)

I2C slave read data from internal buffer. When I2C slave receive data, isr will copy received data from hardware rx fifo to internal ringbuffer. Then users can read from internal ringbuffer.

Note

Only call this function in I2C slave mode

Return

• ESP_FAIL(-1) Parameter error

• Others(>=0) The number of data bytes that read from I2C slave buffer.

Parameters

• i2c_num: I2C port number

• data: data pointer to accept data from internal buffer

• max_size: Maximum data size to read

• ticks_to_wait: Maximum waiting ticks

esp_err_t i2c_set_period(i2c_port_t i2c_num, int high_period, int low_period)

set I2C master clock period

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• high_period: clock cycle number during SCL is high level, high_period is a 14 bit value

• low_period: clock cycle number during SCL is low level, low_period is a 14 bit value

esp_err_t i2c_get_period(i2c_port_t i2c_num, int *high_period, int *low_period)

get I2C master clock period

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• high_period: pointer to get clock cycle number during SCL is high level, will get a 14 bit value

• low_period: pointer to get clock cycle number during SCL is low level, will get a 14 bit value

esp_err_t i2c_filter_enable(i2c_port_t i2c_num, uint8_t cyc_num)

enable hardware filter on I2C bus Sometimes the I2C bus is disturbed by high frequency noise(about 20ns), or the rising edge of the SCL clock is very slow, these may cause the master state machine broken. enable hardware filter can filter out high frequency interference and make the master more stable.

Note

Enable filter will slow the SCL clock.

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• cyc_num: the APB cycles need to be filtered(0<= cyc_num <=7). When the period of a pulse is less than cyc_num * APB_cycle, the I2C controller will ignore this pulse.

esp_err_t i2c_filter_disable(i2c_port_t i2c_num)

disable filter on I2C bus

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

esp_err_t i2c_set_start_timing(i2c_port_t i2c_num, int setup_time, int hold_time)

set I2C master start signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• setup_time: clock number between the falling-edge of SDA and rising-edge of SCL for start mark, it’s a 10-bit value.

• hold_time: clock num between the falling-edge of SDA and falling-edge of SCL for start mark, it’s a 10-bit value.

esp_err_t i2c_get_start_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time)

get I2C master start signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• setup_time: pointer to get setup time

• hold_time: pointer to get hold time

esp_err_t i2c_set_stop_timing(i2c_port_t i2c_num, int setup_time, int hold_time)

set I2C master stop signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• setup_time: clock num between the rising-edge of SCL and the rising-edge of SDA, it’s a 10-bit value.

• hold_time: clock number after the STOP bit’s rising-edge, it’s a 14-bit value.

esp_err_t i2c_get_stop_timing(i2c_port_t i2c_num, int *setup_time, int *hold_time)

get I2C master stop signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• setup_time: pointer to get setup time.

• hold_time: pointer to get hold time.

esp_err_t i2c_set_data_timing(i2c_port_t i2c_num, int sample_time, int hold_time)

set I2C data signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• sample_time: clock number I2C used to sample data on SDA after the rising-edge of SCL, it’s a 10-bit value

• hold_time: clock number I2C used to hold the data after the falling-edge of SCL, it’s a 10-bit value

esp_err_t i2c_get_data_timing(i2c_port_t i2c_num, int *sample_time, int *hold_time)

get I2C data signal timing

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• sample_time: pointer to get sample time

• hold_time: pointer to get hold time

esp_err_t i2c_set_timeout(i2c_port_t i2c_num, int timeout)

set I2C timeout value

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• timeout: timeout value for I2C bus (unit: APB 80Mhz clock cycle)

esp_err_t i2c_get_timeout(i2c_port_t i2c_num, int *timeout)

get I2C timeout value

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• timeout: pointer to get timeout value

esp_err_t i2c_set_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t tx_trans_mode, i2c_trans_mode_t rx_trans_mode)

set I2C data transfer mode

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• tx_trans_mode: I2C sending data mode

• rx_trans_mode: I2C receving data mode

esp_err_t i2c_get_data_mode(i2c_port_t i2c_num, i2c_trans_mode_t *tx_trans_mode, i2c_trans_mode_t *rx_trans_mode)

get I2C data transfer mode

Return

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Parameters

• i2c_num: I2C port number

• tx_trans_mode: pointer to get I2C sending data mode

• rx_trans_mode: pointer to get I2C receiving data mode

Macros

I2C_APB_CLK_FREQ

I2C source clock is APB clock, 80MHz

I2C_NUM_0

I2C port 0

I2C_NUM_1

I2C port 1

I2C_NUM_MAX

I2C port max

Type Definitions

typedef void *i2c_cmd_handle_t

I2C command handle

Header File

• hal/include/hal/i2c_types.h

Structures

struct i2c_config_t

I2C initialization parameters.

Public Members

i2c_mode_t mode

I2C mode

int sda_io_num

GPIO number for I2C sda signal

int scl_io_num

GPIO number for I2C scl signal

bool sda_pullup_en

Internal GPIO pull mode for I2C sda signal

bool scl_pullup_en

Internal GPIO pull mode for I2C scl signal

uint32_t clk_speed

I2C clock frequency for master mode, (no higher than 1MHz for now)

struct i2c_config_t::[anonymous]::[anonymous] master

I2C master config

uint8_t addr_10bit_en

I2C 10bit address mode enable for slave mode

uint16_t slave_addr

I2C address for slave mode

struct i2c_config_t::[anonymous]::[anonymous] slave

I2C slave config

uint32_t clk_flags

Bitwise of I2C_SCLK_SRC_FLAG_**FOR_DFS** for clk source choice

Macros

I2C_SCLK_SRC_FLAG_FOR_NOMAL

Any one clock source that is available for the specified frequency may be choosen

I2C_SCLK_SRC_FLAG_AWARE_DFS

For REF tick clock, it won’t change with APB.

I2C_SCLK_SRC_FLAG_LIGHT_SLEEP

For light sleep mode.

I2C_CLK_FREQ_MAX

Use the highest speed that is available for the clock source picked by clk_flags.

Type Definitions

typedef int i2c_port_t

I2C port number, can be I2C_NUM_0 ~ (I2C_NUM_MAX-1).

Enumerations

enum i2c_mode_t

Values:

I2C_MODE_SLAVE = 0

I2C slave mode

I2C_MODE_MASTER

I2C master mode

I2C_MODE_MAX

enum i2c_rw_t

Values:

I2C_MASTER_WRITE = 0

I2C write data

I2C_MASTER_READ

I2C read data

enum i2c_trans_mode_t

Values:

I2C_DATA_MODE_MSB_FIRST = 0

I2C data msb first

I2C_DATA_MODE_LSB_FIRST = 1

I2C data lsb first

I2C_DATA_MODE_MAX

enum i2c_addr_mode_t

Values:

I2C_ADDR_BIT_7 = 0

I2C 7bit address for slave mode

I2C_ADDR_BIT_10

I2C 10bit address for slave mode

I2C_ADDR_BIT_MAX

enum i2c_ack_type_t

Values:

I2C_MASTER_ACK = 0x0

I2C ack for each byte read

I2C_MASTER_NACK = 0x1

I2C nack for each byte read

I2C_MASTER_LAST_NACK = 0x2

I2C nack for the last byte

I2C_MASTER_ACK_MAX

enum i2c_sclk_t

I2C clock source, sorting from smallest to largest, place them in order. This can be expanded in the future use.

Values:

I2C_SCLK_DEFAULT = 0

I2C source clock not selected

I2C_SCLK_APB

I2C source clock from APB, 80M

I2C_SCLK_MAX

enum i2c_opmode_t

Values:

I2C_CMD_RESTART = 0

I2C restart command

I2C_CMD_WRITE

I2C write command

I2C_CMD_READ

I2C read command

I2C_CMD_STOP

I2C stop command

I2C_CMD_END

I2C end command

提供有关此文档的反馈