i2c_bus

[English]

i2c_bus 的使用方法：

  1. 创建总线：使用 i2c_bus_create() 创建一个总线实例。创建时需要指定 I2C 端口号，以及总线配置项 i2c_config_t。配置项包括 SDA 和 SCL 引脚号、上下拉模式，因为这些配置项在系统设计时已经确定，一般不在运行时切换。总线配置项还包括总线默认的时钟频率，在设备不指定频率时使用。

  2. 创建设备：使用 i2c_bus_device_create() 在已创建的总线实例之上创建设备，创建时需要指定总线句柄、设备的 I2C 地址、设备运行的时钟频率，I2C 传输时将根据设备的配置项动态切换频率。设备时钟速率可配置为 0，表示默认使用当前的总线频率。

  3. 数据读取：使用 i2c_bus_read_byte()、i2c_bus_read_bytes() 可直接进行 Byte 的读取操作；使用 i2c_bus_read_bit()、i2c_bus_read_bits() 可直接进行 bit 的读取操作。只需要传入设备句柄、设备寄存器地址、用于存放读取数据的 buf 和读取长度的等。寄存器地址可设为 NULL_I2C_MEM_ADDR，用于操作没有内部寄存器的设备。

  4. 数据写入：使用 i2c_bus_write_byte()、i2c_bus_write_bytes() 可直接进行 Byte 的写入操作；使用 i2c_bus_write_bit()、i2c_bus_write_bits() 可直接进行 bit 的写入操作。只需要传入设备句柄、设备寄存器地址、将要写入的数据位置和写入长度等。寄存器地址可设为 NULL_I2C_MEM_ADDR，用于操作没有内部寄存器的设备。

  5. 删除设备和总线：如果所有的 i2c_bus 通信已经完成，可以通过删除设备和总线实例释放系统资源。可使用 i2c_bus_device_delete() 分别将已创建的设备删除，然后使用 i2c_bus_delete() 将总线资源删除。如果在设备未删除时删除总线，操作将不会被执行。

示例：

i2c_config_t conf = {
    .mode = I2C_MODE_MASTER,
    .sda_io_num = I2C_MASTER_SDA_IO,
    .sda_pullup_en = GPIO_PULLUP_ENABLE,
    .scl_io_num = I2C_MASTER_SCL_IO,
    .scl_pullup_en = GPIO_PULLUP_ENABLE,
    .master.clk_speed = 100000,
}; // i2c_bus configurations

uint8_t data_rd[2] = {0};
uint8_t data_wr[2] = {0x01, 0x21};

i2c_bus_handle_t i2c0_bus = i2c_bus_create(I2C_NUM_0, &conf); // create i2c_bus
i2c_bus_device_handle_t i2c_device1 = i2c_bus_device_create(i2c0_bus, 0x28, 400000); // create device1, address: 0x28 , clk_speed: 400000
i2c_bus_device_handle_t i2c_device2 = i2c_bus_device_create(i2c0_bus, 0x32, 0); // create device2, address: 0x32 , clk_speed: no-specified

i2c_bus_read_bytes(i2c_device1, NULL_I2C_MEM_ADDR, 2, data_rd); // read bytes from device1 with no register address
i2c_bus_write_bytes(i2c_device2, 0x10, 2, data_wr); // write bytes to device2 register 0x10

i2c_bus_device_delete(&i2c_device1); //delete device1
i2c_bus_device_delete(&i2c_device2); //delete device2
i2c_bus_delete(&i2c0_bus);  //delete i2c_bus

备注

对于某些特殊应用场景，例如:

  1. 当寄存器地址为 16 位时，可以使用 i2c_bus_read_reg16() 或 i2c_bus_write_reg16() 进行读写操作；

  2. 对于需要跳过地址阶段或者需要增加命令阶段的设备，可以使用 i2c_bus_cmd_begin() 结合 I2C command link 进行操作。

已适配 IDF 版本

  • ESP-IDF v4.0 及以上版本。

