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

#include <EspI2c.h>

Collaboration diagram for EspI2cBus:

Public Member Functions
	EspI2cBus (const hf_i2c_master_bus_config_t &config) noexcept
	Construct a new EspI2cBus.

	~EspI2cBus () noexcept
	Destructor. Automatically deinitializes the bus and devices if needed.

	EspI2cBus (const EspI2cBus &)=delete

EspI2cBus &	operator= (const EspI2cBus &)=delete

	EspI2cBus (EspI2cBus &&)=delete

EspI2cBus &	operator= (EspI2cBus &&)=delete

bool	Initialize () noexcept
	Initialize the I2C bus.

bool	Deinitialize () noexcept
	Deinitialize the I2C bus and remove all devices.

int	CreateDevice (const hf_i2c_device_config_t &device_config) noexcept
	Create and add a device to the I2C bus.

BaseI2c *	GetDevice (int device_index) noexcept
	Get device by index (BaseI2c interface).

const BaseI2c *	GetDevice (int device_index) const noexcept
	Get device by index (const version).

EspI2cDevice *	GetEspDevice (int device_index) noexcept
	Get ESP-specific device by index.

const EspI2cDevice *	GetEspDevice (int device_index) const noexcept
	Get ESP-specific device by index (const version).

BaseI2c *	GetDeviceByAddress (hf_u16_t device_address) noexcept
	Get device by address.

std::size_t	GetDeviceCount () const noexcept
	Get number of devices on the bus.

bool	RemoveDevice (int device_index) noexcept
	Remove a device from the bus.

bool	RemoveDeviceByAddress (hf_u16_t device_address) noexcept
	Remove a device from the bus by address.

BaseI2c *	operator[] (int device_index) noexcept
	Get device by index with bounds checking.

const BaseI2c *	operator[] (int device_index) const noexcept
	Get device by index with bounds checking (const version).

EspI2cDevice *	At (int device_index) noexcept
	Get ESP-specific device by index with bounds checking.

const EspI2cDevice *	At (int device_index) const noexcept
	Get ESP-specific device by index with bounds checking (const version).

bool	IsValidIndex (int device_index) const noexcept
	Check if device index is valid.

BaseI2c *	GetFirstDevice () noexcept
	Get first device on the bus.

const BaseI2c *	GetFirstDevice () const noexcept
	Get first device on the bus (const version).

BaseI2c *	GetLastDevice () noexcept
	Get last device on the bus.

const BaseI2c *	GetLastDevice () const noexcept
	Get last device on the bus (const version).

std::vector< BaseI2c * >	GetAllDevices () noexcept
	Get all devices as a vector of BaseI2c pointers.

std::vector< const BaseI2c * >	GetAllDevices () const noexcept
	Get all devices as a vector of const BaseI2c pointers.

std::vector< EspI2cDevice * >	GetAllEspDevices () noexcept
	Get all ESP-specific devices as a vector.

std::vector< const EspI2cDevice * >	GetAllEspDevices () const noexcept
	Get all ESP-specific devices as a vector (const version).

int	FindDeviceIndex (hf_u16_t device_address) const noexcept
	Find device index by address with bounds checking.

std::vector< hf_u16_t >	GetDeviceAddresses () const noexcept
	Get device addresses as a vector.

bool	HasDevices () const noexcept
	Check if bus has any devices.

bool	IsEmpty () const noexcept
	Check if bus is empty (no devices).

bool	ClearAllDevices () noexcept
	Clear all devices from the bus.

const hf_i2c_master_bus_config_t &	GetConfig () const noexcept
	Get the bus configuration.

i2c_master_bus_handle_t	GetHandle () const noexcept
	Get the ESP-IDF bus handle.

int	GetPort () const noexcept
	Get the I2C port number.

bool	IsInitialized () const noexcept
	Check if the bus is initialized.

size_t	ScanDevices (std::vector< hf_u16_t > &found_devices, hf_u16_t start_addr=0x08, hf_u16_t end_addr=0x77, hf_u32_t scan_timeout_ms=0) noexcept
	Scan the I2C bus for devices.

bool	ProbeDevice (hf_u16_t device_addr, hf_u32_t timeout_ms=10) noexcept
	Probe for device presence on the bus.

