SPIAudioMaster Class Reference

SPI master endpoint for remote audio sink configuration and PCM data transfer. More...

#include <SPIAudioMaster.h>

Inheritance diagram for SPIAudioMaster:

Public Member Functions
	SPIAudioMaster ()=default
	Default constructor.
	SPIAudioMaster (SPIClass &spi)
	Constructor with explicit SPI bus instance.
virtual void	addNotifyAudioChange (AudioInfoSupport &bi)
	Adds target to be notified about audio changes.
virtual AudioInfo	audioInfo () override
	provides the actual input AudioInfo
virtual AudioInfo	audioInfoOut ()
int	available ()
	Queries how many bytes are currently filled/readable in the remote buffer.
int	availableForWrite ()
	Returns writable bytes on the remote side.
virtual bool	begin ()
virtual bool	begin (AudioInfo info)
bool	begin (SPIAudioMasterConfig cfg=SPIAudioMasterConfig())
	Initializes SPI and stores the master configuration.
bool	clear ()
	Clears the remote audio buffer.
virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.
void	end ()
	Stops the master and closes the SPI bus.
virtual void	flush ()
bool	isActive () const
	Returns true when the master is active.
virtual bool	isDeletable ()
	If true we need to release the related memory in the destructor.
bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.
virtual	operator bool ()
virtual bool	removeNotifyAudioChange (AudioInfoSupport &bi)
	Removes a target in order not to be notified about audio changes.
void	setAudioInfo (AudioInfo info) override
	Sends audio format information to the remote slave.
bool	setMime (const char *mime)
	Set stream mime type (e.g. "audio/wav", "audio/mp3")
void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)
size_t	write (const uint8_t *data, size_t len)
	Writes audio bytes in chunks using WriteData command.
virtual size_t	write (uint8_t ch) override
virtual void	writeSilence (size_t len)

Protected Member Functions
uint32_t	getAvailableBufferSize ()
	Queries available space in the remote buffer in bytes.
uint32_t	getFilledBufferSize ()
	Queries how many bytes are filled/readable in the remote buffer.
void	notifyAudioChange (AudioInfo info)
bool	sendCommand (SPIAudioCommand command, const uint8_t *payload, uint16_t payload_len, uint8_t *response, uint16_t *response_len)
	Sends a protocol command and reads the optional response.
uint16_t	transferU16LE (uint16_t value)
	Transfers and/or receives a 16-bit little-endian value over SPI.

Static Protected Member Functions
static uint32_t	readU32LE (const uint8_t *in)
	Reads a 32-bit little-endian integer from the source buffer.
static void	writeU32LE (uint8_t *out, uint32_t value)
	Writes a 32-bit little-endian integer to the target buffer.

Protected Attributes
int	_timeout = 10
bool	active = false
int	buffer_size = 0
AudioInfo	cfg
SPIAudioMasterConfig	config
bool	is_active = false
bool	is_notify_active = true
Vector< AudioInfoSupport * >	notify_vector
SPIClass *	p_spi = nullptr
SingleBuffer< uint8_t >	tmp {MAX_SINGLE_CHARS}
int	tmpPos = 0

Detailed Description

SPI master endpoint for remote audio sink configuration and PCM data transfer.

This class implements the master side of a simple binary request/response protocol over SPI and is designed to work with SPIAudioSlave.

Protocol Overview

SPIAudioMaster provides a lightweight binary protocol for controlling a remote audio sink and streaming PCM data over SPI. The protocol is request/response based; the master initiates all transactions and waits for slave responses.

Supported Commands

• SetMime: Configure remote MIME type (e.g., "audio/wav", "audio/mp3"). Helps the slave understand the audio format context.
• SetAudioInfo: Atomically set sample rate (Hz), channel count, and bits per sample in a single command. Preferred over separate format commands.
• WriteData: Stream raw PCM payload bytes to the remote input buffer. Respects remote buffer availability and configured max_payload size.
• GetAvailableBufferSize: Query free space in the remote buffer (bytes). Enables flow control to prevent remote buffer overflow.
• GetFilledBufferSize: Query how many bytes are currently buffered on the remote side and ready to be consumed. Useful for monitoring latency.
• Clear: Reset the remote buffer (useful for state recovery).

Wire Format

Request frame: cmd(1) + payload_len(2 LE) + payload(0..65535) Response frame: status(1) + response_len(2 LE) + response(0..65535)

