I2C Driver

Overview

I2C is a serial, synchronous, half-duplex communication protocol that allows co-existence of multiple masters and slaves on the same bus. The I2C bus consists of two lines: serial data line (SDA) and serial clock (SCL). Both lines require pull-up resistors.

With such advantages as simplicity and low manufacturing cost, I2C is mostly used for communication of low-speed peripheral devices over short distances (within one foot).

ESP32 has two I2C controllers (also referred to as ports) which are responsible for handling communications on two I2C buses. Each I2C controller can operate as master or slave. As an example, one controller can act as a master and the other as a slave at the same time.

Driver Features

I2C driver governs communications of devices over the I2C bus. The driver supports the following features:

  • Reading and writing bytes in Master mode
  • Slave mode
  • Reading and writing to registers which are in turn read/written by the master

Driver Usage

The following sections describe typical steps of configuring and operating the I2C driver:

  1. Configuration - set the initialization parameters (master or slave mode, GPIO pins for SDA and SCL, clock speed, etc.)
  2. Install Driver- activate the driver on one of the two I2C controllers as a master or slave
  3. Depending on whether you configure the driver for a master or slave, choose the appropriate item
    1. Communication as Master - handle communications (master)
    2. Communication as Slave - respond to messages from the master (slave)
  4. Interrupt Handling - configure and service I2C interrupts
  5. Customized Configuration - adjust default I2C communication parameters (timings, bit order, etc.)
  6. Error Handling - how to recognize and handle driver configuration and communication errors
  7. Delete Driver- release resources used by the I2C driver when communication ends

Configuration

To establish I2C communication, start by configuring the driver. This is done by setting the parameters of the structure i2c_config_t:

  • Set I2C mode of operation - slave or master from i2c_mode_t

  • Configure communication pins

    • Assign GPIO pins for SDA and SCL signals
    • Set whether to enable ESP32’s internal pull-ups

  • (Master only) Set I2C clock speed

  • (Slave only) Configure the following

    • Whether to enable 10 bit address mode
    • Define slave address

After that, initialize the configuration for a given I2C port. For this, call the function i2c_param_config() and pass to it the port number and the structure i2c_config_t.

At this stage, i2c_param_config() also sets a few other I2C configuration parameters to default values that are defined by the I2C specification. For more details on the values and how to modify them, see Customized Configuration.

Install Driver

After the I2C driver is configured, install it by calling the function i2c_driver_install() with the following parameters:

  • Port number, one of the two port numbers from i2c_port_t
  • Master or slave, selected from i2c_mode_t
  • (Slave only) Size of buffers to allocate for sending and receiving data. As I2C is a master-centric bus, data can only go from the slave to the master at the master’s request. Therefore, the slave will usually have a send buffer where the slave application writes data. The data remains in the send buffer to be read by the master at the master’s own discretion.
  • Flags for allocating the interrupt (see ESP_INTR_FLAG_* values in esp32/include/esp_intr_alloc.h)

Communication as Master

After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.

ESP32’s I2C controller operating as master is responsible for establishing communication with I2C slave devices and sending commands to trigger a slave to action, for example, to take a measurement and send the readings back to the master.

For better process organization, the driver provides a container, called a “command link”, that should be populated with a sequence of commands and then passed to the I2C controller for execution.

Master Write

The example below shows how to build a command link for an I2C master to send n bytes to a slave.

I2C command link - master write example

The following describes how a command link for a “master write” is set up and what comes inside:

  1. Create a command link with i2c_cmd_link_create().

    Then, populate it with the series of data to be sent to the slave:

    1. Start bit - i2c_master_start()
    2. Slave address - i2c_master_write_byte(). The single byte address is provided as an argument of this function call.
    3. Data - One or more bytes as an argument of i2c_master_write()
    4. Stop bit - i2c_master_stop()

    Both functions i2c_master_write_byte() and i2c_master_write() have an additional argument specifying whether the master should ensure that it has received the ACK bit.

  2. Trigger the execution of the command link by I2C controller by calling i2c_master_cmd_begin(). Once the execution is triggered, the command link cannot be modified.

  3. After the commands are transmitted, release the resources used by the command link by calling i2c_cmd_link_delete().

Master Read

The example below shows how to build a command link for an I2C master to read n bytes from a slave.

I2C command link - master read example

