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 the SPI bus for this device.

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

void	unlock () const
	Releases exclusive bus access.

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.

The blocking APIs are thread-safe and may be called concurrently from multiple tasks. The polling APIs are NOT thread-safe — acquire exclusive bus access via lock() (or a std::lock_guard) before calling them.

Satisfies the Lockable named requirement, so it can be used directly with std::lock_guard and similar standard RAII wrappers.

This type is non-copyable and move-only. The caller must ensure the parent master_bus outlives this device.

Definition at line 332 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 422 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 428 of file master.hpp.

◆ lock()

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

Acquires exclusive access to the SPI bus for this device.

While the bus is acquired, transactions to all other devices on the same bus are deferred. Blocks indefinitely.

◆ 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: Not thread-safe. Call lock() or use std::lock_guard first.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 607 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: Not thread-safe. Call lock() or use std::lock_guard first.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 594 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: Not thread-safe. Call lock() or use std::lock_guard first.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 619 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: Not thread-safe. Call lock() or use std::lock_guard first.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 632 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: Not thread-safe. Call lock() or use std::lock_guard first.; Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 583 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 718 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 735 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 485 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 469 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 502 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 557 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 459 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 bus access without blocking.

Returns: true if the bus was 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: Not thread-safe. Call lock() or use std::lock_guard first.

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: Not thread-safe. Call lock() or use std::lock_guard first.

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: Not thread-safe. Call lock() or use std::lock_guard first.

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: Not thread-safe. Call lock() or use std::lock_guard first.

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: Not thread-safe. Call lock() or use std::lock_guard first.

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 771 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 bus access.

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()