A device on a SPI master bus. More...

Classes
struct	config
	SPI device configuration. More...

Public Member Functions
	master_device (master_bus &bus, const struct config &config)
	Creates a new SPI device on the specified bus.

	~master_device ()

	master_device (const master_device &)=delete

master_device &	operator= (const master_device &)=delete

	master_device (master_device &&other) noexcept

master_device &	operator= (master_device &&other) noexcept

master_bus &	bus () const
	Returns the parent bus.

spi_device_handle_t	idf_handle () const
	Returns the underlying ESP-IDF device handle.

freq::hertz	frequency () const
	Returns the actual clock frequency in use.

void	transmit (std::span< const uint8_t > tx_data)
	Transmits data to the device.

void	receive (std::span< uint8_t > rx_data)
	Receives data from the device into the provided buffer.

std::vector< uint8_t >	receive (size_t size)
	Receives data from the device.

void	transfer (std::span< const uint8_t > tx_data, std::span< uint8_t > rx_data)
	Performs a full-duplex transfer.

result< void >	try_transmit (std::span< const uint8_t > tx_data)
	Transmits data to the device.

result< void >	try_receive (std::span< uint8_t > rx_data)
	Receives data from the device into the provided buffer.

result< std::vector< uint8_t > >	try_receive (size_t size)
	Receives data from the device.

result< void >	try_transfer (std::span< const uint8_t > tx_data, std::span< uint8_t > rx_data)
	Performs a full-duplex transfer.

void	transmit (const transaction &trans)
	Executes a full-control transaction.

result< void >	try_transmit (const transaction &trans)
	Executes a full-control transaction.

void	polling_transmit (std::span< const uint8_t > tx_data)
	Transmits data using polling (busy-wait).

void	polling_receive (std::span< uint8_t > rx_data)
	Receives data using polling (busy-wait).

std::vector< uint8_t >	polling_receive (size_t size)
	Receives data using polling (busy-wait).

void	polling_transfer (std::span< const uint8_t > tx_data, std::span< uint8_t > rx_data)
	Performs a full-duplex transfer using polling (busy-wait).

void	polling_transmit (const transaction &trans)
	Executes a full-control transaction using polling (busy-wait).

result< void >	try_polling_transmit (std::span< const uint8_t > tx_data)
	Transmits data using polling (busy-wait).

result< void >	try_polling_receive (std::span< uint8_t > rx_data)
	Receives data using polling (busy-wait).

result< std::vector< uint8_t > >	try_polling_receive (size_t size)
	Receives data using polling (busy-wait).

result< void >	try_polling_transfer (std::span< const uint8_t > tx_data, std::span< uint8_t > rx_data)
	Performs a full-duplex transfer using polling (busy-wait).

result< void >	try_polling_transmit (const transaction &trans)
	Executes a full-control transaction using polling (busy-wait).

idfxx::future< void >	queue_trans (const transaction &trans)
	Queues a transaction for asynchronous execution.

template<typename Rep , typename Period >
idfxx::future< void >	queue_trans (const transaction &trans, const std::chrono::duration< Rep, Period > &timeout)
	Queues a transaction for asynchronous execution with timeout.

result< idfxx::future< void > >	try_queue_trans (const transaction &trans)
	Queues a transaction for asynchronous execution.

template<typename Rep , typename Period >
result< idfxx::future< void > >	try_queue_trans (const transaction &trans, const std::chrono::duration< Rep, Period > &timeout)
	Queues a transaction for asynchronous execution with timeout.

void	lock () const
	Acquires exclusive access to this device and its bus.

bool	try_lock () const noexcept
	Tries to acquire exclusive access without waiting for the device.

void	unlock () const
	Releases exclusive access acquired by lock() or try_lock().

Static Public Member Functions
static result< master_device >	make (master_bus &bus, const struct config &config)
	Creates a new SPI device on the specified bus.

Detailed Description

A device on a SPI master bus.

Represents a device attached to a SPI bus. Provides byte-oriented transmit/receive helpers, a full-control transaction API, a polling (busy-wait) variant for low-latency transfers, and an asynchronous queue API for overlapping transfers with other work.

All transaction APIs are thread-safe and may be called concurrently from multiple tasks; individual polling calls are serialized against each other and against lock(). To keep a multi-transaction sequence atomic, hold the device lock (e.g. via std::lock_guard) across the sequence.

Satisfies the Lockable named requirement, so it can be used directly with std::lock_guard and similar standard RAII wrappers. Locking provides mutual exclusion between threads sharing this device and holds exclusive access to the underlying bus for the duration. The lock is recursive: a thread may re-lock a device it already holds.

