pio_i2s

Bidirectional I2S audio communication using PIO.

  • Author(s): Cooper Dalrymple

Implementation Notes

Software and Dependencies:

class pio_i2s.I2S(bit_clock: microcontroller.Pin, word_select: microcontroller.Pin = None, data_out: microcontroller.Pin = None, data_in: microcontroller.Pin = None, channel_count: int = 2, sample_rate: int = 48000, bits_per_sample: int = 16, samples_signed: bool = True, buffer_size: int = 1024, left_justified: bool = False, peripheral: bool = False)

Communicate with external audio devices using I2S protocol.

Parameters:

  • bit_clock (microcontroller.Pin) – The bit clock (or serial clock) pin.

  • word_select (microcontroller.Pin) – The word select (or left/right clock) pin. Must be the next pin from bit_clock sequentially. If not specified, the next pin sequentially from bit_clock will be used automatically.

  • data_out (microcontroller.Pin, optional) – The output data pin. If left unspecified, write functionality will be disabled.

  • data_in (microcontroller.Pin, optional) – The input data pin. If left unspecified, read functionality will be disabled.

  • channel_count (int, optional) – The number of channels. 1 = mono; 2 = stereo.

  • sample_rate (int, optional) – The sample rate to be used.

  • bits_per_sample (int, optional) – The bits per sample of be used. Must be 8, 16, 24, or 32 bits.

  • samples_signed (bool, optional) – Whether the samples are signed (True) or unsigned (False).

  • buffer_size (int, optional) – The total size in bytes of each of the two playback and record buffers to use.

  • left_justified (bool, optional) – True when data bits are aligned with the word select clock. False when they are shifted by one to match classic I2S protocol.

  • peripheral (bool, optional) – Whether the clock signals are generated by this device (False) or are read from the output of an external device (True). data_in must be specified if using peripheral mode and come before bit_clock sequentially.

property bits_per_sample: int

The number of bits per sample. This property is read-only.

property buffer_format: str

The format code of the array.array buffers. For more information, refer to the original CPython documentation: array. This property is read-only.

property buffer_size: int

The number of samples per buffer. This property is read-only.

property channel_count: int

The number of channels used by the I2S bus. 1 for mono, 2 for stereo. This property is read-only.

deinit() → None

Stop I2S communication and de-initialize resources used by this object.

play(source: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, source_length: int = None) → bool

Plays samples from the source data to the output of the I2S bus bytes of samples to destination. This is blocking.

Parameters:

  • destination (circuitpython_typing.ReadableBuffer) – The destination buffer to write the samples from the I2S bus to.

  • destination_length (int) – The number of samples to write to the destination buffer. If not provided, the full size of the destination buffer will be written to.

read(block: bool = True) → array

Read the input data from the I2S bus as an array of audio samples.

Parameters:

block (bool, optional) – Whether or not to wait until data from the I2S bus can be read from.

Returns:

An array.array object with buffer_size elements. If the channel_count is stereo (2), the left and right channels will alternate between even and odd indexes.

record(destination: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, destination_length: int = None) → bool

Records samples from the I2S bus to the destination. This is blocking.

Parameters:

  • destination (circuitpython_typing.ReadableBuffer) – The destination buffer to write the samples from the I2S bus to.

  • destination_length (int) – The number of samples to write to the destination buffer. If not provided, the full size of the destination buffer will be written to.

Returns:

Whether or not the recording operation was successful.

property sample_rate: int

The rate of the I2S bus in samples per second. This property is read-only.

property samples_signed: bool

Whether or not the samples are signed (True) or unsigned (False) integers. This property is read-only.

write(data: array | bytearray | bytes | memoryview | rgbmatrix.RGBMatrix | ulab.numpy.ndarray, loop: bool = False, block: bool = True) → bool

Write an array-like set of audio samples to the output buffer up to the maximum buffer_size.

Parameters:

  • data (circuitpython_typing.ReadableBuffer) – The array of sample data.

  • loop (bool, optional) – Whether or not to loop the sample data by copying it to both output buffers.

  • block (bool, optional) – Whether or not to wait until the I2S bus is ready to be written to.

Returns:

Whether or not the output buffer was successfully written to.

property write_ready: bool

Whether or not the I2S bus has a buffer that is ready to be written to. This property is read-only.