Advanced ESP32-integrated I2C controller for ESP-IDF v5.5+ with proper bus-device architecture. More...

#include "BaseI2c.h"
#include "utils/EspTypes.h"
#include "utils/PlatformMutex.h"
#include <memory>
#include <vector>
#include "driver/i2c_master.h"
#include "esp_log.h"

Include dependency graph for EspI2c.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	EspI2cDevice
	Represents a single I2C device on a bus. More...

class	EspI2cBus
	Manages a single I2C bus. Handles bus initialization and device creation. More...

Enumerations
enum class	hf_i2c_operation_t : uint8_t { HF_I2C_OP_WRITE = 0 , HF_I2C_OP_READ = 1 , HF_I2C_OP_WRITE_READ = 2 , HF_I2C_OP_WRITE_ASYNC = 3 , HF_I2C_OP_READ_ASYNC = 4 , HF_I2C_OP_WRITE_READ_ASYNC = 5 }
	Enumeration for I2C operation types used in logging and validation. More...

Functions
const char *	HfI2COperationToString (hf_i2c_operation_t op) noexcept
	Convert operation type to string for logging.

Detailed Description

Advanced ESP32-integrated I2C controller for ESP-IDF v5.5+ with proper bus-device architecture.

This header provides a comprehensive I2C implementation that properly utilizes the ESP-IDF v5.5+ bus-device model, following the same pattern as the SPI implementation. The architecture separates bus management from device operations, providing clean abstraction and optimal resource management.

ESP32/ESP-IDF v5.5+ Features Supported:

Bus-Device Architecture: Separate EspI2cBus and EspI2cDevice classes
Modern API: Uses i2c_new_master_bus() and i2c_master_bus_add_device()
Mode-Aware Operations: Single mode variable determines sync vs async capabilities
Per-Device Configuration: Each device has its own clock speed and settings
Thread Safety: Full RTOS integration with proper synchronization
Device Management: Dynamic device addition/removal with proper cleanup
BaseI2c Integration: EspI2cDevice inherits from BaseI2c for portability
Comprehensive Error Handling: Proper error conversion and reporting
Resource Management: Automatic cleanup and proper resource lifecycle

Performance Characteristics:

Standard Mode: 100 kHz
Fast Mode: 400 kHz
Fast Mode Plus: 1 MHz (ESP32)
7-bit and 10-bit addressing support
Clock stretching with configurable timeout
Hardware FIFO utilization
Multi-master operation capability

Author: Nebiyu Tadesse

Date: 2025

Copyright: HardFOC

Version: 4.0.0 - Mode-aware architecture with DRY implementation

Note: This implementation requires ESP-IDF v5.5+ and is optimized for ESP32.; Thread-safe operation is guaranteed for all public methods.; Follows the same architectural pattern as EspSpi for consistency.; ESP-IDF v5.5+ enforces strict separation between sync/async modes.

// Create sync mode bus configuration
hf_i2c_master_bus_config_t bus_config = {};
bus_config.i2c_port = 0;
bus_config.sda_io_num = 21;
bus_config.scl_io_num = 22;
bus_config.mode = hf_i2c_mode_t::HF_I2C_MODE_SYNC;  // Sync mode only
bus_config.trans_queue_depth = 0;  // No queue for sync mode
 
// Create I2C bus
EspI2cBus i2c_bus(bus_config);
if (!i2c_bus.Initialize()) {
    // Handle initialization error
}
 
// Create device configuration
hf_i2c_device_config_t device_config = {};
device_config.device_address = 0x48;
device_config.scl_speed_hz = 400000;
device_config.dev_addr_length = hf_i2c_address_bits_t::HF_I2C_ADDR_7_BIT;
 
// Add device to bus
int device_index = i2c_bus.CreateDevice(device_config);
BaseI2c* device = i2c_bus.GetDevice(device_index);
 
// Use device for I2C operations (sync mode)
uint8_t data[] = {0x10, 0x20, 0x30};
hf_i2c_err_t result = device->Write(data, sizeof(data));

// Create async mode bus configuration
hf_i2c_master_bus_config_t bus_config = {};
bus_config.i2c_port = 0;
bus_config.sda_io_num = 21;
bus_config.scl_io_num = 22;
bus_config.mode = hf_i2c_mode_t::HF_I2C_MODE_ASYNC;  // Async mode only
bus_config.trans_queue_depth = 10;  // Queue required for async mode
 
// Create I2C bus
EspI2cBus i2c_bus(bus_config);
if (!i2c_bus.Initialize()) {
    // Handle initialization error
}
 
// Create device configuration
hf_i2c_device_config_t device_config = {};
device_config.device_address = 0x48;
device_config.scl_speed_hz = 400000;
device_config.dev_addr_length = hf_i2c_address_bits_t::HF_I2C_ADDR_7_BIT;
 
// Add device to bus
int device_index = i2c_bus.CreateDevice(device_config);
BaseI2c* device = i2c_bus.GetDevice(device_index);
 
// Use device for I2C operations (async mode)
uint8_t data[] = {0x10, 0x20, 0x30};
hf_i2c_err_t result = device->WriteAsync(data, sizeof(data),
    [](hf_i2c_err_t err, void* user_data) {
        ESP_LOGI("Async write completed: %s", HfI2CErrToString(err).data());
    });

Enumeration Type Documentation

◆ hf_i2c_operation_t

enum class hf_i2c_operation_t : uint8_t

strong

Enumeration for I2C operation types used in logging and validation.

Enumerator
HF_I2C_OP_WRITE	Write operation.
HF_I2C_OP_READ	Read operation.
HF_I2C_OP_WRITE_READ	Write-then-read operation.
HF_I2C_OP_WRITE_ASYNC	Asynchronous write operation.
HF_I2C_OP_READ_ASYNC	Asynchronous read operation.
HF_I2C_OP_WRITE_READ_ASYNC	Asynchronous write-then-read operation.

Function Documentation

◆ HfI2COperationToString()

const char * HfI2COperationToString ( hf_i2c_operation_t op )

noexcept

Convert operation type to string for logging.

Parameters

op	Operation type

Returns: String representation of operation

Classes

Enumerations