Compared to writing data, the command link is populated in Step 4 not with i2c_master_write... functions but with i2c_master_read_byte() and / or i2c_master_read(). Also, the last read in Step 5 is configured so that the master does not provide the ACK bit.

Indicating Write or Read

After sending a slave address (see Step 3 on both diagrams above), the master either writes or reads from the slave.

The information on what the master will actually do is hidden in the least significant bit of the slave’s address.

For this reason, the command link sent by the master to write data to the slave contains the address (ESP_SLAVE_ADDR << 1) | I2C_MASTER_WRITE and looks as follows:

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

Likewise, the command link to read from the slave looks as follows:

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

Communication as Slave

After installing the I2C driver, ESP32 is ready to communicate with other I2C devices.

The API provides the following functions for slaves

  • i2c_slave_read_buffer()

    Whenever the master writes data to the slave, the slave will automatically store it in the receive buffer. This allows the slave application to call the function i2c_slave_read_buffer() at its own discretion. This function also has a parameter to specify block time if no data is in the receive buffer. This will allow the slave application to wait with a specified timeout for data to arrive to the buffer.

  • i2c_slave_write_buffer()

    The send buffer is used to store all the data that the slave wants to send to the master in FIFO order. The data stays there until the master requests for it. The function i2c_slave_write_buffer() has a parameter to specify block time if the send buffer is full. This will allow the slave application to wait with a specified timeout for the adequate amount of space to become available in the send buffer.

A code example showing how to use these functions can be found in peripherals/i2c.

Interrupt Handling

During driver installation, an interrupt handler is installed by default. However, you can register your own interrupt handler instead of the default one by calling the function i2c_isr_register(). When implementing your own interrupt handler, refer to the ESP32 Technical Reference Manual for the description of interrupts triggered by the I2C controller.

To delete an interrupt handler, call i2c_isr_free().

Customized Configuration

As mentioned at the end of Section Configuration, when the function i2c_param_config() initializes the driver configuration for an I2C port, it also sets several I2C communication parameters to default values defined in the I2C specification. Some other related parameters are pre-configured in registers of the I2C controller.

All these parameters can be changed to user-defined values by calling dedicated functions given in the table below. Please note that the timing values are defined in APB clock cycles. The frequency of APB is specified in I2C_APB_CLK_FREQ.

Other Configurable I2C Communication Parameters
Parameters to Change Function
High time and low time for SCL pulses i2c_set_period()
SCL and SDA signal timing used during generation of start signals i2c_set_start_timing()
SCL and SDA signal timing used during generation of stop signals i2c_set_stop_timing()
Timing relationship between SCL and SDA signals when slave samples, as well as when master toggles i2c_set_data_timing()
I2C timeout i2c_set_timeout()
Choice between transmitting / receiving the LSB or MSB first, choose one of the modes defined in i2c_trans_mode_t i2c_set_data_mode()

Each of the above functions has a _get_ counterpart to check the currently set value. For example, to check the I2C timeout value, call i2c_get_timeout().

To check the default parameter values which are set during the driver configuration process, please refer to the file driver/i2c.c and look for defines with the suffix _DEFAULT.

You can also select different pins for SDA and SCL signals and alter the configuration of pull-ups with the function i2c_set_pin(). If you want to modify already entered values, use the function i2c_param_config().

Note

ESP32’s internal pull-ups are in the range of tens of kOhm, which is, in most cases, insufficient for use as I2C pull-ups. Users are advised to use external pull-ups with values described in the I2C specification.

Error Handling

The majority of I2C driver functions either return ESP_OK on successful completion or a specific error code on failure. It is a good practice to always check the returned values and implement error handling. The driver also prints out log messages that contain error details, e.g., when checking the validity of entered configuration. For details please refer to the file driver/i2c.c and look for defines with the suffix _ERR_STR.

Use dedicated interrupts to capture communication failures. For instance, if a slave stretches the clock for too long while preparing the data to send back to master, the interrupt I2C_TIME_OUT_INT will be triggered. For detailed information, see Interrupt Handling.

In case of a communication failure, you can reset the internal hardware buffers by calling the functions i2c_reset_tx_fifo() and i2c_reset_rx_fifo() for the send and receive buffers respectively.

Delete Driver

When the I2C communication is established with the function i2c_driver_install() and is not required for some substantial amount of time, the driver may be deinitialized to release allocated resources by calling i2c_driver_delete().

Application Example

I2C master and slave example: peripherals/i2c.

API Reference

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.

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