HF Interface Wrapper 0.1.0-dev
Embedded C++ hardware abstraction layer
Loading...
Searching...
No Matches
EspI2cDevice Class Reference

Represents a single I2C device on a bus. More...

#include <EspI2c.h>

Inheritance diagram for EspI2cDevice:
[legend]
Collaboration diagram for EspI2cDevice:
[legend]

Public Member Functions

 EspI2cDevice (EspI2cBus *parent, const hf_i2c_device_config_t &config)
 Construct a new EspI2cDevice.
 
 ~EspI2cDevice () noexcept override
 Destructor. Automatically removes device from bus if needed.
 
bool Initialize () noexcept override
 Initialize the I2C device (no-op if already initialized).
 
bool MarkAsDeinitialized () noexcept
 Mark device as deinitialized without ESP-IDF cleanup.
 
bool Deinitialize () noexcept override
 Deinitialize the device (internal cleanup only)
 
hf_i2c_err_t Write (const hf_u8_t *data, hf_u16_t length, hf_u32_t timeout_ms=0) noexcept override
 Write data to the I2C device.
 
hf_i2c_err_t Read (hf_u8_t *data, hf_u16_t length, hf_u32_t timeout_ms=0) noexcept override
 Read data from the I2C device.
 
hf_i2c_err_t WriteRead (const hf_u8_t *tx_data, hf_u16_t tx_length, hf_u8_t *rx_data, hf_u16_t rx_length, hf_u32_t timeout_ms=0) noexcept override
 Write then read data from the I2C device.
 
hf_i2c_err_t WriteAsync (const hf_u8_t *data, hf_u16_t length, hf_i2c_async_callback_t callback, void *user_data=nullptr, hf_u32_t timeout_ms=1000) noexcept
 Write data to the I2C device asynchronously.
 
hf_i2c_err_t ReadAsync (hf_u8_t *data, hf_u16_t length, hf_i2c_async_callback_t callback, void *user_data=nullptr, hf_u32_t timeout_ms=1000) noexcept
 Read data from the I2C device asynchronously.
 
hf_i2c_err_t WriteReadAsync (const hf_u8_t *tx_data, hf_u16_t tx_length, hf_u8_t *rx_data, hf_u16_t rx_length, hf_i2c_async_callback_t callback, void *user_data=nullptr, hf_u32_t timeout_ms=1000) noexcept
 Write then read data from the I2C device asynchronously.
 
bool IsAsyncModeSupported () const noexcept
 Check if async mode is supported on this device.
 
bool IsAsyncOperationInProgress () const noexcept
 Check if an async operation is currently in progress.
 
bool IsSyncOperationInProgress () const noexcept
 Check if a sync operation is currently in progress.
 
bool WaitAsyncOperationComplete (hf_u32_t timeout_ms=0) noexcept
 Wait for current async operation to complete.
 
hf_i2c_err_t GetStatistics (hf_i2c_statistics_t &statistics) const noexcept override
 Get I2C bus statistics.
 
hf_i2c_err_t GetDiagnostics (hf_i2c_diagnostics_t &diagnostics) const noexcept override
 Get I2C bus diagnostics.
 
hf_i2c_err_t ResetStatistics () noexcept override
 Reset I2C statistics.
 
i2c_master_dev_handle_t GetHandle () const noexcept
 Get the ESP-IDF device handle.
 
const hf_i2c_device_config_tGetConfig () const noexcept
 Get the device configuration.
 
hf_u16_t GetDeviceAddress () const noexcept
 Get the device address.
 
hf_i2c_err_t GetActualClockFrequency (hf_u32_t &actual_freq_hz) const noexcept
 Get the actual clock frequency for this device.
 
bool ProbeDevice () noexcept
 Probe if the device is present on the bus.
 
i2c_master_dev_handle_t GetDeviceHandle () const noexcept
 Get the ESP-IDF device handle for internal operations.
 
hf_i2c_async_callback_t GetCurrentCallback () const noexcept
 Get current async callback (for static callback bridge).
 
void * GetCurrentUserData () const noexcept
 Get current user data (for static callback bridge).
 
void UpdateErrorRecoveryAttempt () noexcept
 Update error recovery attempt statistics.
 