All multi-byte integers are little-endian. Payload length is uint16_t, allowing up to 64KB payloads per command.

Flow Control

The master supports two write modes via is_blocking_write:

• is_blocking_write=false (default): Non-blocking writes. write() sends only the bytes that currently fit into the remote buffer and returns immediately.
• is_blocking_write=true: Blocking writes. write() waits until enough remote space is available for one chunk and then sends that chunk in a single SPI command.

Status Codes

Responses include status byte:

• 0: Ok (command executed successfully)
• 1: InvalidCommand (slave doesn't recognize command)
• 2: InvalidPayload (payload length or format incorrect)
• 3: BufferOverflow (slave buffer full, write rejected)
• 4: InternalError (slave-side error)

SPI Configuration

Configure SPI bus settings via SPIAudioMasterConfig:

• cs_pin: Chip select GPIO (defaults to SS if defined, else 10). Set to -1 to disable manual CS handling (external or hardware-controlled CS).
• clock_hz: SPI clock frequency (default 8 MHz)
• bit_order: MSBFIRST or LSBFIRST (default MSBFIRST)
• data_mode: SPI_MODE0..SPI_MODE3 (default SPI_MODE0)
• max_payload: Max bytes per WriteData command (default 1024)
• is_blocking_write: Enable blocking write mode (default false)

Typical Usage

SPIAudioMaster master;
SPIAudioMasterConfig cfg;
cfg.sample_rate = 48000;
cfg.channels = 2;
cfg.bits_per_sample = 16;
cfg.clock_hz = 10000000;  // 10 MHz SPI clock
master.begin(cfg);
 
master.setMime("audio/wav");
master.setAudioInfo(cfg);  // Sync format to slave
 
// Stream audio data
while (audio_available) {
    size_t sent = master.write(audio_buffer, chunk_size);
}
 
master.end();

Performance Notes

• Each command triggers a full SPI transaction (multiple CS toggles).
• Minimize SetAudioInfo/SetMime calls after initialization.
• Use large max_payload to reduce command overhead (if slave buffer allows).
• Batch small audio chunks to fill max_payload per WriteData command.

Constructor & Destructor Documentation

SPIAudioMaster() [1/2]

SPIAudioMaster ( )

default

Default constructor.

SPIAudioMaster() [2/2]

SPIAudioMaster ( SPIClass &  spi )

inlineexplicit

Constructor with explicit SPI bus instance.

Member Function Documentation

addNotifyAudioChange()

virtual void addNotifyAudioChange ( AudioInfoSupport &  bi )

inlinevirtualinherited

Adds target to be notified about audio changes.

Reimplemented in CodecNOP, EncodedAudioOutput, EncodedAudioStream, AACDecoderFDK, DecoderBasic, CodecChain, MP3DecoderHelix, MP3DecoderMAD, OggContainerDecoder, RTSPClient< TcpClient, UdpSocket >, Pipeline, and Pipeline::ModifyingStreamAdapter.

audioInfo()

virtual AudioInfo audioInfo ( )

inlineoverridevirtualinherited

provides the actual input AudioInfo

Implements AudioInfoSupport.

Reimplemented in AdapterPrintToAudioOutput, EncodedAudioOutput, and AdapterAudioStreamToAudioOutput.

audioInfoOut()

virtual AudioInfo audioInfoOut ( )

inlinevirtualinherited

provides the actual output AudioInfo: this is usually the same as audioInfo() unless we use a transforming stream

Reimplemented in PureDataStream, PWMAudioOutput, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

available()

int available ( )

inline

Queries how many bytes are currently filled/readable in the remote buffer.

availableForWrite()

int availableForWrite ( )

inlinevirtual

Returns writable bytes on the remote side.

Reimplemented from AudioOutput.

begin() [1/3]

virtual bool begin ( )

inlinevirtualinherited

Reimplemented in OSCContainerEncoder::OSCOutput, AudioOutputWithCallback, AudioServerEx, RTSPOutput< Platform >, PitchShiftOutput< T, BufferT >, PWMAudioOutput, RTTTLOutput< T >, EncodedAudioOutput, OggContainerOutput, FFTEffect, FFTPitchShift, R2ROutput, AdapterAudioStreamToAudioOutput, ChannelsSelectOutput, MetaDataFilter, CsvOutput< T >, HexDumpOutput, MemoryOutput, and RTTTLOutput< T >.

begin() [2/3]

virtual bool begin ( AudioInfo  info )

inlinevirtualinherited

Reimplemented in AudioESP32ULP, RTSPOutput< Platform >, RTTTLOutput< T >, ChannelsSelectOutput, CsvOutput< T >, and EncodedAudioOutput.

begin() [3/3]

bool begin ( SPIAudioMasterConfig  cfg = SPIAudioMasterConfig() )

inline

Initializes SPI and stores the master configuration.

clear()

bool clear ( )

inline

Clears the remote audio buffer.

clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

end()

void end ( )

inlinevirtual

Stops the master and closes the SPI bus.

Reimplemented from AudioOutput.

flush()

virtual void flush ( )

inlinevirtualinherited

Reimplemented from Print.

Reimplemented in MultiOutput, and HexDumpOutput.

getAvailableBufferSize()

uint32_t getAvailableBufferSize ( )

inlineprotected

Queries available space in the remote buffer in bytes.

getFilledBufferSize()

uint32_t getFilledBufferSize ( )

inlineprotected

Queries how many bytes are filled/readable in the remote buffer.

isActive()

bool isActive ( ) const

inline

Returns true when the master is active.

isDeletable()

virtual bool isDeletable ( )

inlinevirtualinherited

If true we need to release the related memory in the destructor.

Reimplemented in AdapterPrintToAudioOutput, and AdapterAudioStreamToAudioOutput.

isNotifyActive()

bool isNotifyActive ( )

inlineinherited

Checks if the automatic AudioInfo update is active.

notifyAudioChange()

void notifyAudioChange ( AudioInfo  info )

inlineprotectedinherited

operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in RTSPOutput< Platform >, EncodedAudioOutput, and AdapterAudioStreamToAudioOutput.

readU32LE()

static uint32_t readU32LE ( const uint8_t *  in )

inlinestaticprotected

Reads a 32-bit little-endian integer from the source buffer.

removeNotifyAudioChange()

virtual bool removeNotifyAudioChange ( AudioInfoSupport &  bi )

inlinevirtualinherited

Removes a target in order not to be notified about audio changes.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

sendCommand()

bool sendCommand ( SPIAudioCommand  command, const uint8_t *  payload, uint16_t  payload_len, uint8_t *  response, uint16_t *  response_len  )

inlineprotected

Sends a protocol command and reads the optional response.

setAudioInfo()

void setAudioInfo ( AudioInfo  info )

inlineoverridevirtual

Sends audio format information to the remote slave.

Reimplemented from AudioOutput.

setMime()

bool setMime ( const char *  mime )

inline

Set stream mime type (e.g. "audio/wav", "audio/mp3")

setNotifyActive()

void setNotifyActive ( bool  flag )

inlineinherited

Deactivate/Reactivate automatic AudioInfo updates: (default is active)

transferU16LE()

uint16_t transferU16LE ( uint16_t  value )

inlineprotected

Transfers and/or receives a 16-bit little-endian value over SPI.

write() [1/2]

size_t write ( const uint8_t *  data, size_t  len  )

inlinevirtual

Writes audio bytes in chunks using WriteData command.

Implements AudioOutput.

write() [2/2]

virtual size_t write ( uint8_t  ch )

inlineoverridevirtualinherited

Reimplemented in MetaDataOutput, and MultiOutput.

writeSilence()

virtual void writeSilence ( size_t  len )

inlinevirtualinherited

Writes n 0 values (= silence)

Parameters

len

writeU32LE()

static void writeU32LE ( uint8_t *  out, uint32_t  value  )

inlinestaticprotected

Writes a 32-bit little-endian integer to the target buffer.

Member Data Documentation

_timeout

int _timeout = 10

protectedinherited

active

bool active = false

protected

buffer_size

int buffer_size = 0

protected

cfg

AudioInfo cfg

protectedinherited

config

SPIAudioMasterConfig config

protected

is_active

bool is_active = false

protectedinherited

is_notify_active

bool is_notify_active = true

protectedinherited

notify_vector

Vector<AudioInfoSupport*> notify_vector

protectedinherited

p_spi

SPIClass* p_spi = nullptr

protected

tmp

SingleBuffer<uint8_t> tmp {MAX_SINGLE_CHARS}

protectedinherited

tmpPos

int tmpPos = 0

protectedinherited

---

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

• src/AudioTools/Communication/SPI/SPIAudioMaster.h