I2C

API Reference

Functions

esp_err_t i2c_driver_install(i2c_port_t i2c_num, i2c_mode_t mode)

I2C driver install.

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 )

esp_err_t i2c_driver_delete(i2c_port_t i2c_num)

I2C driver delete.

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.

Note
It must be used after calling i2c_driver_install
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_set_pin(i2c_port_t i2c_num, int sda_io_num, int scl_io_num, gpio_pullup_t sda_pullup_en, gpio_pullup_t 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()

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, 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
Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • cmd_handle: I2C cmd link
  • data: data to send
  • 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
Return
  • ESP_OK Success
  • ESP_ERR_INVALID_ARG Parameter error
Parameters
  • cmd_handle: I2C cmd link
  • data: pointer accept the data byte
  • 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
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
  • 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.

Structures

struct i2c_config_t

I2C initialization parameters.

Public Members

i2c_mode_t mode

I2C mode

gpio_num_t sda_io_num

GPIO number for I2C sda signal

gpio_pullup_t sda_pullup_en

Internal GPIO pull mode for I2C sda signal

gpio_num_t scl_io_num

GPIO number for I2C scl signal

gpio_pullup_t scl_pullup_en

Internal GPIO pull mode for I2C scl signal

uint32_t clk_stretch_tick

Clock Stretch time, depending on CPU frequency

Type Definitions

typedef void *i2c_cmd_handle_t

I2C command handle

Enumerations

enum i2c_mode_t

Values:

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_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

enum i2c_port_t

Values:

I2C_NUM_0 = 0

I2C port 0

I2C_NUM_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