hf_i2c_mode_t GetMode () const noexcept
 Get the current I2C operation mode for this device.
 
bool IsAsyncMode () const noexcept
 Check if this device is in async mode.
 
bool IsSyncMode () const noexcept
 Check if this device is in sync mode.
 
- Public Member Functions inherited from BaseI2c
virtual ~BaseI2c () noexcept=default
 Virtual destructor ensures proper cleanup in derived classes.
 
 BaseI2c (const BaseI2c &)=delete
 
BaseI2coperator= (const BaseI2c &)=delete
 
 BaseI2c (BaseI2c &&)=delete
 
BaseI2coperator= (BaseI2c &&)=delete
 
bool EnsureInitialized () noexcept
 Ensures that the I2C bus is initialized (lazy initialization).
 
bool EnsureDeinitialized () noexcept
 Ensures that the I2C bus is deinitialized (lazy deinitialization).
 
bool IsInitialized () const noexcept
 Checks if the bus is initialized.
 
virtual bool Open () noexcept
 Open the I2C bus (alias for Initialize).
 
virtual bool Close () noexcept
 Close the I2C bus (alias for Deinitialize).
 
virtual bool IsDevicePresent () noexcept
 Check if this device is present on the bus.
 
virtual bool WriteByte (hf_u8_t data) noexcept
 Write a single byte to the I2C device.
 
virtual bool ReadByte (hf_u8_t &data) noexcept
 Read a single byte from the I2C device.
 
virtual bool WriteRegister (hf_u8_t reg_addr, hf_u8_t data) noexcept
 Write to a register on the I2C device.
 
virtual bool ReadRegister (hf_u8_t reg_addr, hf_u8_t &data) noexcept
 Read from a register on the I2C device.
 
virtual bool ReadRegisters (hf_u8_t reg_addr, hf_u8_t *data, hf_u16_t length) noexcept
 Read multiple registers from the I2C device.
 
virtual hf_i2c_err_t ResetDiagnostics () noexcept
 Reset I2C diagnostic information.
 

Private Member Functions

bool RegisterTemporaryCallback (hf_i2c_async_callback_t callback, void *user_data, hf_u32_t timeout_ms) noexcept
 Register temporary async callback for single operation.
 
void UnregisterTemporaryCallback () noexcept
 Unregister temporary async callback after operation.
 
void StartAsyncOperationTracking () noexcept
 Start async operation tracking after I2C operation is successfully started.
 
void UpdateStatistics (bool success, size_t bytes_transferred, hf_u64_t operation_time_us) noexcept
 Update statistics with operation result.
 
void UpdateErrorStatistics (hf_i2c_err_t error_code) noexcept
 Update error-specific statistics.
 
hf_i2c_err_t ConvertEspError (esp_err_t esp_error) const noexcept
 Convert ESP-IDF error to HardFOC error.
 
bool ValidateOperation (const void *data, hf_u16_t length, hf_i2c_operation_t operation_type) noexcept
 Common validation for all I2C operations.
 
bool SetupSyncOperation (hf_i2c_operation_t operation_type) noexcept
 Common sync operation setup and cleanup.
 
void CleanupSyncOperation () noexcept
 Common sync operation cleanup.
 
void CleanupAsyncOperation () noexcept
 Common async operation cleanup.
 
bool SetupAsyncOperation (hf_i2c_async_callback_t callback, void *user_data, hf_u32_t timeout_ms) noexcept
 Common async operation setup.
 

Static Private Member Functions

static bool InternalAsyncCallback (i2c_master_dev_handle_t i2c_dev, const i2c_master_event_data_t *evt_data, void *arg)
 Internal C callback bridge for ESP-IDF callbacks.
 

Private Attributes

EspI2cBusparent_bus_
 Parent bus pointer.
 
i2c_master_dev_handle_t handle_
 ESP-IDF device handle.
 
hf_i2c_device_config_t config_
 Device configuration.
 
bool initialized_
 Initialization status.
 
hf_i2c_statistics_t statistics_
 Per-device statistics.
 
hf_i2c_diagnostics_t diagnostics_
 Per-device diagnostics.
 
PlatformMutex mutex_
 Device mutex for thread safety.
 
