-
Notifications
You must be signed in to change notification settings - Fork 447
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Rewrite I2S from scratch, add I2S input support (#569)
Rewrite the I2S code from scratch to eliminate the dependence on the pico-extras implementation and to support I2S input as well. 8-bit, 16-bit, 24-bit, and 32-bit words are supported. Multiple I2S ports are allowed (theoretically up to 6 because 2 DMA channels are required per port). I2S input and I2S output are supported. Add input example Fixes #535 Fixes #99 Fixes #562
- Loading branch information
1 parent
3adc1c5
commit 07500e8
Showing
15 changed files
with
1,120 additions
and
284 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,89 +1,181 @@ | ||
| I2S (Digital Audio) Output Library | ||
| ================================== | ||
| I2S (Digital Audio) Audio Library | ||
| ================================= | ||
|
|
||
| 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. | ||
|
|
||
| This I2S library uses the ``pico-extras`` I2S audio library and wraps it in | ||
| an Arduino I2S library. It supports 16 bits/sample and frequencies of up | ||
| to 48kHZ, with configurable BCLK, LRCLK(always pin "BCLK + 1"), and DOUT pins. | ||
| 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. | ||
|
|
||
| **Note:** This I2S device takes over the entire PIO1 (second) unit and adjusts | ||
| its clock frequency to meet the I2S needs. That means when only 4 Tones | ||
| or only 4 Servos may be used when the I2S device is used. | ||
|
|
||
| I2S Class API | ||
| ------------- | ||
|
|
||
| I2S(OUTPUT) | ||
| ~~~~~~~~~~~ | ||
| Creates an I2S output port. Needs to be connected up to the | ||
| desired pins (see below) and started before any output can happen. | ||
|
|
||
| I2S(INPUT) | ||
| ~~~~~~~~~~ | ||
| Creates an I2S input port. Needs to be connected up to the | ||
| desired pins (see below) and started before any input can happen. | ||
|
|
||
| bool setBCLK(pin_size_t pin) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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()`` | ||
| Default BCLK = 26, LRCLK = 27 | ||
| due to limitations of the PIO state machines. Call this before ``I2S::begin()`` | ||
|
|
||
| bool setDOUT(pin_size_t pin) | ||
| bool setDATA(pin_size_t pin) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Sets the DOUT pin of the I2S device. Any pin may be used. Default DOUT = 28 | ||
| Call before ``I2S.begin()`` | ||
|
|
||
| bool begin(long sampleRate) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Start the I2S device up with the given sample rate. The pins selected above | ||
| will be turned to output and the I2S will begin to drive silence frames (all | ||
| zero) out. | ||
| Sets the DOUT or DIN pin of the I2S device. Any pin may be used. | ||
| Call before ``I2S::begin()`` | ||
|
|
||
| bool setBitsPerSample(int bits) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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()`` | ||
|
|
||
| bool setBuffers(size_t buffers, size_t bufferWords, int32_t silenceSample = 0) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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()``. | ||
|
|
||
| bool setFrequency(long sampleRate) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| bool begin()/begin(long sampleRate) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Start the I2S device up with the given sample rate, or with the value set | ||
| using the prior ``setFrequency`` call. | ||
|
|
||
| void end() | ||
| ~~~~~~~~~~ | ||
| Stops the I2S device. **Note, at present the memory allocated for I2S buffers | ||
| is not freed leading to a memory leak when ``end()`` is called. This is due | ||
| to the state of the ``pico-extras`` release which this code uses.** | ||
| Stops the I2S device. | ||
|
|
||
| void flush() | ||
| ~~~~~~~~~~~~ | ||
| Sends any partial frames in memory to the I2S output device. They may NOT play | ||
| immediately. Potential use case for this call would be when the frequency of | ||
| the output will be changing. | ||
|
|
||
| size_t write(uint8_t) | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| Provided for compatibility, but not very useful. Writes a sample from 0...255 | ||
| to the I2S buffer. See ``write(int16_t)`` for a better one | ||
| Waits until all the I2S buffers have been output. | ||
|
|
||
| size_t write(uint8_t/int8_t/int16_t/int32_t) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| size_t write(int32_t val, bool sync) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| size_t write(const uint8_t \*buffer, size_t size) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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** (i.e. one left/right sample). Will not block, so check | ||
| the return value to find out how many bytes were actually written. | ||
| of **4 bytes**. Will not block, so check the return value to find out how | ||
| many bytes were actually written. | ||
|
|
||
| int availableForWrite() | ||
| ~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Returns the number of **32-bit L/R samples** that can be written without | ||
| Returns the number of L/R samples that can be written without | ||
| potentially blocking. | ||
|
|
||
| bool setFrequency(int newFreq) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Adjusts the I2S output frequency. When changing frequency while I2S output | ||
| is underway, be sure to use ``I2S.flush()`` before changing the frequency to | ||
| ensure the older data is played at the right frequency. | ||
|
|
||
| size_t write(int16_t) | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes a single 16-bit left or right sample to the I2S output buffer. The | ||
| user is required to ensure that an even number of samples is written (i.e. | ||
| left and right) over the application lifetime. The application also needs | ||
| to track which sample is next to be written (right/left). For this reason, | ||
| the ``write(void *b, size_t lrsamples)`` call may be easier and faster to use. | ||
|
|
||
| size_t write(const void \*buffer, size_t lrsamples) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes up to size left+right packed samples to the I2S device. Non-blocking, | ||
| will writefrom 0...size samples and return that count. Be sure your app | ||
| handles partial writes (i.e. by ``yield()`` ing and then retrying to write the | ||
| remaining data.) | ||
|
|
||
| The ``onTransmit`` callback is not supported. | ||
|
|
||
| See the `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>`_ library | ||
| for a working example, or look at the included sample tone generator. | ||
| int read() | ||
| ~~~~~~~~~~ | ||
| Reads a single sample of I2S data, whatever the I2S sample size is configured. | ||
| Will not return until data is available. | ||
|
|
||
| int peek() | ||
| ~~~~~~~~~~ | ||
| Returns the next sample to be read from the I2S buffer (without actually | ||
| removing it). | ||
|
|
||
| void onTransmit(void (\*fn)(void)) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| void onReceive(void (\*fn)(void)) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| Sample Writing/Reading API | ||
| -------------------------- | ||
| 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). | ||
|
|
||
| size_t write8(int8_t l, int8_t r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes a left and right 8-bit sample to the I2S buffers. Blocks until space | ||
| is available. | ||
|
|
||
| size_t write16(int16_t l, int16_t r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes a left and right 16-bit sample to the I2S buffers. Blocks until space | ||
| is available. | ||
|
|
||
| size_t write24(int32_t l, int32_t r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes a left and right 24-bit sample to the I2S buffers. See note below | ||
| about 24-bit mode. Blocks until space is available. | ||
|
|
||
| size_t write32(int32_t l, int32_t r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Writes a left and right 32-bit sample to the I2S buffers. Blocks until space | ||
| is available. | ||
|
|
||
| bool read8(int8_t \*l, int8_t \*r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Reads a left and right 8-bit sample and returns ``true`` on success. Will block | ||
| until data is available. | ||
|
|
||
| bool read16(int16_t \*l, int16_t \*r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Reads a left and right 16-bit sample and returns ``true`` on success. Will block | ||
| until data is available. | ||
|
|
||
| bool read24(int32_t \*l, int32_t \*r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 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. | ||
|
|
||
| bool read32(int32_t \*l, int32_t \*r) | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Reads a left and right 32-bit sample and returns ``true`` on success. Will block | ||
| until data is available. | ||
|
|
||
|
|
||
| Note About 24-bit Samples | ||
| ------------------------- | ||
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| /* | ||
| I2S stereo microphone (input) example | ||
| Run using the Arduino Serial Plotter to see waveform. | ||
| Released to the Public Domain by Earle F. Philhower, III | ||
| For the Google AIY Voice Hat Microphone daughterboard, part | ||
| of the Raspberry Pi AIY cardboard box, the I2S stereo pinout | ||
| looking at the board top with the RPI logo on the left hand | ||
| side: | ||
| +-- ------------------------------------ --+ | ||
| left RPI | (1) GND (2) DIN (3) BCLK (4) LRCLK (5) 3.3V | AIY right | ||
| logo +---------------------------------------------+ logo | ||
| */ | ||
|
|
||
| #include <I2S.h> | ||
|
|
||
| I2S i2s(INPUT); | ||
|
|
||
| void setup() { | ||
| Serial.begin(115200); | ||
|
|
||
| i2s.setDATA(0); | ||
| i2s.setBCLK(1); // LRCLK = GP2 | ||
| i2s.setBitsPerSample(16); | ||
| i2s.setFrequency(22050); | ||
| i2s.begin(); | ||
|
|
||
| while (1) { | ||
| int16_t l, r; | ||
| i2s.read16(&l, &r); | ||
| Serial.printf("%d %d\n", l, r); | ||
| } | ||
| } | ||
|
|
||
| void loop() { | ||
| /* Nothing here */ | ||
| } |
Oops, something went wrong.