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 TdmConfig::new_tdm_philips and related helpers. You can also configure custom data formats using methods such as TdmConfig::with_msb_shift, TdmConfig::with_ws_width, TdmConfig::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 rx_buffer = dma_rx_stream_buffer!(4 * 4092, 1024);

let i2s = I2s::new(
    peripherals.I2S0,
    peripherals.DMA_I2S0,
    TdmConfig::new_tdm_philips()
        .with_sample_rate(Rate::from_hz(44100))
        .with_data_format(DataFormat::Data16Channel16)
        .with_channels(Channels::STEREO),
)?;

let mut i2s_rx = i2s
    .i2s_rx
    .with_bclk(peripherals.GPIO1)
    .with_ws(peripherals.GPIO2)
    .with_din(peripherals.GPIO5)
    .build();

let mut transfer = i2s_rx.read(rx_buffer)?;

loop {
    let avail = transfer.available_bytes();

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

PDM mode

PDM (pulse-density modulation) is supported on I2S instances where the hardware provides PDM (see per-instance metadata). Use I2s::new_pdm with PdmConfig. Hardware PCM-to-PDM / PDM-to-PCM conversion is only available on instances that support it (typically I2S0); other instances require PdmDataFormat::Raw. PDM uses a single clock pin (with_clk on I2s::i2s_tx / I2s::i2s_rx) instead of separate BCLK and WS lines. Only simplex operation (TX or RX) is supported.

use esp_hal::i2s::master::{I2s, PdmSlotMode, PdmTxConfig, PdmConfig};
use esp_hal::time::Rate;

let pdm = PdmConfig::tx_only(PdmTxConfig::new_codec_default(
    Rate::from_hz(16_000),
    PdmSlotMode::Mono,
));
let i2s = I2s::new_pdm(peripherals.I2S0, peripherals.DMA_I2S0, pdm)?;

Re-exports

pub use super::pdm::PdmConfig;

pub use super::pdm::PdmDataFormat;

pub use super::pdm::PdmError;

pub use super::pdm::PdmInstance;

pub use super::pdm::PdmRxConfig;

pub use super::pdm::PdmSlotMode;

pub use super::pdm::PdmTxConfig;

Structs

Channels

I2S channels configuration

I2s

Instance of the I2S peripheral driver

I2sRx

I2S RX channel

I2sRxDmaTransferunstable

A structure representing a DMA transfer.

I2sTx

I2S TX channel

I2sTxDmaTransferunstable

A structure representing a DMA transfer.

TdmConfig

TDM mode peripheral configuration.

TdmUnitConfig

I2S receiver/transmitter unit configuration (TDM mode).

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

ClkPinunstable

Pins that can be used as clock outputs.

I2sMasterDmaChannelunstable

DMA channel trait for I2S master peripherals.

Instance

A peripheral singleton compatible with the I2S master driver.

Type Aliases

UnitConfig

Alias for TdmUnitConfig (TDM mode unit configuration).