hf_i2c_mode_t device_mode_
 Device operation mode (inherited from bus)
 
bool async_operation_in_progress_
 Is async operation active.
 
bool sync_operation_in_progress_
 Is sync operation active (mutual exclusion)
 
hf_i2c_async_callback_t current_callback_
 Current user callback.
 
void * current_user_data_
 Current user data.
 
hf_u64_t async_start_time_
 Async operation start time.
 
hf_i2c_transaction_type_t current_op_type_
 Current operation type.
 
hf_u16_t last_write_length_
 Length of last write operation for async tracking.
 
hf_u16_t last_read_length_
 Length of last read operation for async tracking.
 

Additional Inherited Members

- Protected Member Functions inherited from BaseI2c
 BaseI2c () noexcept
 Protected default constructor. Initializes base I2C state with default values.
 
- Protected Attributes inherited from BaseI2c
bool initialized_
 Initialization status.
 
hf_i2c_statistics_t statistics_
 I2C operation statistics.
 
hf_i2c_diagnostics_t diagnostics_
 I2C diagnostic information.
 

Detailed Description

Represents a single I2C device on a bus.

Inherits from BaseI2c and delegates operations to the parent bus. Provides full configuration and control for a single I2C device, including per-device clock speed, addressing mode, and ESP-IDF v5.5+ features.

Note
Thread-safe. All operations are protected by PlatformMutex.
Each device maintains its own handle and configuration.
Supports both synchronous and asynchronous operations.
Warning
ESP-IDF v5.5 constraint: Only one device per bus can use async mode

Constructor & Destructor Documentation

◆ EspI2cDevice()

EspI2cDevice::EspI2cDevice ( EspI2cBus * parent,
const hf_i2c_device_config_t & config )

Construct a new EspI2cDevice.

Parameters
parentPointer to the parent EspI2cBus
configDevice configuration

◆ ~EspI2cDevice()

EspI2cDevice::~EspI2cDevice ( )
overridenoexcept

Destructor. Automatically removes device from bus if needed.

Member Function Documentation

◆ CleanupAsyncOperation()

void EspI2cDevice::CleanupAsyncOperation ( )
privatenoexcept

Common async operation cleanup.

◆ CleanupSyncOperation()

void EspI2cDevice::CleanupSyncOperation ( )
privatenoexcept

Common sync operation cleanup.

◆ ConvertEspError()

hf_i2c_err_t EspI2cDevice::ConvertEspError ( esp_err_t esp_error) const
privatenoexcept

Convert ESP-IDF error to HardFOC error.

Parameters
esp_errorESP-IDF error code
Returns
HardFOC I2C error code

◆ Deinitialize()

bool EspI2cDevice::Deinitialize ( )
overridevirtualnoexcept

Deinitialize the device (internal cleanup only)

Returns
true if successful

This method only handles internal device cleanup. ESP-IDF cleanup is handled by the parent bus.

Implements BaseI2c.

◆ GetActualClockFrequency()

hf_i2c_err_t EspI2cDevice::GetActualClockFrequency ( hf_u32_t & actual_freq_hz) const
noexcept

Get the actual clock frequency for this device.

Parameters
actual_freq_hzReference to store actual frequency
Returns
Operation result

◆ GetConfig()

const hf_i2c_device_config_t & EspI2cDevice::GetConfig ( ) const
noexcept

Get the device configuration.

Returns
const hf_i2c_device_config_t&

◆ GetCurrentCallback()

hf_i2c_async_callback_t EspI2cDevice::GetCurrentCallback ( ) const
inlinenoexcept

Get current async callback (for static callback bridge).

Returns
Current async callback function

◆ GetCurrentUserData()

void * EspI2cDevice::GetCurrentUserData ( ) const
inlinenoexcept

Get current user data (for static callback bridge).

Returns
Current user data pointer

◆ GetDeviceAddress()

hf_u16_t EspI2cDevice::GetDeviceAddress ( ) const
virtualnoexcept

Get the device address.

Returns
Device address

Implements BaseI2c.

◆ GetDeviceHandle()

i2c_master_dev_handle_t EspI2cDevice::GetDeviceHandle ( ) const
inlinenoexcept