API 参考

Header File

Functions

i2c_bus_handle_t i2c_bus_create(i2c_port_t port, const i2c_config_t *conf)

Create an I2C bus instance then return a handle if created successfully. Each I2C bus works in a singleton mode, which means for an i2c port only one group parameter works. When i2c_bus_create is called more than one time for the same i2c port, following parameter will override the previous one.

参数

  • port – I2C port number

  • conf – Pointer to I2C bus configuration

返回

i2c_bus_handle_t Return the I2C bus handle if created successfully, return NULL if failed.

esp_err_t i2c_bus_delete(i2c_bus_handle_t *p_bus_handle)

Delete and release the I2C bus resource.

参数

p_bus_handle – Point to the I2C bus handle, if delete succeed handle will set to NULL.

返回

  • ESP_OK Success

  • ESP_FAIL Fail

uint8_t i2c_bus_scan(i2c_bus_handle_t bus_handle, uint8_t *buf, uint8_t num)

Scan i2c devices attached on i2c bus.

参数

  • bus_handle – I2C bus handle

  • buf – Pointer to a buffer to save devices’ address, if NULL no address will be saved.

  • num – Maximum number of addresses to save, invalid if buf set to NULL, higher addresses will be discarded if num less-than the total number found on the I2C bus.

返回

uint8_t Total number of devices found on the I2C bus

uint32_t i2c_bus_get_current_clk_speed(i2c_bus_handle_t bus_handle)

Get current active clock speed.

参数

bus_handle – I2C bus handle

返回

uint32_t current clock speed

uint8_t i2c_bus_get_created_device_num(i2c_bus_handle_t bus_handle)

Get created device number of the bus.

参数

bus_handle – I2C bus handle

返回

uint8_t created device number of the bus

i2c_bus_device_handle_t i2c_bus_device_create(i2c_bus_handle_t bus_handle, uint8_t dev_addr, uint32_t clk_speed)

Create an I2C device on specific bus. Dynamic configuration must be enable to achieve multiple devices with different configs on a single bus. menuconfig:Bus Options->I2C Bus Options->enable dynamic configuration.

参数

  • bus_handle – Point to the I2C bus handle

  • dev_addr – i2c device address

  • clk_speed – device specified clock frequency the i2c_bus will switch to during each transfer. 0 if use current bus speed.

返回

i2c_bus_device_handle_t return a device handle if created successfully, return NULL if failed.

esp_err_t i2c_bus_device_delete(i2c_bus_device_handle_t *p_dev_handle)

Delete and release the I2C device resource, i2c_bus_device_delete should be used in pairs with i2c_bus_device_create.

参数

p_dev_handle – Point to the I2C device handle, if delete succeed handle will set to NULL.

返回

  • ESP_OK Success

  • ESP_FAIL Fail

uint8_t i2c_bus_device_get_address(i2c_bus_device_handle_t dev_handle)

Get device’s I2C address.

参数

dev_handle – I2C device handle

返回

uint8_t I2C address, return NULL_I2C_DEV_ADDR if dev_handle is invalid.

esp_err_t i2c_bus_read_byte(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t *data)

Read single byte from i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to read from, set to NULL_I2C_MEM_ADDR if no internal address.

  • data – Pointer to a buffer to save the data that was read

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_read_bytes(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, size_t data_len, uint8_t *data)

Read multiple bytes from i2c device with 8-bit internal register/memory address. If internal reg/mem address is 16-bit, please refer i2c_bus_read_reg16.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to read from, set to NULL_I2C_MEM_ADDR if no internal address.

  • data_len – Number of bytes to read

  • data – Pointer to a buffer to save the data that was read

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_read_bit(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t bit_num, uint8_t *data)

Read single bit of a byte from i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to read from, set to NULL_I2C_MEM_ADDR if no internal address.

  • bit_num – The bit number 0 - 7 to read

  • data – Pointer to a buffer to save the data that was read. *data == 0 -> bit = 0, *data !=0 -> bit = 1.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_read_bits(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t bit_start, uint8_t length, uint8_t *data)

