Collaboration diagram for I2S Driver:

Classes
union	i2s_sample_t
	I2S sample. More...

struct	i2s_module_config_t
	I2S module configuration (TX or RX) More...

struct	i2s_config_t
	I2S configuration parameters. More...

struct	i2s_buffer_info_t
	Defines a buffer with available content. More...

struct	i2s_buffer_stat_t
	Contains I2S buffer status information. More...

Typedefs
typedef void(*	i2s_callback_t) (void *param, i2s_event_type_t event)
	Callback function type. More...

typedef unsigned	TickType_t
	Defines the wait interval (presently milliseconds) More...

typedef uint8_t	i2s_pin_set_t

Enumerations
enum	i2s_bits_per_sample_t { I2S_BITS_PER_SAMPLE_8BIT = 8, I2S_BITS_PER_SAMPLE_16BIT = 16, I2S_BITS_PER_SAMPLE_24BIT = 24 }
	I2S bit width per sample. More...

enum	i2s_channel_t { I2S_CHANNEL_MONO = 1, I2S_CHANNEL_STEREO = 2 }
	I2S channel. More...

enum	i2s_comm_format_t { I2S_COMM_FORMAT_I2S = 0x01, I2S_COMM_FORMAT_I2S_MSB = 0x01, I2S_COMM_FORMAT_I2S_LSB = 0x03 }
	I2S communication standard format. More...

enum	i2s_channel_fmt_t { I2S_CHANNEL_FMT_RIGHT_LEFT = 0x00, I2S_CHANNEL_FMT_ALL_RIGHT, I2S_CHANNEL_FMT_ALL_LEFT, I2S_CHANNEL_FMT_ONLY_RIGHT, I2S_CHANNEL_FMT_ONLY_LEFT }
	I2S channel format type. More...

enum	i2s_mode_t { I2S_MODE_DISABLED, I2S_MODE_MASTER, I2S_MODE_SLAVE }
	I2S Mode, default is I2S_MODE_MASTER. More...

enum	i2s_event_type_t { I2S_EVENT_DMA_ERROR, I2S_EVENT_TX_DONE, I2S_EVENT_RX_DONE, I2S_EVENT_MAX }
	I2S event types. More...

enum	i2s_pin_t { I2S_PIN_BCK_OUT = 0x01, I2S_PIN_WS_OUT = 0x02, I2S_PIN_DATA_OUT = 0x04, I2S_PIN_BC_IN = 0x10, I2S_PIN_WS_IN = 0x20, I2S_PIN_DATA_IN = 0x40 }
	I2S pin enable for i2s_set_pin. More...

Functions
bool	i2s_driver_install (const i2s_config_t *config)
	Install and start I2S driver. More...

void	i2s_driver_uninstall ()
	Uninstall I2S driver. More...

bool	i2s_start ()
	Start I2S driver. More...

bool	i2s_stop ()
	Stop I2S driver. More...

bool	i2s_set_sample_rates (uint32_t rate)

bool	i2s_set_dividers (uint8_t bck_div, uint8_t mclk_div)

float	i2s_get_real_rate ()

bool	i2s_dma_read (i2s_buffer_info_t *info, size_t max_bytes)
	Fetch a DMA buffer containing received data (zero-copy) More...

bool	i2s_dma_write (i2s_buffer_info_t *info, size_t max_bytes)
	Fetch a DMA buffer for direct writing (zero-copy) More...

size_t	i2s_write (const void *src, size_t size, TickType_t ticks_to_wait)
	writes a buffer of frames into the DMA memory, returns the amount of frames written. More...

size_t	i2s_read (void *dest, size_t size, TickType_t ticks_to_wait)
	Reads a block of received data. More...

bool	i2s_zero_dma_buffer ()
	Zero the contents of the TX DMA buffer. More...

void	i2s_set_pins (i2s_pin_set_t pins, bool enable)
	Configure I2S pins. More...

bool	i2s_enable_loopback (bool enable)

bool	i2s_stat_tx (i2s_buffer_stat_t *stat)
	Obtain state information for TX buffers. More...

bool	i2s_stat_rx (i2s_buffer_stat_t *stat)
	Obtain state information for RX buffers. More...

Detailed Description