bool	ResetBus () noexcept
	Reset the I2C bus.

hf_i2c_mode_t	GetMode () const noexcept
	Get the current I2C operation mode.

bool	IsAsyncMode () const noexcept
	Check if async mode is enabled.

bool	IsSyncMode () const noexcept
	Check if sync mode is enabled.

bool	SwitchMode (hf_i2c_mode_t new_mode, uint8_t queue_depth=10) noexcept
	Switch operation mode (recreates bus)

Private Member Functions
int	FindDeviceIndexByAddress (hf_u16_t device_address) const noexcept
	Find device index by address.

hf_i2c_err_t	ConvertEspError (esp_err_t esp_error) const noexcept
	Convert ESP-IDF error to HardFOC error.

bool	CustomFastProbe (hf_u16_t device_addr, hf_u32_t timeout_ms) noexcept
	Custom fast I2C probe that works around ESP-IDF's broken probe function.

Private Attributes
hf_i2c_master_bus_config_t	config_
	Bus configuration.

i2c_master_bus_handle_t	bus_handle_
	ESP-IDF bus handle.

bool	initialized_
	Initialization status.

PlatformMutex	mutex_
	Bus mutex for thread safety.

std::vector< std::unique_ptr< EspI2cDevice > >	devices_
	Device instances.

hf_i2c_mode_t	current_mode_
	Current operation mode.

hf_i2c_statistics_t	statistics_
	Bus-level statistics.

hf_i2c_diagnostics_t	diagnostics_
	Bus-level diagnostics.

Detailed Description

Manages a single I2C bus. Handles bus initialization and device creation.

Provides full configuration and control for the I2C bus, including device management, bus initialization, and ESP-IDF v5.5+ features. Thread-safe device management with proper resource cleanup.

Constructor & Destructor Documentation

◆ EspI2cBus() [1/3]

EspI2cBus::EspI2cBus ( const hf_i2c_master_bus_config_t & config )

explicitnoexcept

Construct a new EspI2cBus.

Parameters

config Bus configuration

◆ ~EspI2cBus()

EspI2cBus::~EspI2cBus ( )

noexcept

Destructor. Automatically deinitializes the bus and devices if needed.

◆ EspI2cBus() [2/3]

EspI2cBus::EspI2cBus ( const EspI2cBus & )

delete

◆ EspI2cBus() [3/3]

EspI2cBus::EspI2cBus ( EspI2cBus && )

delete

Member Function Documentation

◆ At() [1/2]

const EspI2cDevice * EspI2cBus::At ( int device_index ) const

noexcept

Get ESP-specific device by index with bounds checking (const version).

Parameters

device_index Index of the device (0-based)

Returns: Pointer to const EspI2cDevice, or nullptr if index out of bounds

Note: Thread-safe access to devices

◆ At() [2/2]

EspI2cDevice * EspI2cBus::At ( int device_index )

noexcept

Get ESP-specific device by index with bounds checking.

Parameters

device_index Index of the device (0-based)

Returns: Pointer to EspI2cDevice, or nullptr if index out of bounds

Note: Thread-safe access to devices

◆ ClearAllDevices()

bool EspI2cBus::ClearAllDevices ( )

noexcept

Clear all devices from the bus.

Returns: true if successful, false otherwise

Note: All devices will be properly deinitialized and removed

◆ ConvertEspError()

hf_i2c_err_t EspI2cBus::ConvertEspError ( esp_err_t esp_error ) const

privatenoexcept

Convert ESP-IDF error to HardFOC error.

Parameters

esp_error ESP-IDF error code

Returns: HardFOC I2C error code

◆ CreateDevice()

int EspI2cBus::CreateDevice ( const hf_i2c_device_config_t & device_config )

noexcept

Create and add a device to the I2C bus.

Parameters

device_config Device configuration

Returns: Device index (>= 0) if successful, -1 if failed

◆ CustomFastProbe()

bool EspI2cBus::CustomFastProbe	(	hf_u16_t	device_addr,
		hf_u32_t	timeout_ms )

privatenoexcept

Custom fast I2C probe that works around ESP-IDF's broken probe function.

Parameters

