I2C¶
Overview¶
ESP32 has two I2C controllers which can be set as master mode or slave mode.
Application Example¶
I2C master and slave example: peripherals/i2c.
API Reference¶
Header File¶
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.
- Return
- ESP_OK Success
- ESP_ERR_INVALID_ARG Parameter error
- ESP_FAIL Driver install error
- Parameters
i2c_num
: I2C port numbermode
: 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.
- 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 numberi2c_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 numberfn
: isr handler functionarg
: parameter for isr handler functionintr_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, gpio_num_t sda_io_num, gpio_num_t 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 numbersda_io_num
: GPIO number for I2C sda signalscl_io_num
: GPIO number for I2C scl signalsda_pullup_en
: Whether to enable the internal pullup for sda pinscl_pullup_en
: Whether to enable the internal pullup for scl pinmode
: 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 linkdata
: I2C one byte command to write to busack_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 linkdata
: data to senddata_len
: data lengthack_en
: enable ack check for master
-
esp_err_t
i2c_master_read_byte
(i2c_cmd_handle_t cmd_handle, uint8_t *data, int 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 linkdata
: pointer accept the data byteack
: ack value for read command
-
esp_err_t
i2c_master_read
(i2c_cmd_handle_t cmd_handle, uint8_t *data, size_t data_len, int 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 linkdata
: data buffer to accept the data from busdata_len
: read data lengthack
: 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, portBASE_TYPE 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 numbercmd_handle
: I2C command handlerticks_to_wait
: maximum wait ticks.
-
int
i2c_slave_write_buffer
(i2c_port_t i2c_num, uint8_t *data, int size, portBASE_TYPE 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 numberdata
: data pointer to write into internal buffersize
: data sizeticks_to_wait
: Maximum waiting ticks
-
int
i2c_slave_read_buffer
(i2c_port_t i2c_num, uint8_t *data, size_t max_size, portBASE_TYPE 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 numberdata
: data pointer to write into internal buffermax_size
: Maximum data size to readticks_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 numberhigh_period
: clock cycle number during SCL is high level, high_period is a 14 bit valuelow_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 numberhigh_period
: pointer to get clock cycle number during SCL is high level, will get a 14 bit valuelow_period
: pointer to get clock cycle number during SCL is low level, will get a 14 bit value
-
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 numbersetup_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 numbersetup_time
: pointer to get setup timehold_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 numbersetup_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 numbersetup_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 numbersample_time
: clock number I2C used to sample data on SDA after the rising-edge of SCL, it’s a 10-bit valuehold_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 numbersample_time
: pointer to get sample timehold_time
: pointer to get hold time
-
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 numbertx_trans_mode
: I2C sending data moderx_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 numbertx_trans_mode
: pointer to get I2C sending data moderx_trans_mode
: pointer to get I2C receiving data mode
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_speed
¶ I2C clock frequency for master mode, (no higher than 1MHz for now)
-
uint8_t
addr_10bit_en
¶ I2C 10bit address mode enable for slave mode
-
uint16_t
slave_addr
¶ I2C address for slave mode
-
i2c_mode_t
Macros¶
-
I2C_APB_CLK_FREQ
¶ I2C source clock is APB clock, 80MHz
-
I2C_FIFO_LEN
¶ I2C hardware fifo length
Enumerations¶
-
enum
i2c_mode_t
¶ Values:
-
I2C_MODE_SLAVE
= 0¶ I2C slave mode
-
I2C_MODE_MASTER
¶ I2C master mode
-
I2C_MODE_MAX
¶
-
-
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
¶
-