i2cdev: ESP-IDF I2C master thread-safe utilities
- struct i2c_dev_t
I2C device descriptor.
This structure supports both legacy ESP-IDF I2C driver and modern i2c_master driver.
┌─── REQUIRED (Set by user) ───────────────────────────────────────────┐ │ - dev->port - I2C port number (e.g., I2C_NUM_0) │ │ - dev->addr - Device I2C address (e.g., 0x48) │ │ - dev->cfg.sda_io_num - SDA pin (-1 = use Kconfig default) │ │ - dev->cfg.scl_io_num - SCL pin (-1 = use Kconfig default) │ │ - dev->cfg.master.clk_speed - Clock speed in Hz (e.g., 400000) │ └──────────────────────────────────────────────────────────────────────┘
┌─── OPTIONAL (Set by user if needed) ─────────────────────────────────┐ │ - dev->addr_bit_len - Address format (defaults to 7-bit) - NEW │ │ - dev->cfg.sda_pullup_en - Enable internal SDA pullup │ │ - dev->cfg.scl_pullup_en - Enable internal SCL pullup │ │ - dev->timeout_ticks - Legacy driver timeout (legacy only) │ └──────────────────────────────────────────────────────────────────────┘
┌─── AUTO-POPULATED (library fills these) ─────────────────────────────┐ │ - dev->mutex - Device mutex handle │ │ - dev->dev_handle - I2C device handle (modern driver) - NEW │ │ - dev->sda_pin - Actual SDA pin used by bus │ │ - dev->scl_pin - Actual SCL pin used by bus │ └──────────────────────────────────────────────────────────────────────┘
Note
INITIALIZATION CHECKLIST - Set these fields before calling i2c_dev_create_mutex():
Note
BACKWARD COMPATIBILITY DESIGN: The custom ‘cfg’ structure mimics ESP-IDF’s deprecated i2c_config_t layout to maintain zero-change compatibility with existing device drivers. ESP-IDF ≥5.2 deprecated i2c_config_t and split it into separate bus/device configs, but this library preserves the familiar field paths like: dev->cfg.sda_io_num, dev->cfg.scl_io_num, dev->cfg.master.clk_speed
Public Members
- i2c_port_t port
I2C port number (e.g., I2C_NUM_0)
- uint16_t addr
Device I2C address (e.g., 0x48 for 7-bit)
- i2c_addr_bit_len_t addr_bit_len
Address format: I2C_ADDR_BIT_LEN_7 (default) or I2C_ADDR_BIT_LEN_10.
- SemaphoreHandle_t mutex
Device mutex - Created by i2c_dev_create_mutex()
- void *dev_handle
Device handle - Modern driver only, created lazily (when actual I2C operation is performed)
- int sda_pin
Actual SDA pin used - Populated after port setup.
- int scl_pin
Actual SCL pin used - Populated after port setup.
- uint32_t timeout_ticks
Clock stretching timeout - Legacy driver only.
- gpio_num_t sda_io_num
Desired SDA pin (-1 = use Kconfig default)
- gpio_num_t scl_io_num
Desired SCL pin (-1 = use Kconfig default)
- uint8_t sda_pullup_en
Enable internal SDA pullup (optional)
- uint8_t scl_pullup_en
Enable internal SCL pullup (optional)
- uint32_t clk_speed
Clock speed in Hz.