device_addr	Device address to probe
timeout_ms	Timeout in milliseconds

Returns: true if device responds, false otherwise

Note: This function creates a temporary device and performs a real I2C transaction; Much faster and more reliable than ESP-IDF's broken probe function

◆ Deinitialize()

bool EspI2cBus::Deinitialize ( )

noexcept

Deinitialize the I2C bus and remove all devices.

Returns: true if successful, false otherwise

◆ FindDeviceIndex()

int EspI2cBus::FindDeviceIndex ( hf_u16_t device_address ) const

noexcept

Find device index by address with bounds checking.

Parameters

device_address Device address to find

Returns: Device index if found, -1 if not found

◆ FindDeviceIndexByAddress()

int EspI2cBus::FindDeviceIndexByAddress ( hf_u16_t device_address ) const

privatenoexcept

Find device index by address.

Parameters

device_address Device address to find

Returns: Device index if found, -1 otherwise

◆ GetAllDevices() [1/2]

std::vector< const BaseI2c * > EspI2cBus::GetAllDevices ( ) const

noexcept

Get all devices as a vector of const BaseI2c pointers.

Returns: Vector of const BaseI2c pointers (copy of internal device list)

Note: Thread-safe, returns a copy of the current device list

◆ GetAllDevices() [2/2]

std::vector< BaseI2c * > EspI2cBus::GetAllDevices ( )

noexcept

Get all devices as a vector of BaseI2c pointers.

Returns: Vector of BaseI2c pointers (copy of internal device list)

Note: Thread-safe, returns a copy of the current device list

◆ GetAllEspDevices() [1/2]

std::vector< const EspI2cDevice * > EspI2cBus::GetAllEspDevices ( ) const

noexcept

Get all ESP-specific devices as a vector (const version).

Returns: Vector of const EspI2cDevice pointers (copy of internal device list)

Note: Thread-safe, returns a copy of the current device list

◆ GetAllEspDevices() [2/2]

std::vector< EspI2cDevice * > EspI2cBus::GetAllEspDevices ( )

noexcept

Get all ESP-specific devices as a vector.

Returns: Vector of EspI2cDevice pointers (copy of internal device list)

Note: Thread-safe, returns a copy of the current device list

◆ GetConfig()

const hf_i2c_master_bus_config_t & EspI2cBus::GetConfig ( ) const

noexcept

Get the bus configuration.

Returns: const hf_i2c_master_bus_config_t&

◆ GetDevice() [1/2]

const BaseI2c * EspI2cBus::GetDevice ( int device_index ) const

noexcept

Get device by index (const version).

Parameters

device_index Index of the device

Returns: Pointer to const BaseI2c device, or nullptr if invalid

◆ GetDevice() [2/2]

BaseI2c * EspI2cBus::GetDevice ( int device_index )

noexcept

Get device by index (BaseI2c interface).

Parameters

device_index Index of the device

Returns: Pointer to BaseI2c device, or nullptr if invalid

◆ GetDeviceAddresses()

std::vector< hf_u16_t > EspI2cBus::GetDeviceAddresses ( ) const

noexcept

Get device addresses as a vector.

Returns: Vector of device addresses

Note: Thread-safe, returns a copy of current device addresses

◆ GetDeviceByAddress()

BaseI2c * EspI2cBus::GetDeviceByAddress ( hf_u16_t device_address )

noexcept

Get device by address.

Parameters

device_address Device address to find

Returns: Pointer to BaseI2c device, or nullptr if not found

◆ GetDeviceCount()

std::size_t EspI2cBus::GetDeviceCount ( ) const

noexcept

Get number of devices on the bus.

Returns: Number of devices

◆ GetEspDevice() [1/2]

const EspI2cDevice * EspI2cBus::GetEspDevice ( int device_index ) const

noexcept

Get ESP-specific device by index (const version).

Parameters

device_index Index of the device

Returns: Pointer to const EspI2cDevice, or nullptr if invalid

◆ GetEspDevice() [2/2]

EspI2cDevice * EspI2cBus::GetEspDevice ( int device_index )

noexcept

Get ESP-specific device by index.

Parameters

device_index Index of the device