This type is non-copyable and move-only. The caller must ensure the parent master_bus outlives this device. A moved-from object must not be used: any operation other than destruction or assignment is undefined behavior.

Definition at line 340 of file master.hpp.

Constructor & Destructor Documentation

◆ master_device() [1/3]

idfxx::spi::master_device::master_device	(	master_bus &	bus,
		const struct config &	config
	)

explicit

Creates a new SPI device on the specified bus.

Does not take ownership of bus. The caller must ensure that this device does not outlive the bus.

Parameters

bus	The parent SPI master bus.
config	Device configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

spi::master_device device(bus, {
    .mode = 0,
    .clock_speed = 1_MHz,
    .cs = idfxx::gpio_5,
});

◆ ~master_device()

idfxx::spi::master_device::~master_device ( )

◆ master_device() [2/3]

idfxx::spi::master_device::master_device ( const master_device & )

delete

◆ master_device() [3/3]

idfxx::spi::master_device::master_device ( master_device && other )

noexcept

Member Function Documentation

◆ bus()

master_bus & idfxx::spi::master_device::bus ( ) const

inline

Returns the parent bus.

Precondition: The object has not been moved from.

Definition at line 430 of file master.hpp.

◆ frequency()

freq::hertz idfxx::spi::master_device::frequency ( ) const

Returns the actual clock frequency in use.

The requested config::clock_speed may not always be exactly achievable; this returns the closest frequency the hardware is running at.

Returns: The actual frequency in Hz.

◆ idf_handle()

spi_device_handle_t idfxx::spi::master_device::idf_handle ( ) const

inline

Returns the underlying ESP-IDF device handle.

Definition at line 436 of file master.hpp.

◆ lock()

void idfxx::spi::master_device::lock ( ) const

Acquires exclusive access to this device and its bus.

Provides mutual exclusion against other threads locking or issuing polling transactions on this device. While the lock is held, transactions to all other devices on the same bus are also deferred. Blocks indefinitely until the device and bus are available.

The lock is recursive: a thread may lock a device it already holds. Each lock() must be balanced by a matching unlock().

Exceptions

std::system_error if the driver rejects bus acquisition (only possible when a polling transaction was started through the raw idf_handle(), bypassing this API). When CONFIG_COMPILER_CXX_EXCEPTIONS is disabled, this aborts instead.

std::lock_guard lk(device);
device.polling_transmit(cmd);
device.polling_receive(response);

◆ make()

static result< master_device > idfxx::spi::master_device::make	(	master_bus &	bus,
		const struct config &	config
	)

static

Creates a new SPI device on the specified bus.

Does not take ownership of bus. The caller must ensure that this device does not outlive the bus.

Parameters

bus	The parent SPI master bus.
config	Device configuration.

Returns: The new master_device, or an error.

auto device = spi::master_device::make(bus, {
    .mode = 0,
    .clock_speed = 1_MHz,
    .cs = idfxx::gpio_5,
});

◆ operator=() [1/2]

master_device & idfxx::spi::master_device::operator= ( const master_device & )

delete

◆ operator=() [2/2]

master_device & idfxx::spi::master_device::operator= ( master_device && other )

noexcept

◆ polling_receive() [1/2]

std::vector< uint8_t > idfxx::spi::master_device::polling_receive ( size_t size )

inline

Receives data using polling (busy-wait).

Parameters

size	Number of bytes to receive.

Returns: Received data.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 618 of file master.hpp.

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

◆ polling_receive() [2/2]

void idfxx::spi::master_device::polling_receive ( std::span< uint8_t > rx_data )

inline

Receives data using polling (busy-wait).

Parameters

rx_data Buffer to receive into.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 604 of file master.hpp.

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

◆ polling_transfer()

void idfxx::spi::master_device::polling_transfer	(	std::span< const uint8_t >	tx_data,
		std::span< uint8_t >	rx_data
	)

inline

Performs a full-duplex transfer using polling (busy-wait).

Parameters

tx_data	Data to transmit.
rx_data	Buffer for received data (must be same size as tx_data).

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 631 of file master.hpp.

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

◆ polling_transmit() [1/2]

void idfxx::spi::master_device::polling_transmit ( const transaction & trans )

inline

Executes a full-control transaction using polling (busy-wait).

Parameters

trans Transaction descriptor (lengths in bits).

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 645 of file master.hpp.

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

◆ polling_transmit() [2/2]

void idfxx::spi::master_device::polling_transmit ( std::span< const uint8_t > tx_data )

inline

Transmits data using polling (busy-wait).

Parameters