Get the ESP-IDF device handle for internal operations.

Returns
ESP-IDF device handle

◆ GetDiagnostics()

hf_i2c_err_t EspI2cDevice::GetDiagnostics ( hf_i2c_diagnostics_t & diagnostics) const
overridevirtualnoexcept

Get I2C bus diagnostics.

Parameters
diagnosticsReference to diagnostics structure to fill
Returns
Operation result

Reimplemented from BaseI2c.

◆ GetHandle()

i2c_master_dev_handle_t EspI2cDevice::GetHandle ( ) const
noexcept

Get the ESP-IDF device handle.

Returns
i2c_master_dev_handle_t

◆ GetMode()

hf_i2c_mode_t EspI2cDevice::GetMode ( ) const
noexcept

Get the current I2C operation mode for this device.

Returns
Current operation mode (sync/async)

◆ GetStatistics()

hf_i2c_err_t EspI2cDevice::GetStatistics ( hf_i2c_statistics_t & statistics) const
overridevirtualnoexcept

Get I2C bus statistics.

Parameters
statisticsReference to statistics structure to fill
Returns
Operation result

Reimplemented from BaseI2c.

◆ Initialize()

bool EspI2cDevice::Initialize ( )
overridevirtualnoexcept

Initialize the I2C device (no-op if already initialized).

Returns
true if successful, false otherwise

Implements BaseI2c.

◆ InternalAsyncCallback()

bool EspI2cDevice::InternalAsyncCallback ( i2c_master_dev_handle_t i2c_dev,
const i2c_master_event_data_t * evt_data,
void * arg )
staticprivate

Internal C callback bridge for ESP-IDF callbacks.

Parameters
i2c_devESP-IDF device handle
evt_dataEvent data from ESP-IDF (i2c_master_event_data_t)
argUser data (pointer to EspI2cDevice)
Returns
false (no high priority wake needed)
Note
This single callback handles ALL operation types (write/read/write-read)

◆ IsAsyncMode()

bool EspI2cDevice::IsAsyncMode ( ) const
noexcept

Check if this device is in async mode.

Returns
true if in async mode, false if in sync mode

◆ IsAsyncModeSupported()

bool EspI2cDevice::IsAsyncModeSupported ( ) const
noexcept

Check if async mode is supported on this device.

Returns
true if async mode is available, false otherwise

◆ IsAsyncOperationInProgress()

bool EspI2cDevice::IsAsyncOperationInProgress ( ) const
noexcept

Check if an async operation is currently in progress.

Returns
true if async operation is active, false otherwise

◆ IsSyncMode()

bool EspI2cDevice::IsSyncMode ( ) const
noexcept

Check if this device is in sync mode.

Returns
true if in sync mode, false if in async mode

◆ IsSyncOperationInProgress()

bool EspI2cDevice::IsSyncOperationInProgress ( ) const
noexcept

Check if a sync operation is currently in progress.

Returns
true if sync operation is active, false otherwise

◆ MarkAsDeinitialized()

bool EspI2cDevice::MarkAsDeinitialized ( )
noexcept

Mark device as deinitialized without ESP-IDF cleanup.

Returns
true if successful

This method is called by the bus when it handles ESP-IDF cleanup. The device should not attempt to remove itself from the ESP-IDF bus.

◆ ProbeDevice()

bool EspI2cDevice::ProbeDevice ( )
virtualnoexcept

Probe if the device is present on the bus.

Returns
true if device responds, false otherwise

Reimplemented from BaseI2c.

◆ Read()

hf_i2c_err_t EspI2cDevice::Read ( hf_u8_t * data,
hf_u16_t length,
hf_u32_t timeout_ms = 0 )
overridevirtualnoexcept

Read data from the I2C device.

Parameters
dataPointer to buffer to store received data
lengthNumber of bytes to read
timeout_msTimeout in milliseconds (0 = default)
Returns
I2C operation result
Note
Device address is configured during device creation

Implements BaseI2c.

◆ ReadAsync()

hf_i2c_err_t EspI2cDevice::ReadAsync ( hf_u8_t * data,
hf_u16_t length,
hf_i2c_async_callback_t callback,
void * user_data = nullptr,
hf_u32_t timeout_ms = 1000 )
noexcept