i2s.h - Hardware I2S driver for ESP8266

Author: Aug 2019 - mikee47 mike@.nosp@m.sill.nosp@m.yhous.nosp@m.e.ne.nosp@m.t

This file is part of the Sming Framework Project

This library is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 or later.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Sming. If not, see https://www.gnu.org/licenses/.

Typedef Documentation

◆ i2s_callback_t

typedef void(* i2s_callback_t) (void *param, i2s_event_type_t event)

Callback function type.

Note: Function is called in interrupt context, so place in IRAM and keep it brief.

◆ i2s_pin_set_t

typedef uint8_t i2s_pin_set_t

◆ TickType_t

typedef unsigned TickType_t

Defines the wait interval (presently milliseconds)

Enumeration Type Documentation

◆ i2s_bits_per_sample_t

enum i2s_bits_per_sample_t

I2S bit width per sample.

Enumerator
I2S_BITS_PER_SAMPLE_8BIT	I2S bits per sample: 8-bits.
I2S_BITS_PER_SAMPLE_16BIT	I2S bits per sample: 16-bits.
I2S_BITS_PER_SAMPLE_24BIT	I2S bits per sample: 24-bits.

◆ i2s_channel_fmt_t

enum i2s_channel_fmt_t

I2S channel format type.

Enumerator
I2S_CHANNEL_FMT_RIGHT_LEFT
I2S_CHANNEL_FMT_ALL_RIGHT
I2S_CHANNEL_FMT_ALL_LEFT
I2S_CHANNEL_FMT_ONLY_RIGHT
I2S_CHANNEL_FMT_ONLY_LEFT

◆ i2s_channel_t

enum i2s_channel_t

I2S channel.

Enumerator
I2S_CHANNEL_MONO	I2S 1 channel (mono)
I2S_CHANNEL_STEREO	I2S 2 channel (stereo)

◆ i2s_comm_format_t

enum i2s_comm_format_t

I2S communication standard format.

Enumerator
I2S_COMM_FORMAT_I2S	I2S communication format I2S.
I2S_COMM_FORMAT_I2S_MSB	I2S format MSB.
I2S_COMM_FORMAT_I2S_LSB	I2S format LSB.

◆ i2s_event_type_t

enum i2s_event_type_t

I2S event types.

Enumerator
I2S_EVENT_DMA_ERROR
I2S_EVENT_TX_DONE	I2S DMA finish sent 1 buffer
I2S_EVENT_RX_DONE	I2S DMA finish received 1 buffer
I2S_EVENT_MAX	I2S event max index

◆ i2s_mode_t

enum i2s_mode_t

I2S Mode, default is I2S_MODE_MASTER.

Enumerator
I2S_MODE_DISABLED
I2S_MODE_MASTER
I2S_MODE_SLAVE

◆ i2s_pin_t

enum i2s_pin_t

I2S pin enable for i2s_set_pin.

Enumerator
I2S_PIN_BCK_OUT	GPIO 15 / TXD2 / D8.
I2S_PIN_WS_OUT	GPIO 2 / TXD1 / D4.
I2S_PIN_DATA_OUT	GPIO 3 / RXD0 / D9.
I2S_PIN_BC_IN	GPIO 13 / RXD2 / D7.
I2S_PIN_WS_IN	GPIO 14 / D5.
I2S_PIN_DATA_IN	GPIO 12 / D6.

Function Documentation

◆ i2s_dma_read()

bool i2s_dma_read	(	i2s_buffer_info_t *	info,
		size_t	max_bytes
	)

Fetch a DMA buffer containing received data (zero-copy)

Parameters

info	Pointer to structure to receive buffer information
max_bytes	Number of bytes to read

Return values

bool	true on success, false if no data available or info is null

Note: On success, info->buffer specifies where to read the data from, and info->size how many bytes are actually available (always > 0).; Returns at most one DMA buffer

◆ i2s_dma_write()

bool i2s_dma_write	(	i2s_buffer_info_t *	info,
		size_t	max_bytes
	)

Fetch a DMA buffer for direct writing (zero-copy)

Parameters

info	Pointer to structure to receive buffer information
max_bytes	Number of bytes required in buffer

Return values

bool	true on success, false if buffer unavailable or info is null

