AudioLoRa Class Reference

Sends and receives audio over a LoRa radio link (via the sandeepmistry/arduino-LoRa library) as a regular AudioTools Stream, so it can be dropped into a StreamCopy pipeline like any other audio source/sink – e.g. StreamCopy(audioLoRa, i2sMic) to transmit, or StreamCopy(i2sSpeaker, audioLoRa) to receive. See AudioLoRaConfig's documentation first for why, even with its audio-tuned defaults, this only works at all in a narrow envelope (very low bitrate, short clips/bursts). More...

#include <AudioLoRa.h>

Inheritance diagram for AudioLoRa:

Public Member Functions
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 ()
int	availableForWrite ()
bool	begin ()
bool	begin (AudioLoRaConfig config)
virtual void	clearNotifyAudioChange ()
	Deletes all change notify subscriptions.
AudioLoRaConfig	defaultConfig ()
void	end ()
virtual void	flush () override
bool	isNotifyActive ()
	Checks if the automatic AudioInfo update is active.
virtual	operator bool ()
size_t	readBytes (uint8_t *data, size_t len)
virtual size_t	readSilence (uint8_t *buffer, size_t length)
	Source to generate silence: just sets the buffer to 0.
virtual bool	removeNotifyAudioChange (AudioInfoSupport &bi)
	Removes a target in order not to be notified about audio changes.
void	setAudioInfo (AudioInfo info)
	Defines the input AudioInfo.
void	setNotifyActive (bool flag)
	Deactivate/Reactivate automatic AudioInfo updates: (default is active)
void	setWriteBufferSize (int size)
size_t	write (const uint8_t *data, size_t len)
virtual size_t	write (uint8_t ch) override
virtual void	writeSilence (size_t len)
	Writes len bytes of silence (=0).

Protected Member Functions
virtual int	not_supported (int out, const char *msg="")
void	notifyAudioChange (AudioInfo info)
void	readAudioInfo ()
void	refillReadBuffer ()
	Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read()
void	writeAudioInfo ()

Protected Attributes
int	_timeout = 10
SingleBuffer< uint8_t >	buffer
AudioLoRaConfig	cfg
AudioInfo	info
bool	is_notify_active = true
Vector< AudioInfoSupport * >	notify_vector
RingBuffer< uint8_t >	tmp_in {0}
RingBuffer< uint8_t >	tmp_out {0}
int	write_buffer_size = MAX_SINGLE_CHARS

Detailed Description

Sends and receives audio over a LoRa radio link (via the sandeepmistry/arduino-LoRa library) as a regular AudioTools Stream, so it can be dropped into a StreamCopy pipeline like any other audio source/sink – e.g. StreamCopy(audioLoRa, i2sMic) to transmit, or StreamCopy(i2sSpeaker, audioLoRa) to receive. See AudioLoRaConfig's documentation first for why, even with its audio-tuned defaults, this only works at all in a narrow envelope (very low bitrate, short clips/bursts).

Wire protocol: if cfg.process_audio_info is set (the default), begin() sends a single LoRa packet containing a raw AudioInfo struct (sample rate/channels/bits) right away, so a receiver can learn the format instead of needing it configured out of band. From then on, write() appends audio bytes to an internal buffer and transmits one LoRa packet each time it fills to cfg.max_size. On the receiving side, readBytes() checks each incoming packet's size and, whenever it matches sizeof(AudioInfo), decodes it as a header via setAudioInfo() instead of returning it as audio payload.

Known limitations (review notes, not yet fixed):

• The header is sent exactly once, synchronously inside begin(), with no retry or periodic re-announcement. If the receiving side hasn't called its own begin() yet at that exact moment – a likely race when two independently-powered boards start up – that one packet is simply gone, and the receiver never learns the audio format. Consider calling begin() on the receiver well before the transmitter, or configuring both sides identically and setting process_audio_info = false to skip the handshake entirely.
• readBytes()'s header check is driven by the process_audio_info setting, not by whether a header has already been received – so it keeps reinterpreting any packet of exactly sizeof(AudioInfo) bytes as a fresh header for the life of the stream. With the default max_size = 200, ordinary audio packets are always ~200 bytes so this is unlikely to misfire in practice, but it becomes a real risk if max_size is ever configured close to sizeof(AudioInfo).
• begin() calls LoRa.begin(cfg.frequency) exactly once; if the radio isn't ready yet it fails immediately rather than retrying.
• available()/availableForWrite() always return cfg.max_size, a constant, rather than reflecting whether a packet has actually arrived or whether the radio is free.
• write() only flushes once its buffer is exactly full; any partial buffer content left over when the stream ends is never sent (no flush(), and end() does not drain it), so trailing audio can be lost.
• LoRa itself provides no retransmission/ACK for these packets, so a lost or corrupted packet is simply missing audio (an audible gap), with no recovery built in here.
• Requires the external, separately-installed sandeepmistry/arduino-LoRa library and matching transceiver hardware (e.g. an SX127x module); this header also defines ss/rst/dio0 as short, generic macros in the global namespace – ss in particular (a very common local variable name, e.g. std::stringstream ss) is likely to collide with unrelated code that includes this header.

