While the RP2040 chip on the Raspberry Pi Pico does not include a hardware I2S device, it is possible to use the PIO (Programmable I/O) state machines to implement one dynamically.
Digital audio input and output are supported at 8, 16, 24, and 32 bits per sample.
Theoretically up to 6 I2S ports may be created, but in practice there may not be enough resources (DMA, PIO SM) to actually create and use so many.
Create an I2S port by instantiating a variable of the I2S class specifying the direction. Configure it using API calls below before using it.
Creates an I2S output port. Needs to be connected up to the desired pins (see below) and started before any output can happen.
Creates an I2S input port. Needs to be connected up to the desired pins (see below) and started before any input can happen.
Sets the BCLK pin of the I2S device. The LRCLK/word clock will be pin + 1
due to limitations of the PIO state machines. Call this before I2S::begin()
Sets the DOUT or DIN pin of the I2S device. Any pin may be used. Call before I2S::begin()
Sets the MCLK pin of the I2S device and enables MCLK output. Any pin may be used. Call before I2S::begin()
Sets the sample rate to MCLK multiplier value. Only multiples of 64 are valid. Call before I2S::begin()
Specify how many bits per audio sample to read or write. Note that for 24-bit samples, audio samples must be left-aligned (i.e. bits 31...8). Call before I2S::begin()
Set the number of DMA buffers and their size in 32-bit words as well as the word to fill when no data is available to send to the I2S hardware. Call before I2S::begin()
.
Sets the word clock frequency, but does not start the I2S device if not already running. May be called after I2S::begin()
to change the sample rate on-the-fly.
Changes the PICO system clock to optimise for the desired samplerate. The clock changes to 147.6 MHz for samplerates that are a multiple of 8 kHz, and 135.6 MHz for multiples of 11.025 kHz. Note that using setSysClk()
may affect the timing of other sysclk-dependent functions. Should be called before any I2S functions and any other sysclk dependent initialisations.
Enables LSB-J format for I2S output. In this mode the MSB comes out at the same time as the LRCLK changes, and not the normal 1-cycle delay. Useful for DAC chips like the PT8211.
Enabled TDM formatted multi-channel output. Be sure to set the number of channels to the expected value (8 normally) and the bits per sample to 32.
Sets the number of TDM channels between frame syncs. Generally should be set to 8.
Certain boards are hardwired with the WCLK before the BCLK, instead of the normal way around. This call swaps the WCLK and BCLK pins. Note that you still call setBCLK(x)
with x
being the lowest pin ID (i.e. in swapClocks mode the setBCLK
call actually sets LRCLK).
Start the I2S device up with the given sample rate, or with the value set using the prior setFrequency
call.
Stops the I2S device.
Waits until all the I2S buffers have been output.
Returns a flag indicating if the I2S system ran our of data to send on output, or had to throw away data on input.
Writes a single sample of bitsPerSample
to the buffer. It is up to the user to keep track of left/right channels. Note this writes data equivalent to one channel's data, not the size of the passed in variable (i.e. if you have a 16-bit sample size and write((int8_t)-5); write((int8_t)5);
you will have written 2 samples to the I2S buffer of whatever the I2S size, not a single 16-bit sample.
This call will block (wait) until space is available to actually write the data.
Writes 32 bits of data to the I2S buffer (regardless of the configured I2S bit size). When sync
is true, it will not return until the data has been writte. When sync
is false, it will return 0
immediately if there is no space present in the I2S buffer.
Transfers number of bytes from an application buffer to the I2S output buffer. Be aware that size
is in bytes* and not samples. Size must be a multiple of 4 bytes. Will not block, so check the return value to find out how many bytes were actually written.
Returns the amount of bytes that can be written without potentially blocking.
Reads a single sample of I2S data, whatever the I2S sample size is configured. Will not return until data is available.
Returns the next sample to be read from the I2S buffer (without actually removing it).
Sets a callback to be called when an I2S DMA buffer is fully transmitted. Will be in an interrupt context so the specified function must operate quickly and not use blocking calls like delay() or write to the I2S.
Sets a callback to be called when an I2S DMA buffer is fully read in. Will be in an interrupt context so the specified function must operate quickly and not use blocking calls like delay() or read from the I2S.
Because I2S streams consist of a natural left and right sample, it is often convenient to write or read both with a single call. The following calls allow applications to read or write both samples at the same time, and explicitly indicate the bit widths required (to avoid potential issues with type conversion on calls).
Writes a left and right 8-bit sample to the I2S buffers. Blocks until space is available.
Writes a left and right 16-bit sample to the I2S buffers. Blocks until space is available.
Writes a left and right 24-bit sample to the I2S buffers. See note below about 24-bit mode. Blocks until space is available.
Writes a left and right 32-bit sample to the I2S buffers. Blocks until space is available.
Reads a left and right 8-bit sample and returns true
on success. Will block until data is available.
Reads a left and right 16-bit sample and returns true
on success. Will block until data is available.
Reads a left and right 24-bit sample and returns true
on success. See note below about 24-bit mode. Will block until data is available.
Reads a left and right 32-bit sample and returns true
on success. Will block until data is available.
24-bit samples are stored as left-aligned 32-bit values with bits 7..0 ignored. Only the upper 24 bits 31...8 will be transmitted or received. The actual I2S protocol will only transmit or receive 24 bits in this mode, even though the data is 32-bit packed.