Read multiple bits of a byte from i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to read from, set to NULL_I2C_MEM_ADDR if no internal address.

  • bit_start – The bit to start from, 0 - 7, MSB at 0

  • length – The number of bits to read, 1 - 8

  • data – Pointer to a buffer to save the data that was read

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_write_byte(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t data)

Write single byte to i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to write to, set to NULL_I2C_MEM_ADDR if no internal address.

  • data – The byte to write.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_write_bytes(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, size_t data_len, const uint8_t *data)

Write multiple byte to i2c device with 8-bit internal register/memory address If internal reg/mem address is 16-bit, please refer i2c_bus_write_reg16.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to write to, set to NULL_I2C_MEM_ADDR if no internal address.

  • data_len – Number of bytes to write

  • data – Pointer to the bytes to write.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_write_bit(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t bit_num, uint8_t data)

Write single bit of a byte to an i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to write to, set to NULL_I2C_MEM_ADDR if no internal address.

  • bit_num – The bit number 0 - 7 to write

  • data – The bit to write, data == 0 means set bit = 0, data !=0 means set bit = 1.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_write_bits(i2c_bus_device_handle_t dev_handle, uint8_t mem_address, uint8_t bit_start, uint8_t length, uint8_t data)

Write multiple bits of a byte to an i2c device with 8-bit internal register/memory address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal reg/mem address to write to, set to NULL_I2C_MEM_ADDR if no internal address.

  • bit_start – The bit to start from, 0 - 7, MSB at 0

  • length – The number of bits to write, 1 - 8

  • data – The bits to write.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_cmd_begin(i2c_bus_device_handle_t dev_handle, i2c_cmd_handle_t cmd)

I2C master send queued commands create by i2c_cmd_link_create . This function will trigger sending all queued commands. The task will be blocked until all the commands have been sent out. If I2C_BUS_DYNAMIC_CONFIG enable, i2c_bus will dynamically check configs and re-install i2c driver before each transfer, hence multiple devices with different configs on a single bus can be supported.

备注

Only call this function when i2c_bus_read/write_xx do not meet the requirements

参数

  • dev_handle – I2C device handle

  • cmd – I2C command handler

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_write_reg16(i2c_bus_device_handle_t dev_handle, uint16_t mem_address, size_t data_len, const uint8_t *data)

Write date to an i2c device with 16-bit internal reg/mem address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal 16-bit reg/mem address to write to, set to NULL_I2C_MEM_ADDR if no internal address.

  • data_len – Number of bytes to write

  • data – Pointer to the bytes to write.

返回

esp_err_t

  • 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.

esp_err_t i2c_bus_read_reg16(i2c_bus_device_handle_t dev_handle, uint16_t mem_address, size_t data_len, uint8_t *data)

Read date from i2c device with 16-bit internal reg/mem address.

参数

  • dev_handle – I2C device handle

  • mem_address – The internal 16-bit reg/mem address to read from, set to NULL_I2C_MEM_ADDR if no internal address.

  • data_len – Number of bytes to read

  • data – Pointer to a buffer to save the data that was read

返回

esp_err_t

  • 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.

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] master

I2C master config

uint32_t clk_flags

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

Macros

NULL_I2C_MEM_ADDR

set mem_address to NULL_I2C_MEM_ADDR if i2c device has no internal address during read/write

NULL_I2C_MEM_16BIT_ADDR

set 16bit mem_address to NULL_I2C_MEM_16BIT_ADDR if i2c device has no internal address during read/write

NULL_I2C_DEV_ADDR

invalid i2c device address

gpio_pad_select_gpio
portTICK_RATE_MS

Type Definitions

typedef void *i2c_bus_handle_t

i2c bus handle

typedef void *i2c_bus_device_handle_t

i2c device handle

typedef void *i2c_cmd_handle_t

I2C command handle

提供有关此文档的反馈