Libraries
Class Bus
extends Object
I2S Serial communication Bus, primarily used to emit sound but has a wide range of usages.
Class summary
| constructor --master/bool --mclk/any= --ws/any= --sck/any= --tx/any= --rx/any= --invert-mclk/bool= --invert-ws/bool= --invert-sck/bool= | Constructs an I2S channel. |
|---|---|
| constructor --sck/any= --ws/any= --tx/any= --rx/any= --mclk/any= --sample-rate/int --bits-per-sample/int --is-master/bool= --mclk-multiplier/int= --use-apll/bool= --buffer-size/int= | Deprecated. is-master has been renamed to '--master' and is now mandatory. use-apll is no longer supported. buffer-size is no longer supported. The bus must be constructed, configured, and started manually. |
Constructors
constructor --master/bool --mclk/any=null --ws/any=null --sck/any=null --tx/any=null --rx/any=null --invert-mclk/bool=false --invert-ws/bool=false --invert-sck/bool=false
Constructs an I2S channel.
For typical I2S setups, the rx/tx pin, a clock (sck), and a word-select (ws) pins are required. The master clock (mclk) is optional.
If master is true, then I2S peripheral runs as master. As master, the sck, ws, and mclk pins are outputs. As slave, they are inputs.
If a mclk pin is provide, then the master clock is emitted/read from that pin. Some ESP variants have restrictions on which pins can be used as output. Some variants don't support the master clock as input. Note that the mclk can be an output, even if the bus is in slave mode.
The invert-sck, invert-ws, invert-mclk flags can be used to invert the signals.
The mclk, ws, sck, tx, and rx are GPIO numbers. The channel reserves the pins and releases them again when the channel is closed.
constructor --sck/any=null --ws/any=null --tx/any=null --rx/any=null --mclk/any=null --sample-rate/int --bits-per-sample/int --is-master/bool=true --mclk-multiplier/int=256 --use-apll/bool=false --buffer-size/int=-1
Deprecated. is-master has been renamed to '--master' and is now mandatory. use-apll is no longer supported. buffer-size is no longer supported. The bus must be constructed, configured, and started manually.
Statics
MSB format.
The data signal is aligned with the word-select signal.
PCM short format.
The data signal is shifted by one bit compared to the word-select signal (like Philips).
The word-select signal is only active for one bit. The start of the word-select pulse is two bits before the data bit.
Philips format.
The data signal has a one-bit shift compared to the word-select signal.
That is, when the word-select signal switches, then there is still one bit of data left for the previous word.
A slot configuration for transmitting the same data to both slots.
ESP32
In 8-bit and 24-bit mode, the data must be padded to 16/32 bits.
For 16-bit (also the padded 8-bit), every two bytes are swapped.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0002 | 0x0002 | 0x0001 | 0x0001 | 0x0004 | 0x0004 | ...
Other ESP32 variants
The data is sent to both slots.
No reordering is done.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0001 | 0x0001 | 0x0002 | 0x0002 | 0x0003 | 0x0003 | ...
A slot configuration for mono left.
When writing, emits the data to the left buffer.
When receiving, only collects the left slot.
ESP32
Output
In 8-bit and 24-bit mode, the data must be padded to 16/32 bits.
For 16-bit (also the padded 8-bit), every two bytes are swapped.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0002 | 0x0000 | 0x0001 | 0x0000 | 0x0004 | 0x0000 | ...
Input
Only collects the left slot.
For 16-bit (also the padded 8-bit), every two bytes are swapped.
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0001 | 0x0002 | 0x0003 | 0x0004 | 0x0005 | 0x0006 | ...
Data:
0x0001 | 0x0000 | 0x0005 | 0x0003 | 0x0009 | 0x0007 | ...
Other ESP32 variants
Output
The data is sent to the left slot and 0s to the right slot.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0001 | 0x0000 | 0x0002 | 0x0000 | 0x0003 | 0x0000 | ...
Input
Only collects the left slot.
Wire:
WS-low | WS-high | WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------|---------|---------| ...
0x0001 | 0x0002 | 0x0003 | 0x0004 | 0x0005 | 0x0006 | ...
Data:
0x0001 | 0x0003 | 0x0005 | 0x0007 | 0x0009 | ...
A slot configuration for mono right.
When writing, emits the data to the right buffer.
When receiving, only collects the right slot.
A slot configuration for stereo.
The left and right slots are interleaved in the data stream.
The data in the buffers and on the wire is the same.
For example:
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------| ...
0x0001 0x0002 0x0003 0x0004
A slot configuration for transmitting the left data of the buffer.
ESP32 and ESP32S2
Sends the left data to both slots.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------| ...
0x0001 0x0001 0x0003 0x0003
Other ESP32 variants
Sends the left data to the left slot and 0s to the right slot.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------| ...
0x0001 0x0000 0x0003 0x0000
A slot configuration for transmitting the right data of the buffer.
ESP32 and ESP32S2
Sends the right data to both slots.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------| ...
0x0002 0x0002 0x0004 0x0004
Other ESP32 variants
Sends the right data to the right slot and 0s to the left slot.
Data:
0x0001 | 0x0002 | 0x0003 | 0x0004 | ...
Wire:
WS-low | WS-high | WS-low | WS-high | ...
--------|---------|---------|---------| ...
0x0000 0x0002 0x0000 0x0004
Methods
Closes the I2S bus and releases resources associated to it.
configure --mclk-external-frequency/int=null --mclk-multiplier/int=null --sample-rate/int --bits-per-sample/int --format/int=FORMAT-PHILIPS --slots-in/int --slots-out/int -> none
Configures the channel.
The sample-rate is the rate at which samples are written.
The bits-per-sample is the width of each sample. It can be either 8, 16, 24, or 32. For 8 and 24 bits see the note on the ESP32 below.
The mclk-multiplier is the multiplier of the sample-rate to be used for the master clock. It should be one of the 128, 256, 384, 512, 576, 768, 1024, or 1152. If none is given, it defaults to 384 for 24 bits per sample and 256 otherwise. If the bits-per-sample is 24 bits, then the multiplier must be a multiple of 3.
The mclk-multiplier is mostly revelant if a mclk pin was provided, but can also be used to allow slower sample-rates: a higher multiplier allows for a slower frequency.
If the mclk-external-frequency is set to a value and a mclk pin was provided, then the master clock is read from the mclk pin. This is only supported on some ESP32 variants. The mclk-external-frequency value must be higher than the clock frequency (sample-rate * bits-per-sample * 2).
The slots-out must be one of SLOTS-STEREO-BOTH, SLOTS-STEREO-LEFT (data is stereo, but only emit the left channel), SLOTS-STEREO-RIGHT, SLOTS-MONO-BOTH (data is mono, and should be sent to left and right), SLOTS-MONO-LEFT, or SLOTS-MONO-RIGHT.
configure --mclk-external-frequency/int=null --mclk-multiplier/int=null --sample-rate/int --bits-per-sample/int --format/int=FORMAT-PHILIPS --slots/int=SLOTS-STEREO-BOTH -> none
Variant of configure --slots-in --slots-out --sample-rate --bits-per-sample that sets both slots to the same value.
Number of encountered errors.
If overrun is true and includes overrun errors.
If underrun is true includes underrun errors.
If overrun and underrun are null (the default), then both types of errors are included.
If overrun (resp. underrun) is not null, and underrun (resp. overrun) is null, then the null-parameter is treated as false.
Overrun errors happen when the program is not fast enough to read the buffers.
Underrun errors happen when the program is not fast enough to write the buffers.
Whether this object is equal to the other.
Inheritance
Classes overwrite this operator to get an equality specific to their needs. Equality operators often compare the type and field contents. For example:
class Pin:
number/int
constructor .number:
operator == other:
if other is not Pin: return false
return number == other.number
A class doesn't have to follow the above format, but it must keep the operator in sync with any
hash-code method. That is, if a class has a hash-code member, then the equality and hash-code must agree. If two instances are equal (a == b), then their hash codes must also be equal (a.hash-code == b.hash-code).Preloads data to the I2S bus.
The channel must have a transmit channel.
The bus must be stopped.
Returns the number of bytes that were preloaded.
Reads bytes from the I2S bus.
This methods blocks until data is available.
Esp32
On the ESP32 (but not its variants), the buffer is padded for 8 and 24 bits samples. That is, for 8 bits, samples are provided in 16-bit blocks and only the highest 8 bits are used. For 24 bits, each sample is given as 32 bits, where only the highest 24 bits are used.
Reads bytes from the I2S bus to a buffer.
This methods blocks until data is available.
Starts the bus.
Usually the bus is started automatically when it is created. However, if the bus was created with the start flag set to false, then this method must be called to start the bus.
When a bus was constructed but not started yet, then the master clock is running, but the other signals are not. Specifically, in master mode, there is no clock, word-select or data being transmitted.
The bus must not already be started.
Stops the bus.
It's rare that you need to stop the bus. Usually, you just close it.
Stringifies this object.
Inheritance
Objects that need a human-friendly string representation should overwrite this method. The default string is based on the internal class-ID.
Writes bytes to the I2S bus.
This method blocks until some data has been written.
Returns the number of bytes written.
Writes bytes to the I2S bus.
This method blocks until all data has been written.
Esp32
On the ESP32 (but not its variants), the buffer needs to be padded for 8 and 24 bits samples. That is, for 8 bits, samples should be provided in 16-bit blocks and only the highest 8 bits are used. For 24 bits, each sample should be 32 bits, where only the highest 24 bits are used.