class I2S – Inter-IC Sound bus protocol

The I2S class drives an Inter-IC Sound (I2S) bus in controller mode – the MCU generates the bit clock (SCK) and the word-select clock (WS) and exchanges sample data on the SD line. The driver supports continuous DMA in the background so the Python side only needs to keep the internal sample buffer fed. Peripheral / receiver-only modes are not supported.

Available on STM32 OpenMV cams that wire an I2S peripheral and the OpenMV Cam RT1062. Not exposed on the OpenMV Cam AE3 (alif port).

I2S(2) on STM32 OpenMV cams shares its pins with SPI(2) – bit-clock on P2 (SCK), word-select on P3 (NSS), and the serial-data line follows the SPI data-direction convention: TX uses P0 (MOSI), RX uses P1 (MISO).

Example – output (TX). Construct a TX bus to drive an external audio DAC at 44.1 kHz, 16-bit mono samples, with a 16384-byte (16 KiB) DMA backing buffer:

from machine import I2S, Pin

audio_out = I2S(
    2,
    sck=Pin("P2"), ws=Pin("P3"), sd=Pin("P0"),
    mode=I2S.TX,
    bits=16,
    format=I2S.MONO,
    rate=44100,
    ibuf=16384,
)

Example – input (RX). Construct an RX bus that captures from a microphone at 22.05 kHz, 32-bit stereo (left + right interleaved), with a 16384-byte (16 KiB) DMA backing buffer:

from machine import I2S, Pin

audio_in = I2S(
    2,
    sck=Pin("P2"), ws=Pin("P3"), sd=Pin("P1"),
    mode=I2S.RX,
    bits=32,
    format=I2S.STEREO,
    rate=22050,
    ibuf=16384,
)

The transfer methods can be used in three styles:

Blocking – write() and readinto() return only once the operation completes:

num_written = audio_out.write(buf)   # blocks until buf is drained
num_read = audio_in.readinto(buf)    # blocks until buf is filled

Non-blocking – install a callback with irq() and the transfer methods return immediately. The callback runs from the MicroPython scheduler when the DMA empties the TX buffer or fills the RX buffer:

audio_out.irq(i2s_callback)
num_written = audio_out.write(buf)   # returns immediately

audio_in.irq(i2s_callback)
num_read = audio_in.readinto(buf)    # returns immediately

asyncio – I2S is a stream and can be wrapped by asyncio.StreamReader / asyncio.StreamWriter:

swriter = asyncio.StreamWriter(audio_out)
swriter.write(buf)
await swriter.drain()

sreader = asyncio.StreamReader(audio_in)
num_read = await sreader.readinto(buf)

Constructor

class machine.I2S(id: int, *, sck: Pin, ws: Pin, sd: Pin, mck: Pin | None = None, mode: int, bits: int, format: int, rate: int, ibuf: int)

Construct an I2S object of the given id:

  • id identifies a particular I2S bus; it is board and port specific

Keyword-only parameters that are supported on all ports:

  • sck is a pin object for the serial clock line

  • ws is a pin object for the word select line

  • sd is a pin object for the serial data line

  • mck is a pin object for the master clock line; master clock frequency is sampling rate * 256

  • mode specifies receive or transmit

  • bits specifies sample size (bits), 16 or 32

  • format specifies channel format, STEREO or MONO

  • rate specifies audio sampling rate (Hz); this is the frequency of the ws signal

  • ibuf specifies internal buffer length (bytes)

For all ports, DMA runs continuously in the background and allows user applications to perform other operations while sample data is transferred between the internal buffer and the I2S peripheral unit. Increasing the size of the internal buffer has the potential to increase the time that user applications can perform non-I2S operations before underflow (e.g. write method) or overflow (e.g. readinto method).

Methods

init(*, sck: Pin, ws: Pin, sd: Pin, mck: Pin | None = None, mode: int, bits: int, format: int, rate: int, ibuf: int) → None

see Constructor for argument descriptions

deinit() → None

Deinitialize the I2S bus

readinto(buf: bytearray) → int

Read audio samples into the buffer specified by buf. buf must support the buffer protocol, such as bytearray or array. “buf” byte ordering is little-endian. For Stereo format, left channel sample precedes right channel sample. For Mono format, the left channel sample data is used. Returns number of bytes read

write(buf: bytes) → int

Write audio samples contained in buf. buf must support the buffer protocol, such as bytearray or array. “buf” byte ordering is little-endian. For Stereo format, left channel sample precedes right channel sample. For Mono format, the sample data is written to both the right and left channels. Returns number of bytes written

irq(handler: Callable[[I2S], None]) → None

Set a callback. handler is called when buf is emptied (write method) or becomes full (readinto method). Setting a callback changes the write and readinto methods to non-blocking operation. handler is called in the context of the MicroPython scheduler.

static shift(*, buf: bytearray, bits: int, shift: int) → None

bitwise shift of all samples contained in buf. bits specifies sample size in bits. shift specifies the number of bits to shift each sample. Positive for left shift, negative for right shift. Typically used for volume control. Each bit shift changes sample volume by 6dB.

Constants

RX: int

for initialising the I2S bus mode to receive

TX: int

for initialising the I2S bus mode to transmit

STEREO: int

for initialising the I2S bus format to stereo

MONO: int

for initialising the I2S bus format to mono