Returns: Pointer to EspI2cDevice, or nullptr if invalid

◆ GetFirstDevice() [1/2]

const BaseI2c * EspI2cBus::GetFirstDevice ( ) const

noexcept

Get first device on the bus (const version).

Returns: Pointer to first const BaseI2c device, or nullptr if no devices

◆ GetFirstDevice() [2/2]

BaseI2c * EspI2cBus::GetFirstDevice ( )

noexcept

Get first device on the bus.

Returns: Pointer to first BaseI2c device, or nullptr if no devices

◆ GetHandle()

i2c_master_bus_handle_t EspI2cBus::GetHandle ( ) const

noexcept

Get the ESP-IDF bus handle.

Returns: i2c_master_bus_handle_t

◆ GetLastDevice() [1/2]

const BaseI2c * EspI2cBus::GetLastDevice ( ) const

noexcept

Get last device on the bus (const version).

Returns: Pointer to last const BaseI2c device, or nullptr if no devices

◆ GetLastDevice() [2/2]

BaseI2c * EspI2cBus::GetLastDevice ( )

noexcept

Get last device on the bus.

Returns: Pointer to last BaseI2c device, or nullptr if no devices

◆ GetMode()

hf_i2c_mode_t EspI2cBus::GetMode ( ) const

noexcept

Get the current I2C operation mode.

Returns: Current operation mode (sync/async)

◆ GetPort()

int EspI2cBus::GetPort ( ) const

noexcept

Get the I2C port number.

Returns: I2C port number

◆ HasDevices()

bool EspI2cBus::HasDevices ( ) const

noexcept

Check if bus has any devices.

Returns: true if bus has devices, false if empty

◆ Initialize()

bool EspI2cBus::Initialize ( )

noexcept

Initialize the I2C bus.

Returns: true if successful, false otherwise

◆ IsAsyncMode()

bool EspI2cBus::IsAsyncMode ( ) const

noexcept

Check if async mode is enabled.

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

◆ IsEmpty()

bool EspI2cBus::IsEmpty ( ) const

noexcept

Check if bus is empty (no devices).

Returns: true if bus is empty, false if it has devices

◆ IsInitialized()

bool EspI2cBus::IsInitialized ( ) const

noexcept

Check if the bus is initialized.

Returns: true if initialized, false otherwise

◆ IsSyncMode()

bool EspI2cBus::IsSyncMode ( ) const

noexcept

Check if sync mode is enabled.

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

◆ IsValidIndex()

bool EspI2cBus::IsValidIndex ( int device_index ) const

noexcept

Check if device index is valid.

Parameters

device_index Index to check

Returns: true if index is valid, false otherwise

◆ operator=() [1/2]

EspI2cBus & EspI2cBus::operator= ( const EspI2cBus & )

delete

◆ operator=() [2/2]

EspI2cBus & EspI2cBus::operator= ( EspI2cBus && )

delete

◆ operator[]() [1/2]

const BaseI2c * EspI2cBus::operator[] ( int device_index ) const

noexcept

Get device by index with bounds checking (const version).

Parameters

device_index Index of the device (0-based)

Returns: Pointer to const BaseI2c device, or nullptr if index out of bounds

Note: Thread-safe access to devices

◆ operator[]() [2/2]

BaseI2c * EspI2cBus::operator[] ( int device_index )

noexcept

Get device by index with bounds checking.

Parameters

device_index Index of the device (0-based)

Returns: Pointer to BaseI2c device, or nullptr if index out of bounds

Note: Thread-safe access to devices

◆ ProbeDevice()

bool EspI2cBus::ProbeDevice	(	hf_u16_t	device_addr,
		hf_u32_t	timeout_ms = 10 )

noexcept

Probe for device presence on the bus.

Parameters

device_addr	Device address to probe
timeout_ms	Timeout in milliseconds (0 = use default 1000ms)

Returns: true if device responds, false otherwise

◆ RemoveDevice()

bool EspI2cBus::RemoveDevice ( int device_index )

noexcept

Remove a device from the bus.

Parameters

device_index Index of the device to remove

Returns: true if successful, false otherwise

◆ RemoveDeviceByAddress()

bool EspI2cBus::RemoveDeviceByAddress ( hf_u16_t device_address )