Note

Supported only on Arduino platforms with LoRa support (e.g. ESP32) and the LoRa library!

Requires: 👉 https://github.com/sandeepmistry/arduino-LoRa

Author

Phil Schatzmann

Copyright

GPLv3

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 JupyterAudioT< T >, MozziStream, TimerCallbackAudioStream, EncodedAudioStream, PureDataStream, AdapterAudioOutputToAudioStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and InputMerge< T >.

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 MP3EncoderShine, PureDataStream, PWMAudioOutput< PWMDriverT >, ChannelFormatConverterStreamT< T >, ChannelFormatConverterStream, NumberFormatConverterStreamT< TFrom, TTo >, NumberFormatConverterStream, FormatConverterStream, Pipeline, ResampleStream, and ResampleStreamT< TInterpolator >.

available()

int available ( )

inlinevirtual

Reimplemented from BaseStream.

availableForWrite()

int availableForWrite ( )

inlinevirtual

Reimplemented from BaseStream.

begin() [1/2]

bool begin ( )

inlinevirtual

Reimplemented from BaseStream.

begin() [2/2]

bool begin ( AudioLoRaConfig  config )

inline

clearNotifyAudioChange()

virtual void clearNotifyAudioChange ( )

inlinevirtualinherited

Deletes all change notify subscriptions.

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

defaultConfig()

AudioLoRaConfig defaultConfig ( )

inline

end()

void end ( )

inlinevirtual

Reimplemented from BaseStream.

flush()

virtual void flush ( )

inlineoverridevirtualinherited

Reimplemented from Print.

Reimplemented in PureDataStream, URLStreamBufferedT< T >, URLStreamBufferedT< ICYStream >, ReformatBaseStream, AudioStreamWrapper, ResampleStream, EncodedAudioStream, URLStream, BufferedTaskStream, I2SStream, MemoryStream, RingBufferStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, and BufferedStream.

isNotifyActive()

bool isNotifyActive ( )

inlineinherited

Checks if the automatic AudioInfo update is active.

not_supported()

virtual int not_supported ( int  out, const char *  msg = ""  )

inlineprotectedvirtualinherited

notifyAudioChange()

void notifyAudioChange ( AudioInfo  info )

inlineprotectedinherited

operator bool()

virtual operator bool ( )

inlinevirtualinherited

Reimplemented in A2DPStream, ICYStreamT< T >, AudioBLEStream, PortAudioStream, URLStream, USBAudioDeviceBase, I2SStream, AdapterAudioOutputToAudioStream, TimedStream, MemoryStream, GeneratedSoundStream< T >, GeneratedSoundStream< int16_t >, Pipeline, and AudioFFTBase.

readAudioInfo()

void readAudioInfo ( )

inlineprotected

readBytes()

size_t readBytes ( uint8_t *  data, size_t  len  )

inlinevirtual

Reimplemented from AudioStream.

readSilence()

virtual size_t readSilence ( uint8_t *  buffer, size_t  length  )

inlinevirtualinherited

Source to generate silence: just sets the buffer to 0.

refillReadBuffer()

void refillReadBuffer ( )

inlineprotectedinherited

Refill small read buffer (e.g. 8 bytes) to avoid single byte reads when calling read()

removeNotifyAudioChange()

virtual bool removeNotifyAudioChange ( AudioInfoSupport &  bi )

inlinevirtualinherited

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

Reimplemented in RTSPClient< TcpClient, UdpSocket >.

setAudioInfo()

void setAudioInfo ( AudioInfo  info )

inlinevirtual

Defines the input AudioInfo.

Reimplemented from AudioStream.

setNotifyActive()

void setNotifyActive ( bool  flag )

inlineinherited

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

setWriteBufferSize()

void setWriteBufferSize ( int  size )

inlineinherited

write() [1/2]

size_t write ( const uint8_t *  data, size_t  len  )

inlinevirtual

Reimplemented from AudioStream.

write() [2/2]

virtual size_t write ( uint8_t  ch )

inlineoverridevirtualinherited

Reimplemented in MemoryStream, AudioStreamWrapper, BufferedTaskStream, RingBufferStream, BufferedStream, and URLStream.

writeAudioInfo()

void writeAudioInfo ( )

inlineprotected

writeSilence()

virtual void writeSilence ( size_t  len )

inlinevirtualinherited

Writes len bytes of silence (=0).

Member Data Documentation

_timeout

int _timeout = 10

protectedinherited

buffer

SingleBuffer<uint8_t> buffer

protected

cfg

AudioLoRaConfig cfg

protected

info

AudioInfo info

protectedinherited

is_notify_active

bool is_notify_active = true

protectedinherited

notify_vector

Vector<AudioInfoSupport*> notify_vector

protectedinherited

tmp_in

RingBuffer<uint8_t> tmp_in {0}

protectedinherited

tmp_out

RingBuffer<uint8_t> tmp_out {0}

protectedinherited

write_buffer_size

int write_buffer_size = MAX_SINGLE_CHARS

protectedinherited

---

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

• src/AudioTools/Communication/AudioLoRa.h