Read data from the I2C device asynchronously.

Parameters
dataPointer to buffer to store received data
lengthNumber of bytes to read
callbackCallback function for operation completion
user_dataUser data passed to callback
timeout_msTimeout to wait for async slot availability (0 = no wait)
Returns
I2C operation result
Note
Returns immediately once async operation starts
Completion is reported via callback
Warning
Only one device per bus can use async mode at a time
Note
Will wait for timeout_ms if another async operation is in progress

◆ RegisterTemporaryCallback()

bool EspI2cDevice::RegisterTemporaryCallback ( hf_i2c_async_callback_t callback,
void * user_data,
hf_u32_t timeout_ms )
privatenoexcept

Register temporary async callback for single operation.

Parameters
callbackUser callback to register
user_dataUser data for callback
timeout_msTimeout to wait for slot availability
Returns
true if successful, false otherwise

◆ ResetStatistics()

hf_i2c_err_t EspI2cDevice::ResetStatistics ( )
overridevirtualnoexcept

Reset I2C statistics.

Returns
Operation result

Reimplemented from BaseI2c.

◆ SetupAsyncOperation()

bool EspI2cDevice::SetupAsyncOperation ( hf_i2c_async_callback_t callback,
void * user_data,
hf_u32_t timeout_ms )
privatenoexcept

Common async operation setup.

Parameters
callbackUser callback
user_dataUser data
timeout_msTimeout for slot availability
Returns
true if setup successful, false otherwise

◆ SetupSyncOperation()

bool EspI2cDevice::SetupSyncOperation ( hf_i2c_operation_t operation_type)
privatenoexcept

Common sync operation setup and cleanup.

Parameters
operation_typeOperation type for logging
Returns
true if setup successful, false otherwise

◆ StartAsyncOperationTracking()

void EspI2cDevice::StartAsyncOperationTracking ( )
inlineprivatenoexcept

Start async operation tracking after I2C operation is successfully started.

◆ UnregisterTemporaryCallback()

void EspI2cDevice::UnregisterTemporaryCallback ( )
privatenoexcept

Unregister temporary async callback after operation.

◆ UpdateErrorRecoveryAttempt()

void EspI2cDevice::UpdateErrorRecoveryAttempt ( )
noexcept

Update error recovery attempt statistics.

Note
This method is called by the bus during recovery operations

◆ UpdateErrorStatistics()

void EspI2cDevice::UpdateErrorStatistics ( hf_i2c_err_t error_code)
privatenoexcept

Update error-specific statistics.

Parameters
error_codeThe specific error code to track

◆ UpdateStatistics()

void EspI2cDevice::UpdateStatistics ( bool success,
size_t bytes_transferred,
hf_u64_t operation_time_us )
privatenoexcept

Update statistics with operation result.

Parameters
successOperation success status
bytes_transferredNumber of bytes transferred
operation_time_usOperation time in microseconds

◆ ValidateOperation()

bool EspI2cDevice::ValidateOperation ( const void * data,
hf_u16_t length,
hf_i2c_operation_t operation_type )
privatenoexcept

Common validation for all I2C operations.

Parameters
dataData buffer pointer
lengthData length
operation_typeOperation type for logging
Returns
true if validation passes, false otherwise

◆ WaitAsyncOperationComplete()

bool EspI2cDevice::WaitAsyncOperationComplete ( hf_u32_t timeout_ms = 0)
noexcept

Wait for current async operation to complete.

Parameters
timeout_msTimeout in milliseconds (0 = wait indefinitely)
Returns
true if operation completed, false on timeout

◆ Write()

hf_i2c_err_t EspI2cDevice::Write ( const hf_u8_t * data,
hf_u16_t length,
hf_u32_t timeout_ms = 0 )
overridevirtualnoexcept

Write data to the I2C device.

Parameters
dataPointer to data buffer to write
lengthNumber of bytes to write
timeout_msTimeout in milliseconds (0 = default)
Returns
I2C operation result
Note
Device address is configured during device creation

Implements BaseI2c.

◆ WriteAsync()

