I2C master bus controller with thread-safe device access. More...

Classes
struct	config
	I2C master bus configuration. More...

Public Member Functions
	master_bus (enum port port, const struct config &config)
	Creates a new I2C master bus.

	master_bus (enum port port, gpio sda, gpio scl, freq::hertz frequency)
	Creates a new I2C master bus with default settings.

	~master_bus ()

	master_bus (const master_bus &)=delete

master_bus &	operator= (const master_bus &)=delete

	master_bus (master_bus &&other) noexcept

master_bus &	operator= (master_bus &&other) noexcept

void	lock () const
	Acquires exclusive access to the bus.

bool	try_lock () const noexcept
	Tries to acquire exclusive access without blocking.

void	unlock () const
	Releases exclusive access to the bus.

i2c_master_bus_handle_t	handle () const
	Returns the underlying ESP-IDF bus handle.

enum port	port () const
	Returns the I2C port.

freq::hertz	frequency () const
	Returns the bus clock frequency in Hz.

std::vector< uint8_t >	scan_devices () const
	Scans for devices on the bus.

template<typename Rep , typename Period >
std::vector< uint8_t >	scan_devices (const std::chrono::duration< Rep, Period > &timeout) const
	Scans for devices on the bus.

void	probe (uint16_t address) const
	Probes for a device at the specified address.

template<typename Rep , typename Period >
void	probe (uint16_t address, const std::chrono::duration< Rep, Period > &timeout) const
	Probes for a device at the specified address.

result< void >	try_probe (uint16_t address) const
	Probes for a device at the specified address.

template<typename Rep , typename Period >
result< void >	try_probe (uint16_t address, const std::chrono::duration< Rep, Period > &timeout) const
	Probes for a device at the specified address.

template<typename Rep , typename Period >
void	wait_all_done (const std::chrono::duration< Rep, Period > &timeout) const
	Waits for all pending asynchronous operations on the bus to complete.

template<typename Rep , typename Period >
result< void >	try_wait_all_done (const std::chrono::duration< Rep, Period > &timeout) const
	Waits for all pending asynchronous operations on the bus to complete.

Static Public Member Functions
static result< master_bus >	make (enum port port, const struct config &config)
	Creates a new I2C master bus.

static result< master_bus >	make (enum port port, gpio sda, gpio scl, freq::hertz frequency)
	Creates a new I2C master bus with default settings.

Detailed Description

I2C master bus controller with thread-safe device access.

Represents an I2C bus operating in master mode. Satisfies the Lockable named requirement for use with std::lock_guard and std::unique_lock.

This type is non-copyable and move-only. Result-returning methods on a moved-from object return errc::invalid_state. Simple accessors return default/null values. The Lockable methods (lock/try_lock/unlock) silently no-op on a moved-from object.

Definition at line 153 of file master.hpp.

Constructor & Destructor Documentation

◆ master_bus() [1/4]

idfxx::i2c::master_bus::master_bus	(	enum port	port,
		const struct config &	config
	)

explicit

Creates a new I2C master bus.

Parameters

port	I2C port number.
config	Bus configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

idfxx::i2c::master_bus bus(idfxx::i2c::port::i2c0, {
    .sda = idfxx::gpio_21,
    .scl = idfxx::gpio_22,
    .frequency = 400_kHz,
    .enable_internal_pullup = false,
});

◆ master_bus() [2/4]

idfxx::i2c::master_bus::master_bus	(	enum port	port,
		gpio	sda,
		gpio	scl,
		freq::hertz	frequency
	)

explicit

Creates a new I2C master bus with default settings.

Parameters

port	I2C port number.
sda	GPIO pin for the SDA line.
scl	GPIO pin for the SCL line.
frequency	Clock frequency in Hz.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ ~master_bus()

idfxx::i2c::master_bus::~master_bus ( )

◆ master_bus() [3/4]

idfxx::i2c::master_bus::master_bus ( const master_bus & )

delete

◆ master_bus() [4/4]

idfxx::i2c::master_bus::master_bus ( master_bus && other )

noexcept

Member Function Documentation

◆ frequency()

freq::hertz idfxx::i2c::master_bus::frequency ( ) const

inline

Returns the bus clock frequency in Hz.

Definition at line 289 of file master.hpp.

◆ handle()

i2c_master_bus_handle_t idfxx::i2c::master_bus::handle ( ) const

inline

Returns the underlying ESP-IDF bus handle.

Definition at line 283 of file master.hpp.

◆ lock()

void idfxx::i2c::master_bus::lock ( ) const

inline

Acquires exclusive access to the bus.

Definition at line 259 of file master.hpp.

◆ make() [1/2]

static result< master_bus > idfxx::i2c::master_bus::make	(	enum port	port,
		const struct config &	config
	)

static

Creates a new I2C master bus.

Parameters

port	I2C port number.
config	Bus configuration.

Returns: The new master_bus, or an error.

auto bus = idfxx::i2c::master_bus::make(idfxx::i2c::port::i2c0, {
    .sda = idfxx::gpio_21,
    .scl = idfxx::gpio_22,
    .frequency = 400_kHz,
    .enable_internal_pullup = false,
});

◆ make() [2/2]

static result< master_bus > idfxx::i2c::master_bus::make	(	enum port	port,
		gpio	sda,
		gpio	scl,
		freq::hertz	frequency
	)

static

Creates a new I2C master bus with default settings.