noexcept

Remove a device from the bus by address.

Parameters

device_address Address of the device to remove

Returns: true if successful, false otherwise

◆ ResetBus()

bool EspI2cBus::ResetBus ( )

noexcept

Reset the I2C bus.

Returns: true if successful, false otherwise

◆ ScanDevices()

size_t EspI2cBus::ScanDevices	(	std::vector< hf_u16_t > &	found_devices,
		hf_u16_t	start_addr = 0x08,
		hf_u16_t	end_addr = 0x77,
		hf_u32_t	scan_timeout_ms = 0 )

noexcept

Scan the I2C bus for devices.

Parameters

found_devices	Vector to store found device addresses
start_addr	Starting address for scan (default: 0x08)
end_addr	Ending address for scan (default: 0x77)
scan_timeout_ms	Timeout for each probe operation (0 = use fast 10ms timeout)

Returns: Number of devices found

◆ SwitchMode()

bool EspI2cBus::SwitchMode	(	hf_i2c_mode_t	new_mode,
		uint8_t	queue_depth = 10 )

noexcept

Switch operation mode (recreates bus)

Parameters

new_mode	New operation mode to switch to
queue_depth	Queue depth for async mode (ignored for sync mode)

Returns: true if successful, false otherwise

Note: This will deinitialize and reinitialize the bus

Member Data Documentation

◆ bus_handle_

i2c_master_bus_handle_t EspI2cBus::bus_handle_

private

ESP-IDF bus handle.

◆ config_

hf_i2c_master_bus_config_t EspI2cBus::config_

private

Bus configuration.

◆ current_mode_

hf_i2c_mode_t EspI2cBus::current_mode_

private

Current operation mode.

◆ devices_

std::vector<std::unique_ptr<EspI2cDevice> > EspI2cBus::devices_

private

Device instances.

◆ diagnostics_

hf_i2c_diagnostics_t EspI2cBus::diagnostics_

mutableprivate

Bus-level diagnostics.

◆ initialized_

bool EspI2cBus::initialized_

private

Initialization status.

◆ mutex_

PlatformMutex EspI2cBus::mutex_

mutableprivate

Bus mutex for thread safety.

◆ statistics_

hf_i2c_statistics_t EspI2cBus::statistics_

mutableprivate

Bus-level statistics.

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

inc/mcu/esp32/EspI2c.h
src/mcu/esp32/EspI2c.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ EspI2cBus() [1/3]

◆ ~EspI2cBus()

◆ EspI2cBus() [2/3]

◆ EspI2cBus() [3/3]

Member Function Documentation

◆ At() [1/2]

◆ At() [2/2]

◆ ClearAllDevices()

◆ ConvertEspError()

◆ CreateDevice()

◆ CustomFastProbe()

◆ Deinitialize()

◆ FindDeviceIndex()

◆ FindDeviceIndexByAddress()

◆ GetAllDevices() [1/2]

◆ GetAllDevices() [2/2]

◆ GetAllEspDevices() [1/2]

◆ GetAllEspDevices() [2/2]

◆ GetConfig()

◆ GetDevice() [1/2]

◆ GetDevice() [2/2]

◆ GetDeviceAddresses()

◆ GetDeviceByAddress()

◆ GetDeviceCount()

◆ GetEspDevice() [1/2]

◆ GetEspDevice() [2/2]

◆ GetFirstDevice() [1/2]

◆ GetFirstDevice() [2/2]

◆ GetHandle()

◆ GetLastDevice() [1/2]

◆ GetLastDevice() [2/2]

◆ GetMode()

◆ GetPort()

◆ HasDevices()

◆ Initialize()

◆ IsAsyncMode()

◆ IsEmpty()

◆ IsInitialized()

◆ IsSyncMode()

◆ IsValidIndex()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ ProbeDevice()

◆ RemoveDevice()

◆ RemoveDeviceByAddress()

◆ ResetBus()

◆ ScanDevices()

◆ SwitchMode()

Member Data Documentation

◆ bus_handle_

◆ config_

◆ current_mode_

◆ devices_

◆ diagnostics_

◆ initialized_

◆ mutex_

◆ statistics_