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.

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 110 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 246 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 240 of file master.hpp.

◆ lock()

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

inline

Acquires exclusive access to the bus.

Definition at line 216 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 243 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 280 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 292 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 255 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 267 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 224 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 304 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 315 of file master.hpp.

References idfxx::timeout.

◆ unlock()

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

inline

Releases exclusive access to the bus.

Definition at line 232 of file master.hpp.

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]

◆ unlock()