Parameters

port	I2C port number.
sda	GPIO pin for the SDA line.
scl	GPIO pin for the SCL line.
frequency	Clock frequency in Hz.

Returns: The new master_bus, or an error.

◆ operator=() [1/2]

master_bus & idfxx::i2c::master_bus::operator= ( const master_bus & )

delete

◆ operator=() [2/2]

master_bus & idfxx::i2c::master_bus::operator= ( master_bus && other )

noexcept

◆ port()

enum port idfxx::i2c::master_bus::port ( ) const

inline

Returns the I2C port.

Definition at line 286 of file master.hpp.

◆ probe() [1/2]

void idfxx::i2c::master_bus::probe ( uint16_t address ) const

inline

Probes for a device at the specified address.

Parameters

address Device address.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the device does not acknowledge or on error.

Definition at line 323 of file master.hpp.

References idfxx::i2c::DEFAULT_TIMEOUT, and probe().

Referenced by probe().

◆ probe() [2/2]

template<typename Rep , typename Period >

void idfxx::i2c::master_bus::probe	(	uint16_t	address,
		const std::chrono::duration< Rep, Period > &	timeout
	)		const

inline

Probes for a device at the specified address.

Parameters

address	Device address.
timeout	Maximum time to wait for response.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if the device does not acknowledge or on error.

Definition at line 335 of file master.hpp.

References idfxx::timeout, and idfxx::unwrap().

◆ scan_devices() [1/2]

std::vector< uint8_t > idfxx::i2c::master_bus::scan_devices ( ) const

inline

Scans for devices on the bus.

Probes addresses 0x08-0x77 and returns those that acknowledge.

Returns: Addresses of responding devices.

Definition at line 298 of file master.hpp.

References idfxx::i2c::DEFAULT_TIMEOUT, and scan_devices().

Referenced by scan_devices().

◆ scan_devices() [2/2]

template<typename Rep , typename Period >

std::vector< uint8_t > idfxx::i2c::master_bus::scan_devices ( const std::chrono::duration< Rep, Period > & timeout ) const

inline

Scans for devices on the bus.

Probes addresses 0x08-0x77 and returns those that acknowledge.

Parameters

timeout Maximum time to wait for each probe.

Returns: Addresses of responding devices.

Definition at line 310 of file master.hpp.

References idfxx::timeout.

◆ try_lock()

bool idfxx::i2c::master_bus::try_lock ( ) const

inlinenoexcept

Tries to acquire exclusive access without blocking.

Definition at line 267 of file master.hpp.

◆ try_probe() [1/2]

result< void > idfxx::i2c::master_bus::try_probe ( uint16_t address ) const

inline

Probes for a device at the specified address.

Parameters

address Device address.

Returns: Success if the device acknowledges, or an error.

Definition at line 347 of file master.hpp.

References idfxx::i2c::DEFAULT_TIMEOUT, and try_probe().

Referenced by idfxx::i2c::master_device::probe(), and try_probe().

◆ try_probe() [2/2]

template<typename Rep , typename Period >

result< void > idfxx::i2c::master_bus::try_probe	(	uint16_t	address,
		const std::chrono::duration< Rep, Period > &	timeout
	)		const

inline

Probes for a device at the specified address.

Parameters

address	Device address.
timeout	Maximum time to wait for response.

Returns: Success if the device acknowledges, or an error.

Definition at line 358 of file master.hpp.

References idfxx::timeout.

◆ try_wait_all_done()

template<typename Rep , typename Period >

result< void > idfxx::i2c::master_bus::try_wait_all_done ( const std::chrono::duration< Rep, Period > & timeout ) const

inline

Waits for all pending asynchronous operations on the bus to complete.

Blocks until every queued transaction has finished or the timeout expires. Only useful when the bus was created with a non-zero trans_queue_depth.

Parameters

timeout Maximum time to wait.

Returns: Success, or an error (e.g. errc::timeout).

Definition at line 391 of file master.hpp.

References idfxx::timeout.

Referenced by wait_all_done().

◆ unlock()

void idfxx::i2c::master_bus::unlock ( ) const

inline

Releases exclusive access to the bus.

Definition at line 275 of file master.hpp.

◆ wait_all_done()

template<typename Rep , typename Period >

void idfxx::i2c::master_bus::wait_all_done ( const std::chrono::duration< Rep, Period > & timeout ) const

inline

Waits for all pending asynchronous operations on the bus to complete.

Blocks until every queued transaction has finished or the timeout expires. Only useful when the bus was created with a non-zero trans_queue_depth.

Parameters

timeout Maximum time to wait.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on timeout or failure.

Definition at line 375 of file master.hpp.

References idfxx::timeout, try_wait_all_done(), and idfxx::unwrap().

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

idfxx_i2c/include/idfxx/i2c/master.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ master_bus() [1/4]

◆ master_bus() [2/4]

◆ ~master_bus()

◆ master_bus() [3/4]

◆ master_bus() [4/4]

Member Function Documentation

◆ frequency()

◆ handle()

◆ lock()

◆ make() [1/2]

◆ make() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ port()

◆ probe() [1/2]

◆ probe() [2/2]

◆ scan_devices() [1/2]

◆ scan_devices() [2/2]

◆ try_lock()

◆ try_probe() [1/2]

◆ try_probe() [2/2]

◆ try_wait_all_done()

◆ unlock()

◆ wait_all_done()