Note: On success, info->buffer specifies where to write the data, and info->size how many bytes should be written - may be less than max_bytes, but always > 0.; Returns at most one DMA buffer

◆ i2s_driver_install()

bool i2s_driver_install ( const i2s_config_t * config )

Install and start I2S driver.

Note: This function must be called before any I2S driver read/write operations.

Parameters

config I2S configuration

Return values

true	on success, false if already installed or invalid config

◆ i2s_driver_uninstall()

void i2s_driver_uninstall ( )

Uninstall I2S driver.

◆ i2s_enable_loopback()

bool i2s_enable_loopback ( bool enable )

◆ i2s_get_real_rate()

float i2s_get_real_rate ( )

Return values

float The actual Sample Rate on output

◆ i2s_read()

size_t i2s_read	(	void *	dest,
		size_t	size,
		TickType_t	ticks_to_wait
	)

Reads a block of received data.

Parameters

dest	Buffer to store data
size	Max. bytes to read
ticks_to_wait	Wait timeout in ticks

Return values

size_t Number of bytes read

◆ i2s_set_dividers()

bool i2s_set_dividers	(	uint8_t	bck_div,
		uint8_t	mclk_div
	)

Direct control over output rate

◆ i2s_set_pins()

void i2s_set_pins	(	i2s_pin_set_t	pins,
		bool	enable
	)

Configure I2S pins.

Parameters

pins	Mask of i2s_pin_t values
enable	true to enable for I2S use, false to revert to GPIO

Note: Call this after initialising driver to specify which pins are required

You can alternatively use arduino functions.

Example: i2s_set_pins(_BV(I2S_BCK_OUT), true)

◆ i2s_set_sample_rates()

bool i2s_set_sample_rates ( uint32_t rate )

Parameters

rate	Sample rate in Hz (ex 44100, 48000) for TX/RX

◆ i2s_start()

bool i2s_start ( )

Start I2S driver.

Note: It is not necessary to call this function after i2s_driver_install() as it is started automatically, unless config.auto_start was set to false.

Return values

bool	true on success, false if driver not initialised

◆ i2s_stat_rx()

bool i2s_stat_rx ( i2s_buffer_stat_t * stat )

Obtain state information for RX buffers.

Parameters

stat

Return values

bool	true on success

◆ i2s_stat_tx()

bool i2s_stat_tx ( i2s_buffer_stat_t * stat )

Obtain state information for TX buffers.

Parameters

stat

Return values

bool	true on success

◆ i2s_stop()

bool i2s_stop ( )

Stop I2S driver.

Note: Disables I2S TX/RX, until i2s_start() is called

Return values

bool	true on success, false if driver not initialised

◆ i2s_write()

size_t i2s_write	(	const void *	src,
		size_t	size,
		TickType_t	ticks_to_wait
	)

writes a buffer of frames into the DMA memory, returns the amount of frames written.

Parameters

src	Data to write
size	Size in bytes
ticks_to_wait	Wait timeout in ticks

Return values

size_t Data actually written, may be less than size

Note: Data is copied into DMA buffers

◆ i2s_zero_dma_buffer()

bool i2s_zero_dma_buffer ( )

Zero the contents of the TX DMA buffer.

Note: Pushes zero-byte samples into the TX DMA buffer, until it is full

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ i2s_callback_t

◆ i2s_pin_set_t

◆ TickType_t

Enumeration Type Documentation

◆ i2s_bits_per_sample_t

◆ i2s_channel_fmt_t

◆ i2s_channel_t

◆ i2s_comm_format_t

◆ i2s_event_type_t

◆ i2s_mode_t

◆ i2s_pin_t

Function Documentation

◆ i2s_dma_read()

◆ i2s_dma_write()

◆ i2s_driver_install()

◆ i2s_driver_uninstall()

◆ i2s_enable_loopback()

◆ i2s_get_real_rate()

◆ i2s_read()

◆ i2s_set_dividers()

◆ i2s_set_pins()

◆ i2s_set_sample_rates()

◆ i2s_start()

◆ i2s_stat_rx()

◆ i2s_stat_tx()

◆ i2s_stop()

◆ i2s_write()

◆ i2s_zero_dma_buffer()