Module master 

Inter-IC Sound (I2S)

Overview

I2S (Inter-IC Sound) is a synchronous serial communication protocol usually used for transmitting audio data between two digital audio devices. Espressif devices may contain more than one I2S peripheral(s). These peripherals can be configured to input and output sample data via the I2S driver.

Configuration

I2S supports different data formats, including varying data and channel widths, different standards, such as the Philips standard and configurable pin mappings for I2S clock (BCLK), word select (WS), and data input/output (DOUT/DIN).

The driver uses DMA (Direct Memory Access) for efficient data transfer and supports various configurations, such as different data formats, standards (e.g., Philips) and pin configurations. It relies on other peripheral modules, such as

• GPIO
• DMA
• system (to configure and enable the I2S peripheral)

Standards

I2S supports different standards, which you can access using Config::new_* methods. You can also configure custom data formats using methods such as Config::with_msb_shift, Config::with_ws_width, Config::with_ws_polarity, etc.

In TDM mode, WS (word select, sometimes called LRCLK or left/right clock) becomes a frame synchronization signal that signals the first slot of a frame. The two sides of the TDM link must agree on the number of channels, data bit width, and frame synchronization pattern; this cannot be determined by examining the signal itself.

TDM Philips Standard

TDM Philips mode pulls the WS line low one BCK period before the first data bit of the first slot is sent and holds it low for 50% of the frame.

TDM MSB Standard

MSB (most-significant bit) mode is similar to Philips mode, except the WS line is pulled low at the same time the first data bit of the first slot is sent. It is held low for 50% of the frame.

TDM PCM Short Standard

PCM (pulse-code modulation) short mode pulls the WS line high one BCK period before the first data bit of the first slot is sent, keeps it high for one BCK, then pulls it low for the remainder of the frame.

TDM PCM Long Standard

PCM long mode pulls the WS line high one BCK period before the first data bit of the first slot is sent, keeps it high until just before the last data bit of the first slot is sent, then pulls it low for the remainder of the frame. Diagrams from ESP-IDF Programming Guide; rendered by Wavedrom.

Examples

I2S Read

let dma_channel = peripherals.DMA_CH0;
let (mut rx_buffer, rx_descriptors, _, _) = dma_buffers!(4 * 4092, 0);

let i2s = I2s::new(
    peripherals.I2S0,
    dma_channel,
    Config::new_tdm_philips()
        .with_sample_rate(Rate::from_hz(44100))
        .with_data_format(DataFormat::Data16Channel16)
        .with_channels(Channels::STEREO),
)?;
let i2s = i2s.with_mclk(peripherals.GPIO0);
let mut i2s_rx = i2s
    .i2s_rx
    .with_bclk(peripherals.GPIO1)
    .with_ws(peripherals.GPIO2)
    .with_din(peripherals.GPIO5)
    .build(rx_descriptors);

let mut transfer = i2s_rx.read_dma_circular(&mut rx_buffer)?;

loop {
    let avail = transfer.available()?;

    if avail > 0 {
        let mut rcv = [0u8; 5000];
        transfer.pop(&mut rcv[..avail])?;
    }
}

Implementation State

• Only TDM mode is supported.

Modules

asynch

Async functionality

Structs

Channels

I2S channels configuration

Config

I2S peripheral configuration.

I2s

Instance of the I2S peripheral driver

I2sRx

I2S RX channel

I2sTx

I2S TX channel

UnitConfig

I2S receiver/transmitter unit configuration

Enums

BitOrder

I2S bit order

ConfigError

Configuration errors.

DataFormat

Supported data formats

Endianness

I2S endianness

Error

I2S Error

I2sInterrupt

Represents the various interrupt types for the I2S peripheral.

Polarity

Represents the polarity of a signal

WsWidth

I2S word select signal width

Traits

AcceptedWord

Data types that the I2S peripheral can work with.

Instance

A peripheral singleton compatible with the I2S master driver.