tx_data Data to transmit.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 592 of file master.hpp.

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

◆ queue_trans() [1/2]

idfxx::future< void > idfxx::spi::master_device::queue_trans ( const transaction & trans )

inline

Queues a transaction for asynchronous execution.

Submits trans to the device and returns a future that signals completion. Blocks indefinitely if the device's transaction queue is full; the queue depth is set by config::queue_size.

Parameters

trans Transaction descriptor.

Returns: A future tracking the queued transaction.

Note: The transaction value itself may be dropped or reused once this call returns; the buffers it references must remain valid until the returned future signals completion.; The parent master_device must outlive every future it produces.; Dropping an in-flight future (without waiting) is safe. The transaction continues to occupy a queue slot until a later wait() call drains it or the device is destroyed, which may cause subsequent queue_trans() calls to block if the queue fills up.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 736 of file master.hpp.

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

◆ queue_trans() [2/2]

template<typename Rep , typename Period >

idfxx::future< void > idfxx::spi::master_device::queue_trans	(	const transaction &	trans,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Queues a transaction for asynchronous execution with timeout.

Template Parameters

Rep	Duration arithmetic type.
Period	Duration period type.

Parameters

trans	Transaction descriptor.
timeout	Maximum time to wait for space in the transaction queue.

Returns: A future tracking the queued transaction.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure or timeout.

Definition at line 753 of file master.hpp.

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

◆ receive() [1/2]

std::vector< uint8_t > idfxx::spi::master_device::receive ( size_t size )

inline

Receives data from the device.

Parameters

size	Number of bytes to receive.

Returns: Received data.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

auto data = device.receive(4);

Definition at line 493 of file master.hpp.

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

◆ receive() [2/2]

void idfxx::spi::master_device::receive ( std::span< uint8_t > rx_data )

inline

Receives data from the device into the provided buffer.

Parameters

rx_data Buffer to receive into.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 477 of file master.hpp.

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

◆ transfer()

void idfxx::spi::master_device::transfer	(	std::span< const uint8_t >	tx_data,
		std::span< uint8_t >	rx_data
	)

inline

Performs a full-duplex transfer.

Parameters

tx_data	Data to transmit.
rx_data	Buffer for received data (must be same size as tx_data).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

std::array<uint8_t, 4> tx = {0x01, 0x02, 0x03, 0x04};
std::array<uint8_t, 4> rx;
device.transfer(tx, rx);

Definition at line 510 of file master.hpp.

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

◆ transmit() [1/2]

void idfxx::spi::master_device::transmit ( const transaction & trans )

inline

Executes a full-control transaction.

Parameters

trans Transaction descriptor (lengths in bits).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 565 of file master.hpp.

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

◆ transmit() [2/2]

void idfxx::spi::master_device::transmit ( std::span< const uint8_t > tx_data )

inline

Transmits data to the device.

Parameters

tx_data Data to transmit.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

std::array<uint8_t, 4> data = {0x01, 0x02, 0x03, 0x04};

device.transmit(data);

Definition at line 467 of file master.hpp.

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

◆ try_lock()

bool idfxx::spi::master_device::try_lock ( ) const

noexcept

Tries to acquire exclusive access without waiting for the device.

Returns false immediately if another thread holds the device lock. On success, exclusive bus access is also acquired, which may briefly block while in-flight transactions of other devices on the bus complete.

Returns: true if the device and bus were acquired, false otherwise.

◆ try_polling_receive() [1/2]

result< std::vector< uint8_t > > idfxx::spi::master_device::try_polling_receive ( size_t size )

Receives data using polling (busy-wait).

Parameters

size	Number of bytes to receive.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.

Returns: Received data, or an error.

◆ try_polling_receive() [2/2]

result< void > idfxx::spi::master_device::try_polling_receive ( std::span< uint8_t > rx_data )

Receives data using polling (busy-wait).

Parameters

rx_data Buffer to receive into.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.

Returns: Success, or an error.

Referenced by polling_receive(), and polling_receive().

◆ try_polling_transfer()

result< void > idfxx::spi::master_device::try_polling_transfer	(	std::span< const uint8_t >	tx_data,
		std::span< uint8_t >	rx_data
	)

Performs a full-duplex transfer using polling (busy-wait).

Parameters

tx_data	Data to transmit.
rx_data	Buffer for received data (must be same size as tx_data).

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.

Returns: Success, or an error.

Referenced by polling_transfer().

◆ try_polling_transmit() [1/2]

result< void > idfxx::spi::master_device::try_polling_transmit ( const transaction & trans )

Executes a full-control transaction using polling (busy-wait).

Parameters

trans Transaction descriptor (lengths in bits).

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.

Returns: Success, or an error.

◆ try_polling_transmit() [2/2]

result< void > idfxx::spi::master_device::try_polling_transmit ( std::span< const uint8_t > tx_data )

Transmits data using polling (busy-wait).

Parameters

tx_data Data to transmit.

Note: Serialized against other polling calls and lock(). Hold the device lock across multi-transaction sequences that must be atomic.

Returns: Success, or an error.

Referenced by polling_transmit(), and polling_transmit().

◆ try_queue_trans() [1/2]

result< idfxx::future< void > > idfxx::spi::master_device::try_queue_trans ( const transaction & trans )

Queues a transaction for asynchronous execution.

Submits trans to the device and returns a future that signals completion. Blocks indefinitely if the device's transaction queue is full; the queue depth is set by config::queue_size.

Parameters

trans Transaction descriptor.

Returns: A future tracking the queued transaction, or an error.

Note: The transaction value itself may be dropped or reused once this call returns; the buffers it references must remain valid until the returned future signals completion.; The parent master_device must outlive every future it produces.

Referenced by queue_trans(), and queue_trans().

◆ try_queue_trans() [2/2]

template<typename Rep , typename Period >

result< idfxx::future< void > > idfxx::spi::master_device::try_queue_trans	(	const transaction &	trans,
		const std::chrono::duration< Rep, Period > &	timeout
	)

inline

Queues a transaction for asynchronous execution with timeout.

Template Parameters

Rep	Duration arithmetic type.
Period	Duration period type.

Parameters

trans	Transaction descriptor.
timeout	Maximum time to wait for space in the transaction queue.

Returns: A future tracking the queued transaction, or an error.

Definition at line 789 of file master.hpp.

References idfxx::timeout.

◆ try_receive() [1/2]

result< std::vector< uint8_t > > idfxx::spi::master_device::try_receive ( size_t size )

Receives data from the device.

Parameters

size	Number of bytes to receive.

Returns: Received data, or an error.

◆ try_receive() [2/2]

result< void > idfxx::spi::master_device::try_receive ( std::span< uint8_t > rx_data )

Receives data from the device into the provided buffer.

Parameters

rx_data Buffer to receive into.

Returns: Success, or an error.

Referenced by receive(), and receive().

◆ try_transfer()

result< void > idfxx::spi::master_device::try_transfer	(	std::span< const uint8_t >	tx_data,
		std::span< uint8_t >	rx_data
	)

Performs a full-duplex transfer.

Parameters

tx_data	Data to transmit.
rx_data	Buffer for received data (must be same size as tx_data).

Returns: Success, or an error.

Referenced by transfer().

◆ try_transmit() [1/2]

result< void > idfxx::spi::master_device::try_transmit ( const transaction & trans )

Executes a full-control transaction.

Parameters

trans Transaction descriptor (lengths in bits).

Returns: Success, or an error.

◆ try_transmit() [2/2]

result< void > idfxx::spi::master_device::try_transmit ( std::span< const uint8_t > tx_data )

Transmits data to the device.

Parameters

tx_data Data to transmit.

Returns: Success, or an error.

Referenced by transmit(), and transmit().

◆ unlock()

void idfxx::spi::master_device::unlock ( ) const

Releases exclusive access acquired by lock() or try_lock().

Bus access is released when the outermost recursive lock is unlocked.

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

idfxx_spi/include/idfxx/spi/master.hpp

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ master_device() [1/3]

◆ ~master_device()

◆ master_device() [2/3]

◆ master_device() [3/3]

Member Function Documentation

◆ bus()

◆ frequency()

◆ idf_handle()

◆ lock()

◆ make()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ polling_receive() [1/2]

◆ polling_receive() [2/2]

◆ polling_transfer()

◆ polling_transmit() [1/2]

◆ polling_transmit() [2/2]

◆ queue_trans() [1/2]

◆ queue_trans() [2/2]

◆ receive() [1/2]

◆ receive() [2/2]

◆ transfer()

◆ transmit() [1/2]

◆ transmit() [2/2]

◆ try_lock()

◆ try_polling_receive() [1/2]

◆ try_polling_receive() [2/2]

◆ try_polling_transfer()

◆ try_polling_transmit() [1/2]

◆ try_polling_transmit() [2/2]

◆ try_queue_trans() [1/2]

◆ try_queue_trans() [2/2]

◆ try_receive() [1/2]

◆ try_receive() [2/2]

◆ try_transfer()

◆ try_transmit() [1/2]

◆ try_transmit() [2/2]

◆ unlock()