This library allows you to use the I2S protocol on SAMD21 based boards (i.e Arduino or Genuino Zero, MKRZero or MKR1000 Board).
To use this library
1#include <I2S.h>
I2S (Inter-IC Sound), is an electrical serial bus interface standard used for connecting digital audio devices together. It is used to communicate PCM audio data between integrated circuits in an electronic device.
An I2S bus that follows the Philips standard is made up of at least three wires:
As detailed below, the device who generates SCK and WS is the Controller.
The SCK line has a frequency that depends on the sample rate, the number of bits for channel and the number of channels in the following way:
In a typical setup, the sender of audio data is called a Transmitter and it transfers data to a Receiver at the other end. The device that controls the bus clock, SCK, together with the Word Select - WS - signal is the Controller in the network and in any network just one device can be Controller at any given time; all the other devices connected are in Peripheral mode. The Controller can be the Transmitter, or the Receiver, or a standalone controller. The digitized audio data sample can have a size ranging from 4 bits up to 32.
As a general rule of thumb, the higher the sample rate (kHz) and bits per sample, the better audio quality (when the digital data is converted back to analog audio sound).
begin()
Initializes the I2S interface with the given parameters to enable communication.
1I2S.begin(mode, sampleRate, bitsPerSample); // controller device2I2S.begin(mode, bitsPerSample); // peripheral device
mode: one between I2S_PHILIPS_MODE, I2S_RIGHT_JUSTIFIED_MODE or I2S_LEFT_JUSTIFIED_MODE sampleRate: the desired sample rate in Hz - long bitsPerSample: the desired bits per sample (i.e 8, 16, 32)
1 if initialization is ok, 0 otherwise
end()
Disables I2S communication, allowing the I2S pins to be used for general input and output. To re-enable I2S communication, call I2S.begin().
1I2S.end()
none
nothing
available()
Get the number of bytes available for reading from the I2S interface. This is data that has already arrived and was stored in the I2S receive buffer. available() inherits from the Stream utility class.
1I2S.available()
none
the number of bytes available to read
peek()
Returns the next sample of incoming I2S data without removing it from the internal I2S buffer. That is, successive calls to peek() will return the same sample, as will the next call to read(). peek() inherits from the Stream utility class.
1I2S.peek()
None
The next sample of incoming I2S data available (or 0 if no data is available)
write()
Writes binary data to the I2S interface. This data is sent as a sample or series of samples.
1I2S.write(val) // blocking2I2S.write(buf, len) // not blocking
val: a value to send as a single sample
buf: an array to send as a series of samples
len: the length of the buffer
byte
availableForWrite()
Get the number of bytes available for writing in the buffer without blocking the write operation.
1I2S.availableForWrite()
none
the number of bytes available to write.
onTransmit(handler)
Registers a function to be called when a block of data has been transmitted.
handler: the function to be called when data is sent and return nothing, e.g.: void myHandler()
None
onReceive(handler)
Registers a function to be called when a block of data has been received.
handler: the function to be called when the device receives data and return nothing, e.g.: void myHandler()
None