.. currentmodule:: machine
.. _machine.I2S:

class I2S -- Inter-IC Sound bus protocol
========================================

The :class:`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** -- :meth:`write` and :meth:`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 :meth:`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** -- :class:`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:: 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
   -------

   .. method:: 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

   .. method:: deinit() -> None

     Deinitialize the I2S bus

   .. method::  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

   .. method::  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

   .. method::  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.

   .. staticmethod::  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
   ---------

   .. data:: RX
      :type: int

      for initialising the I2S bus ``mode`` to receive

   .. data:: TX
      :type: int

      for initialising the I2S bus ``mode`` to transmit

   .. data:: STEREO
      :type: int

      for initialising the I2S bus ``format`` to stereo

   .. data:: MONO
      :type: int

      for initialising the I2S bus ``format`` to mono