hf_i2c_err_t EspI2cDevice::WriteAsync ( const hf_u8_t * data,
hf_u16_t length,
hf_i2c_async_callback_t callback,
void * user_data = nullptr,
hf_u32_t timeout_ms = 1000 )
noexcept

Write data to the I2C device asynchronously.

Parameters
dataPointer to data buffer to write
lengthNumber of bytes to write
callbackCallback function for operation completion
user_dataUser data passed to callback
timeout_msTimeout to wait for async slot availability (0 = no wait)
Returns
I2C operation result
Note
Returns immediately once async operation starts
Completion is reported via callback
Warning
Only one device per bus can use async mode at a time
Note
Will wait for timeout_ms if another async operation is in progress

◆ WriteRead()

hf_i2c_err_t EspI2cDevice::WriteRead ( const hf_u8_t * tx_data,
hf_u16_t tx_length,
hf_u8_t * rx_data,
hf_u16_t rx_length,
hf_u32_t timeout_ms = 0 )
overridevirtualnoexcept

Write then read data from the I2C device.

Parameters
tx_dataPointer to data buffer to write
tx_lengthNumber of bytes to write
rx_dataPointer to buffer to store received data
rx_lengthNumber of bytes to read
timeout_msTimeout in milliseconds (0 = default)
Returns
I2C operation result
Note
Device address is configured during device creation

Implements BaseI2c.

◆ WriteReadAsync()

hf_i2c_err_t EspI2cDevice::WriteReadAsync ( const hf_u8_t * tx_data,
hf_u16_t tx_length,
hf_u8_t * rx_data,
hf_u16_t rx_length,
hf_i2c_async_callback_t callback,
void * user_data = nullptr,
hf_u32_t timeout_ms = 1000 )
noexcept

Write then read data from the I2C device asynchronously.

Parameters
tx_dataPointer to data buffer to write
tx_lengthNumber of bytes to write
rx_dataPointer to buffer to store received data
rx_lengthNumber of bytes to read
callbackCallback function for operation completion
user_dataUser data passed to callback
timeout_msTimeout to wait for async slot availability (0 = no wait)
Returns
I2C operation result
Note
Returns immediately once async operation starts
Completion is reported via callback
Warning
Only one device per bus can use async mode at a time
Note
Will wait for timeout_ms if another async operation is in progress

Member Data Documentation

◆ async_operation_in_progress_

bool EspI2cDevice::async_operation_in_progress_
private

Is async operation active.

◆ async_start_time_

hf_u64_t EspI2cDevice::async_start_time_
private

Async operation start time.

◆ config_

hf_i2c_device_config_t EspI2cDevice::config_
private

Device configuration.

◆ current_callback_

hf_i2c_async_callback_t EspI2cDevice::current_callback_
private

Current user callback.

◆ current_op_type_

hf_i2c_transaction_type_t EspI2cDevice::current_op_type_
private

Current operation type.

◆ current_user_data_

void* EspI2cDevice::current_user_data_
private

Current user data.

◆ device_mode_

hf_i2c_mode_t EspI2cDevice::device_mode_
private

Device operation mode (inherited from bus)

◆ diagnostics_

hf_i2c_diagnostics_t EspI2cDevice::diagnostics_
mutableprivate

Per-device diagnostics.

◆ handle_

i2c_master_dev_handle_t EspI2cDevice::handle_
private

ESP-IDF device handle.

◆ initialized_

bool EspI2cDevice::initialized_
private

Initialization status.

◆ last_read_length_

hf_u16_t EspI2cDevice::last_read_length_
private

Length of last read operation for async tracking.

◆ last_write_length_

hf_u16_t EspI2cDevice::last_write_length_
private

Length of last write operation for async tracking.

◆ mutex_

PlatformMutex EspI2cDevice::mutex_
mutableprivate

Device mutex for thread safety.

◆ parent_bus_

EspI2cBus* EspI2cDevice::parent_bus_
private

Parent bus pointer.

◆ statistics_

hf_i2c_statistics_t EspI2cDevice::statistics_
mutableprivate

Per-device statistics.

◆ sync_operation_in_progress_

bool EspI2cDevice::sync_operation_in_progress_
private

Is sync operation active (mutual exclusion)


The documentation for this class was generated from the following files: