I2S object with IRQ-based callbacks to a FreeRTOS task, for use with BackgroundAudio. More...

#include <ESP32I2SAudio.h>

Inheritance diagram for ESP32I2SAudio:

Collaboration diagram for ESP32I2SAudio:

Public Member Functions
	ESP32I2SAudio (int8_t bclk=0, int8_t ws=1, int8_t dout=2, int8_t mclk=-1)
	Construct ESP32-based I2S object with IRQ-based callbacks to a FreeRTOS task, for use with BackgroundAudio.

void	setPins (int8_t bclk, int8_t ws, int8_t dout, int8_t mclk=-1)
	Set the I2S GPIO pins before calling `begin`

void	setInverted (bool bclk, bool ws, bool mclk=false)
	Set the I2S GPIO inversions before calling `begin`

bool	setBuffers (size_t buffers, size_t bufferWords, int32_t silenceSample=0) override
	Set the size and number of the I2S buffers before `begin`

bool	setBitsPerSample (int bps) override
	Set the bits per sample for the I2S output. Only 16-bit supported.

bool	setFrequency (int freq) override
	Set the sample rate (LRCLK/WS) of the I2S interface. Can be called while running.

bool	setStereo (bool stereo=true) override
	Set mono or stereo mode. Only stereo supported.

bool	begin () override
	Start the I2S interface.

void	_backgroundTask ()
	Background I2S DMA buffer notification task. Tracks number of bytes available to be written.

uint32_t	frames ()
	Get number of DMA frames(buffers) processed.

uint32_t	irqs ()
	Get the number of input data shifts processed by decoder since `begin`

uint32_t	underflows ()
	Get the number of times the MP3 decoder has underflowed waiting on raw data since `begin`

IRAM_ATTR bool	_onSentCB (i2s_chan_handle_t handle, i2s_event_data_t *event, bool underflow=false)
	Object-based callback for I2S Sent notification.

bool	end () override
	Stop the I2S device.

bool	getUnderflow () override
	Determine if there was an underflow since the last time this was called. Cleared on read.

void	onTransmit (void(cb)(void ), void *cbData) override
	Set the callback function to be called every DMA buffer completion.

size_t	write (const uint8_t *buffer, size_t size) override
	Write data to the I2S interface. Not legal from IRQ context. Will not block and may write less than requested.

size_t	write (uint8_t d) override
	Write single byte to I2S buffers. Not supported.

int	availableForWrite () override
	Determine the number of bytes we can write to the DMA buffers at this instant.

Static Public Member Functions
static IRAM_ATTR bool	_onSent (i2s_chan_handle_t handle, i2s_event_data_t event, void user_ctx)
	C-language wrapper for I2S Sent event.

static IRAM_ATTR bool	_onSentUnder (i2s_chan_handle_t handle, i2s_event_data_t event, void user_ctx)
	C-language wrapper for I2S Sent Underflow event.

static void	_taskShim (void *pvParameters)
	C-language shim to start the real object's task.

Detailed Description

I2S object with IRQ-based callbacks to a FreeRTOS task, for use with BackgroundAudio.

ESP-IDF has an error in initializer order for the I2S clock default macros. Redefine it in the proper order until this is fixed. See https://github.com/espressif/arduino-esp32/issues/10975 and https://github.com/espressif/esp-idf/issues/15405

Constructor & Destructor Documentation

◆ ESP32I2SAudio()

ESP32I2SAudio::ESP32I2SAudio	(	int8_t	bclk = `0`,
		int8_t	ws = `1`,
		int8_t	dout = `2`,
		int8_t	mclk = `-1`
	)

inline

Construct ESP32-based I2S object with IRQ-based callbacks to a FreeRTOS task, for use with BackgroundAudio.

Parameters

[in]	bclk	GPIO pin to use for the bit clock (BCLK)
[in]	ws	GPIO pin to use for the word clock (LRCLK, WS)
[in]	dout	GPIO pin to use as the DOUT from the I2S device (connected to DIN on the DAC)
[in]	mclk	Optional GPIO pin for the MCLK (multiplied clock) output, not always needed

Member Function Documentation

◆ _onSent()

static IRAM_ATTR bool ESP32I2SAudio::_onSent	(	i2s_chan_handle_t	handle,
		i2s_event_data_t *	event,
		void *	user_ctx
	)

inlinestatic

C-language wrapper for I2S Sent event.

Returns: True if a task was woken up (FreeRTOS xHigherPriorityTaskWoken)

◆ _onSentCB()

IRAM_ATTR bool ESP32I2SAudio::_onSentCB	(	i2s_chan_handle_t	handle,
		i2s_event_data_t *	event,
		bool	underflow = `false`
	)

inline

Object-based callback for I2S Sent notification.

Returns: True if a task was woken up (FreeRTOS xHigherPriorityTaskWoken)

◆ _onSentUnder()

static IRAM_ATTR bool ESP32I2SAudio::_onSentUnder	(	i2s_chan_handle_t	handle,
		i2s_event_data_t *	event,
		void *	user_ctx
	)

inlinestatic

C-language wrapper for I2S Sent Underflow event.

Returns: True if a task was woken up (FreeRTOS xHigherPriorityTaskWoken)

◆ availableForWrite()

int ESP32I2SAudio::availableForWrite ( )

inlineoverride

Determine the number of bytes we can write to the DMA buffers at this instant.

Returns: Number of bytes available. May not be completely accurate

◆ begin()

bool ESP32I2SAudio::begin ( )

inlineoverride

Start the I2S interface.

Allocates an I2S hardware device with the requested number and size of DMA buffers and pinout. A FreeRTOS task is started, awoken from the I2S DMA buffer complete interrupt, to process the reading and writing and keep track of the available sample space for upper layers.

Returns: True on success

◆ end()

bool ESP32I2SAudio::end ( )

inlineoverride

Stop the I2S device.

Returns: True if success

◆ frames()

uint32_t ESP32I2SAudio::frames ( )

inline

Get number of DMA frames(buffers) processed.

Returns: Number of frames

◆ getUnderflow()

bool ESP32I2SAudio::getUnderflow ( )

inlineoverride

Determine if there was an underflow since the last time this was called. Cleared on read.

Returns: True if an underflow occurred.

◆ irqs()

uint32_t ESP32I2SAudio::irqs ( )

inline

Get the number of input data shifts processed by decoder since begin

Returns: Number of times data has been shifted in the raw input buffer

◆ onTransmit()

void ESP32I2SAudio::onTransmit	(	void()(void )	cb,
		void *	cbData
	)

inlineoverride

Set the callback function to be called every DMA buffer completion.

Parameters

[in]	cb	Callback function
[in]	cbData	Data to be passed to the callback function

◆ setBitsPerSample()

bool ESP32I2SAudio::setBitsPerSample ( int bps )

inlineoverride

Set the bits per sample for the I2S output. Only 16-bit supported.

Parameters

[in] bps Bits per sample, only 16-bit supported

Returns: True if successful

◆ setBuffers()

bool ESP32I2SAudio::setBuffers	(	size_t	buffers,
		size_t	bufferWords,
		int32_t	silenceSample = `0`
	)

inlineoverride

Set the size and number of the I2S buffers before begin

Parameters

[in]	buffers	Number of I2S DMA buffers
[in]	bufferWords	Number of 32-bit words (i.e. a single stereo 16-bit sample) per each DMA buffer
[in]	silenceSample	Optional 32-bit value to send out in case of underflow, normally 0

Returns: True if parameters were successful

◆ setFrequency()

bool ESP32I2SAudio::setFrequency ( int freq )

inlineoverride

Set the sample rate (LRCLK/WS) of the I2S interface. Can be called while running.

Parameters

[in] freq New sampling frequency in hertz

Returns: True if succeeded

◆ setInverted()

void ESP32I2SAudio::setInverted	(	bool	bclk,
		bool	ws,
		bool	mclk = `false`
	)

inline

Set the I2S GPIO inversions before calling begin

Parameters

[in]	bclk	True to invert BCLK output
[in]	ws	True to invert WS/LRCLK output
[in]	mclk	Optionallt, true to invert the MCLK output

◆ setPins()

void ESP32I2SAudio::setPins	(	int8_t	bclk,
		int8_t	ws,
		int8_t	dout,
		int8_t	mclk = `-1`
	)

inline

Set the I2S GPIO pins before calling begin

Parameters

[in]	bclk	GPIO pin to use for the bit clock (BCLK)
[in]	ws	GPIO pin to use for the word clock (LRCLK, WS)
[in]	dout	GPIO pin to use as the DOUT from the I2S device (connected to DIN on the DAC)
[in]	mclk	Optional GPIO pin for the MCLK (multiplied clock) output, not always needed

◆ setStereo()

bool ESP32I2SAudio::setStereo ( bool stereo = true )

inlineoverride

Set mono or stereo mode. Only stereo supported.

Parameters

[in] stereo Set to true for stereo (L/R) output

Returns: True if success

◆ underflows()

uint32_t ESP32I2SAudio::underflows ( )

inline

Get the number of times the MP3 decoder has underflowed waiting on raw data since begin

Returns: Number of frames of underflow data have occurred

◆ write() [1/2]

size_t ESP32I2SAudio::write	(	const uint8_t *	buffer,
		size_t	size
	)

inlineoverride

Write data to the I2S interface. Not legal from IRQ context. Will not block and may write less than requested.

Parameters

[in]	buffer	Data to be written
[in]	size	Number of bytes to write.

Returns: Number of bytes actually written to the I2S DMA buffers

◆ write() [2/2]

size_t ESP32I2SAudio::write ( uint8_t d )

inlineoverride

Write single byte to I2S buffers. Not supported.

Returns: 0 always

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

ESP32I2SAudio.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ESP32I2SAudio()

Member Function Documentation

◆ _onSent()

◆ _onSentCB()

◆ _onSentUnder()

◆ availableForWrite()

◆ begin()

◆ end()

◆ frames()

◆ getUnderflow()

◆ irqs()

◆ onTransmit()

◆ setBitsPerSample()

◆ setBuffers()

◆ setFrequency()

◆ setInverted()

◆ setPins()

◆ setStereo()

◆ underflows()

◆ write() [1/2]

◆ write() [2/2]