Serial Peripheral Interface (SPI)#

Hardware Interface#

Defined in namespace hal

#include <libhal/spi.hpp>

class spi#

Serial peripheral interface (SPI) communication protocol hardware abstract interface.

Subclassed by hal::soft::inert_spi

Public Functions

inline status configure(const settings &p_settings)#

Configure spi to match the settings supplied.

Parameters:: p_settings – - settings to apply to spi
Throws:: std::errc::invalid_argument – if the settings could not be achieved.
Returns:: status - success or failure

inline result<transfer_t> transfer(std::span<const hal::byte> p_data_out, std::span<hal::byte> p_data_in, hal::byte p_filler = default_filler)#

Send and receive data between a selected device on the spi bus. This function will block until the entire transfer is finished.

Parameters:

p_data_out – - buffer to write data to the bus. If this is set to null/empty then writing is ignored and the p_filler will be written to the bus. If the length is less than p_data_in, then p_filler will be written to the bus after this buffer has been sent.
p_data_in – - buffer to read the data off of the bus. If this is null/empty, then the transfer will be write only and the incoming data will be ignored. If the length of this buffer is less than p_data_out, once this buffer has been filled, the rest of the received bytes on the bus will be dropped.
p_filler – - filler data placed on the bus in place of actual write data when p_data_out has been exhausted.

Returns:

result<transfer_t> - success or failure

Public Static Attributes

static constexpr hal::byte default_filler = hal::byte{0xFF}#: Default filler data placed on the bus in place of actual write data when the write buffer has been exhausted.

struct settings#

Generic settings for a standard SPI device.

Public Members

hertz clock_rate = 100.0_kHz#: Serial clock frequency in hertz.

bool clock_idles_high = false#: The polarity of the pins when the signal is idle.

bool data_valid_on_trailing_edge = false#: The phase of the clock signal when communicating.

struct transfer_t#

Feedback from performing a transfer on the spi bus.

This structure is currently empty as no feedback has been determined for now. This structure may be expanded in the future.

Utilities#

Defined in namespace hal

#include <libhal-util/spi.hpp>

group SPI

Functions

constexpr auto operator==(const spi::settings &p_lhs, const spi::settings &p_rhs)#

Compares two SPI objects via their settings.

Parameters:

p_lhs – A SPI object
p_rhs – A SPI object

Returns:

A boolean if they are the same or not.

inline result<hal::spi::transfer_t> write(spi &p_spi, std::span<const hal::byte> p_data_out)#

Write data to the SPI bus and ignore data sent from peripherals on the bus.

Parameters:

p_spi – - spi driver
p_data_out – - data to be written to the SPI bus

Returns:

result<hal::spi::transfer_t> - success or failure

inline result<hal::spi::transfer_t> read(spi &p_spi, std::span<hal::byte> p_data_in, hal::byte p_filler = spi::default_filler)#

Read data from the SPI bus.

Filler bytes will be placed on the write line.

Parameters:

p_spi – - spi driver
p_data_in – - buffer to receive bytes back from the SPI bus
p_filler – - filler data placed on the bus in place of actual write data.

Returns:

result<hal::spi::transfer_t> - success or failure

template<size_t BytesToRead> result<std::array<hal::byte, BytesToRead>> read(spi &p_spi, hal::byte p_filler = spi::default_filler)#

Read data from the SPI bus and return a std::array of bytes.

Filler bytes will be placed on the write line.

Template Parameters:

BytesToRead – - Number of bytes to read

Parameters:

p_spi – - spi driver
p_filler – - filler data placed on the bus in place of actual write data.

Returns:

result<std::array<hal::byte, BytesToRead>> - any errors associated with this call

inline result<hal::spi::transfer_t> write_then_read(spi &p_spi, std::span<const hal::byte> p_data_out, std::span<hal::byte> p_data_in, hal::byte p_filler = spi::default_filler)#

Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI and fill the write line with filler bytes.

This utility function that fits the use case of many SPI devices where a transaction is not full duplex. In many spi devices, full duplex means that as data is being written to the SPI bus, the peripheral device is sending data back on the read line. In most cases, the protocol is to write data to the bus, and ignore the read line because the peripheral is not writing anything meaningful to that line, then reading from SPI bus and writing nothing meaningful to the write line as the peripheral is ignoring that line.

Parameters:

p_spi – - spi driver
p_data_out – - bytes to write to the bus
p_data_in – - buffer to receive bytes back from the SPI bus
p_filler – - filler data placed on the bus when the read operation begins.

Returns:

result<hal::spi::transfer_t> - success or failure

template<size_t BytesToRead> result<std::array<hal::byte, BytesToRead>> write_then_read(spi &p_spi, std::span<const hal::byte> p_data_out, hal::byte p_filler = spi::default_filler)#

Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI, fill the write line with filler bytes and return an array of bytes.

Template Parameters:

BytesToRead – - Number of bytes to read from the bus

Parameters:

p_spi – - spi driver
p_data_out – - bytes to write to the bus
p_filler – - filler data placed on the bus when the read operation begins.

Returns:

result<std::array<hal::byte, BytesToRead>>