I2S

API Reference

Header File

Functions

esp_err_t i2s_set_pin(i2s_port_t i2s_num, const i2s_pin_config_t *pin)

Set I2S pin number.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_FAIL IO error

Parameters

  • i2s_num: I2S_NUM_0

  • pin: I2S Pin structure

esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config, int queue_size, void *i2s_queue)

Install and start I2S driver.

Note

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

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_ERR_NO_MEM Out of memory

Parameters

  • i2s_num: I2S_NUM_0

  • i2s_config: I2S configurations - see i2s_config_t struct

  • queue_size: I2S event queue size/depth.

  • i2s_queue: I2S event queue handle, if set NULL, driver will not use an event queue.

esp_err_t i2s_driver_uninstall(i2s_port_t i2s_num)

Uninstall I2S driver.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

esp_err_t i2s_write(i2s_port_t i2s_num, const void *src, size_t size, size_t *bytes_written, TickType_t ticks_to_wait)

Write data to I2S DMA transmit buffer.

Note

many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

  • src: Source address to write from

  • size: Size of data in bytes

  • [out] bytes_written: Number of bytes written, if timeout, the result will be less than the size passed in.

  • ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this

esp_err_t i2s_write_expand(i2s_port_t i2s_num, const void *src, size_t size, size_t src_bits, size_t aim_bits, size_t *bytes_written, TickType_t ticks_to_wait)

Write data to I2S DMA transmit buffer while expanding the number of bits per sample. For example, expanding 16-bit PCM to 32-bit PCM.

Note

many ticks pass without space becoming available in the DMA transmit buffer, then the function will return (note that if the data is written to the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout. Format of the data in source buffer is determined by the I2S configuration (see i2s_config_t).

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

  • src: Source address to write from

  • size: Size of data in bytes

  • src_bits: Source audio bit

  • aim_bits: Bit wanted, no more than 32, and must be greater than src_bits

  • [out] bytes_written: Number of bytes written, if timeout, the result will be less than the size passed in.

  • ticks_to_wait: TX buffer wait timeout in RTOS ticks. If this

esp_err_t i2s_read(i2s_port_t i2s_num, void *dest, size_t size, size_t *bytes_read, TickType_t ticks_to_wait)

Read data from I2S DMA receive buffer.

Note

If the built-in ADC mode is enabled, we should call i2s_adc_start and i2s_adc_stop around the whole reading process, to prevent the data getting corrupted.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

  • dest: Destination address to read into

  • size: Size of data in bytes

  • [out] bytes_read: Number of bytes read, if timeout, bytes read will be less than the size passed in.

  • ticks_to_wait: RX buffer wait timeout in RTOS ticks. If this many ticks pass without bytes becoming available in the DMA receive buffer, then the function will return (note that if data is read from the DMA buffer in pieces, the overall operation may still take longer than this timeout.) Pass portMAX_DELAY for no timeout.

esp_err_t i2s_set_sample_rates(i2s_port_t i2s_num, uint32_t rate)

Set sample rate used for I2S RX and TX.

Note

The bit clock rate is determined by the sample rate and i2s_config_t configuration parameters (number of channels, bits_per_sample). bit_clock = rate * (number of channels) * bits_per_sample

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_ERR_NO_MEM Out of memory

Parameters

  • i2s_num: I2S_NUM_0

  • rate: I2S sample rate (ex: 8000, 44100…)

esp_err_t i2s_stop(i2s_port_t i2s_num)

Stop I2S driver.

Note

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

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

esp_err_t i2s_start(i2s_port_t i2s_num)

Start I2S driver.

Note

It is not necessary to call this function after i2s_driver_install() (it is started automatically), however it is necessary to call it after i2s_stop().

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num)

Zero the contents of the TX DMA buffer.

Note

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

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

Parameters

  • i2s_num: I2S_NUM_0

esp_err_t i2s_set_clk(i2s_port_t i2s_num, uint32_t rate, i2s_bits_per_sample_t bits, i2s_channel_t ch)

Set clock & bit width used for I2S RX and TX.

Note

Similar to i2s_set_sample_rates(), but also sets bit width.

Return

  • ESP_OK Success

  • ESP_ERR_INVALID_ARG Parameter error

  • ESP_ERR_NO_MEM Out of memory

Parameters

  • i2s_num: I2S_NUM_0

  • rate: I2S sample rate (ex: 8000, 44100…)

  • bits: I2S bit width (I2S_BITS_PER_SAMPLE_16BIT, I2S_BITS_PER_SAMPLE_24BIT)

  • ch: I2S channel, (I2S_CHANNEL_MONO, I2S_CHANNEL_STEREO)

Structures

struct i2s_config_t

I2S configuration parameters for i2s_param_config function.

Public Members

i2s_mode_t mode

I2S work mode

int sample_rate

I2S sample rate

i2s_bits_per_sample_t bits_per_sample

I2S bits per sample

i2s_channel_fmt_t channel_format

I2S channel format

i2s_comm_format_t communication_format

I2S communication format

int dma_buf_count

I2S DMA Buffer Count

int dma_buf_len

I2S DMA Buffer Length

bool tx_desc_auto_clear

I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data unavailability)

struct i2s_event_t

Event structure used in I2S event queue.

Public Members

i2s_event_type_t type

I2S event type

size_t size

I2S data size for I2S_DATA event

struct i2s_pin_config_t

I2S pin enable for i2s_set_pin.

Public Members

int bck_o_en

BCK out pin

int ws_o_en

WS out pin

int bck_i_en

BCK in pin

int ws_i_en

WS in pin

int data_out_en

DATA out pin

int data_in_en

DATA in pin

Enumerations

enum i2s_bits_per_sample_t

I2S bit width per sample.

Values:

I2S_BITS_PER_SAMPLE_8BIT = 8

I2S bits per sample: 8-bits

I2S_BITS_PER_SAMPLE_16BIT = 16

I2S bits per sample: 16-bits

I2S_BITS_PER_SAMPLE_24BIT = 24

I2S bits per sample: 24-bits

enum i2s_channel_t

I2S channel.

Values:

I2S_CHANNEL_MONO = 1

I2S 1 channel (mono)

I2S_CHANNEL_STEREO = 2

I2S 2 channel (stereo)

enum i2s_comm_format_t

I2S communication standard format.

Values:

I2S_COMM_FORMAT_I2S = 0x01

I2S communication format I2S

I2S_COMM_FORMAT_I2S_MSB = 0x02

I2S format MSB

I2S_COMM_FORMAT_I2S_LSB = 0x04

I2S format LSB

enum i2s_channel_fmt_t

I2S channel format type.

Values:

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
enum i2s_port_t

I2S Peripheral, 0.

Values:

I2S_NUM_0 = 0x0

I2S 0

I2S_NUM_MAX
enum i2s_mode_t

I2S Mode, defaut is I2S_MODE_MASTER | I2S_MODE_TX.

Values:

I2S_MODE_MASTER = 1
I2S_MODE_SLAVE = 2
I2S_MODE_TX = 4
I2S_MODE_RX = 8
enum i2s_event_type_t

I2S event types.

Values:

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