5.5 KiB
machine
class I2S -- Inter-IC Sound bus protocol
I2S is a synchronous serial protocol used to connect digital audio devices. At the physical level, a bus consists of 3 lines: SCK, WS, SD. The I2S class supports controller operation. Peripheral operation is not supported.
The I2S class is currently available as a Technical Preview. During the preview period, feedback from users is encouraged. Based on this feedback, the I2S class API and implementation may be changed.
I2S objects can be created and initialized using:
from machine import I2S
from machine import Pin
# ESP32
sck_pin = Pin(14) # Serial clock output
ws_pin = Pin(13) # Word clock output
sd_pin = Pin(12) # Serial data output
or
# PyBoards
sck_pin = Pin("Y6") # Serial clock output
ws_pin = Pin("Y5") # Word clock output
sd_pin = Pin("Y8") # Serial data output
audio_out = I2S(2,
sck=sck_pin, ws=ws_pin, sd=sd_pin,
mode=I2S.TX,
bits=16,
format=I2S.MONO,
rate=44100,
ibuf=20000)
audio_in = I2S(2,
sck=sck_pin, ws=ws_pin, sd=sd_pin,
mode=I2S.RX,
bits=32,
format=I2S.STEREO,
rate=22050,
ibuf=20000)
- 3 modes of operation are supported:
-
- blocking
- non-blocking
- uasyncio
blocking:
num_written = audio_out.write(buf) # blocks until buf emptied
num_read = audio_in.readinto(buf) # blocks until buf filled
non-blocking:
audio_out.irq(i2s_callback) # i2s_callback is called when buf is emptied
num_written = audio_out.write(buf) # returns immediately
audio_in.irq(i2s_callback) # i2s_callback is called when buf is filled
num_read = audio_in.readinto(buf) # returns immediately
uasyncio:
swriter = uasyncio.StreamWriter(audio_out)
swriter.write(buf)
await swriter.drain()
sreader = uasyncio.StreamReader(audio_in)
num_read = await sreader.readinto(buf)
Some codec devices like the WM8960 or SGTL5000 require separate initialization before they can operate with the I2S class. For these, separate drivers are supplied, which also offer methods for controlling volume, audio processing and other things. For these drivers see:
wm8960
Constructor
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 linews
is a pin object for the word select linesd
is a pin object for the serial data linemck
is a pin object for the master clock line; master clock frequency is sampling rate * 256mode
specifies receive or transmitbits
specifies sample size (bits), 16 or 32format
specifies channel format, STEREO or MONOrate
specifies audio sampling rate (Hz); this is the frequency of thews
signalibuf
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
I2S.init(sck, ...)
see Constructor for argument descriptions
I2S.deinit()
Deinitialize the I2S bus
I2S.readinto(buf)
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
I2S.write(buf)
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
I2S.irq(handler)
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.
I2S.shift(*, buf, bits, shift)
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
I2S.RX
for initialising the I2S bus mode
to receive
I2S.TX
for initialising the I2S bus mode
to transmit
I2S.STEREO
for initialising the I2S bus format
to stereo
I2S.MONO
for initialising the I2S bus format
to mono