|
1 | | -I2S (Digital Audio) Output Library |
2 | | -================================== |
| 1 | +I2S (Digital Audio) Audio Library |
| 2 | +================================= |
3 | 3 |
|
4 | 4 | While the RP2040 chip on the Raspberry Pi Pico does not include a hardware |
5 | 5 | I2S device, it is possible to use the PIO (Programmable I/O) state machines |
6 | 6 | to implement one dynamically. |
7 | 7 |
|
8 | | -This I2S library uses the ``pico-extras`` I2S audio library and wraps it in |
9 | | -an Arduino I2S library. It supports 16 bits/sample and frequencies of up |
10 | | -to 48kHZ, with configurable BCLK, LRCLK(always pin "BCLK + 1"), and DOUT pins. |
| 8 | +Digital audio input and output are supported at 8, 16, 24, and 32 bits per |
| 9 | +sample. |
| 10 | + |
| 11 | +Theoretically up to 6 I2S ports may be created, but in practice there |
| 12 | +may not be enough resources (DMA, PIO SM) to actually create and use so |
| 13 | +many. |
| 14 | + |
| 15 | +Create an I2S port by instantiating a variable of the I2S class |
| 16 | +specifying the direction. Configure it using API calls below before |
| 17 | +using it. |
11 | 18 |
|
12 | | -**Note:** This I2S device takes over the entire PIO1 (second) unit and adjusts |
13 | | -its clock frequency to meet the I2S needs. That means when only 4 Tones |
14 | | -or only 4 Servos may be used when the I2S device is used. |
15 | 19 |
|
16 | 20 | I2S Class API |
17 | 21 | ------------- |
18 | 22 |
|
| 23 | +I2S(OUTPUT) |
| 24 | +~~~~~~~~~~~ |
| 25 | +Creates an I2S output port. Needs to be connected up to the |
| 26 | +desired pins (see below) and started before any output can happen. |
| 27 | + |
| 28 | +I2S(INPUT) |
| 29 | +~~~~~~~~~~ |
| 30 | +Creates an I2S input port. Needs to be connected up to the |
| 31 | +desired pins (see below) and started before any input can happen. |
| 32 | + |
19 | 33 | bool setBCLK(pin_size_t pin) |
20 | 34 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
21 | 35 | Sets the BCLK pin of the I2S device. The LRCLK/word clock will be ``pin + 1`` |
22 | | -due to limitations of the PIO state machines. Call this before ``I2S.begin()`` |
23 | | -Default BCLK = 26, LRCLK = 27 |
| 36 | +due to limitations of the PIO state machines. Call this before ``I2S::begin()`` |
24 | 37 |
|
25 | | -bool setDOUT(pin_size_t pin) |
| 38 | +bool setDATA(pin_size_t pin) |
26 | 39 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
27 | | -Sets the DOUT pin of the I2S device. Any pin may be used. Default DOUT = 28 |
28 | | -Call before ``I2S.begin()`` |
29 | | - |
30 | | -bool begin(long sampleRate) |
31 | | -~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
32 | | -Start the I2S device up with the given sample rate. The pins selected above |
33 | | -will be turned to output and the I2S will begin to drive silence frames (all |
34 | | -zero) out. |
| 40 | +Sets the DOUT or DIN pin of the I2S device. Any pin may be used. |
| 41 | +Call before ``I2S::begin()`` |
| 42 | + |
| 43 | +bool setBitsPerSample(int bits) |
| 44 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 45 | +Specify how many bits per audio sample to read or write. Note that |
| 46 | +for 24-bit samples, audio samples must be left-aligned (i.e. bits 31...8). |
| 47 | +Call before ``I2S::begin()`` |
| 48 | + |
| 49 | +bool setBuffers(size_t buffers, size_t bufferWords, int32_t silenceSample = 0) |
| 50 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 51 | +Set the number of DMA buffers and their size in 32-bit words as well as |
| 52 | +the word to fill when no data is available to send to the I2S hardware. |
| 53 | +Call before ``I2S::begin()``. |
| 54 | + |
| 55 | +bool setFrequency(long sampleRate) |
| 56 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 57 | +Sets the word clock frequency, but does not start the I2S device if not |
| 58 | +already running. May be called after ``I2S::begin()`` to change the |
| 59 | +sample rate on-the-fly. |
| 60 | + |
| 61 | +bool begin()/begin(long sampleRate) |
| 62 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 63 | +Start the I2S device up with the given sample rate, or with the value set |
| 64 | +using the prior ``setFrequency`` call. |
35 | 65 |
|
36 | 66 | void end() |
37 | 67 | ~~~~~~~~~~ |
38 | | -Stops the I2S device. **Note, at present the memory allocated for I2S buffers |
39 | | -is not freed leading to a memory leak when ``end()`` is called. This is due |
40 | | -to the state of the ``pico-extras`` release which this code uses.** |
| 68 | +Stops the I2S device. |
41 | 69 |
|
42 | 70 | void flush() |
43 | 71 | ~~~~~~~~~~~~ |
44 | | -Sends any partial frames in memory to the I2S output device. They may NOT play |
45 | | -immediately. Potential use case for this call would be when the frequency of |
46 | | -the output will be changing. |
47 | | - |
48 | | -size_t write(uint8_t) |
49 | | -~~~~~~~~~~~~~~~~~~~~~ |
50 | | -Provided for compatibility, but not very useful. Writes a sample from 0...255 |
51 | | -to the I2S buffer. See ``write(int16_t)`` for a better one |
| 72 | +Waits until all the I2S buffers have been output. |
| 73 | + |
| 74 | +size_t write(uint8_t/int8_t/int16_t/int32_t) |
| 75 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 76 | +Writes a single sample of ``bitsPerSample`` to the buffer. It is up to the |
| 77 | +user to keep track of left/right channels. Note this writes data equivalent |
| 78 | +to one channel's data, not the size of the passed in variable (i.e. if you have |
| 79 | +a 16-bit sample size and ``write((int8_t)-5); write((int8_t)5);`` you will have |
| 80 | +written **2 samples** to the I2S buffer of whatever the I2S size, not a single |
| 81 | +16-bit sample. |
| 82 | + |
| 83 | +This call will block (wait) until space is available to actually write |
| 84 | +the data. |
| 85 | + |
| 86 | +size_t write(int32_t val, bool sync) |
| 87 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 88 | +Writes 32 bits of data to the I2S buffer (regardless of the configured I2S |
| 89 | +bit size). When ``sync`` is true, it will not return until the data has |
| 90 | +been writte. When ``sync`` is false, it will return ``0`` immediately if |
| 91 | +there is no space present in the I2S buffer. |
52 | 92 |
|
53 | 93 | size_t write(const uint8_t \*buffer, size_t size) |
54 | 94 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
55 | 95 | Transfers number of bytes from an application buffer to the I2S output buffer. |
56 | 96 | Be aware that ``size`` is in *bytes** and not samples. Size must be a multiple |
57 | | -of **4 bytes** (i.e. one left/right sample). Will not block, so check |
58 | | -the return value to find out how many bytes were actually written. |
| 97 | +of **4 bytes**. Will not block, so check the return value to find out how |
| 98 | +many bytes were actually written. |
59 | 99 |
|
60 | 100 | int availableForWrite() |
61 | 101 | ~~~~~~~~~~~~~~~~~~~~~~~ |
62 | | -Returns the number of **32-bit L/R samples** that can be written without |
| 102 | +Returns the number of L/R samples that can be written without |
63 | 103 | potentially blocking. |
64 | 104 |
|
65 | | -bool setFrequency(int newFreq) |
66 | | -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
67 | | -Adjusts the I2S output frequency. When changing frequency while I2S output |
68 | | -is underway, be sure to use ``I2S.flush()`` before changing the frequency to |
69 | | -ensure the older data is played at the right frequency. |
70 | | - |
71 | | -size_t write(int16_t) |
72 | | -~~~~~~~~~~~~~~~~~~~~~ |
73 | | -Writes a single 16-bit left or right sample to the I2S output buffer. The |
74 | | -user is required to ensure that an even number of samples is written (i.e. |
75 | | -left and right) over the application lifetime. The application also needs |
76 | | -to track which sample is next to be written (right/left). For this reason, |
77 | | -the ``write(void *b, size_t lrsamples)`` call may be easier and faster to use. |
78 | | - |
79 | | -size_t write(const void \*buffer, size_t lrsamples) |
80 | | -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
81 | | -Writes up to size left+right packed samples to the I2S device. Non-blocking, |
82 | | -will writefrom 0...size samples and return that count. Be sure your app |
83 | | -handles partial writes (i.e. by ``yield()`` ing and then retrying to write the |
84 | | -remaining data.) |
85 | | - |
86 | | -The ``onTransmit`` callback is not supported. |
87 | | - |
88 | | -See the `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>`_ library |
89 | | -for a working example, or look at the included sample tone generator. |
| 105 | +int read() |
| 106 | +~~~~~~~~~~ |
| 107 | +Reads a single sample of I2S data, whatever the I2S sample size is configured. |
| 108 | +Will not return until data is available. |
| 109 | + |
| 110 | +int peek() |
| 111 | +~~~~~~~~~~ |
| 112 | +Returns the next sample to be read from the I2S buffer (without actually |
| 113 | +removing it). |
| 114 | + |
| 115 | +void onTransmit(void (\*fn)(void)) |
| 116 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 117 | +Sets a callback to be called when an I2S DMA buffer is fully transmitted. |
| 118 | +Will be in an interrupt context so the specified function must operate |
| 119 | +quickly and not use blocking calls like delay() or write to the I2S. |
| 120 | + |
| 121 | +void onReceive(void (\*fn)(void)) |
| 122 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 123 | +Sets a callback to be called when an I2S DMA buffer is fully read in. |
| 124 | +Will be in an interrupt context so the specified function must operate |
| 125 | +quickly and not use blocking calls like delay() or read from the I2S. |
| 126 | + |
| 127 | +Sample Writing/Reading API |
| 128 | +-------------------------- |
| 129 | +Because I2S streams consist of a natural left and right sample, it is often |
| 130 | +convenient to write or read both with a single call. The following calls |
| 131 | +allow applications to read or write both samples at the same time, and |
| 132 | +explicitly indicate the bit widths required (to avoid potential issues with |
| 133 | +type conversion on calls). |
| 134 | + |
| 135 | +size_t write8(int8_t l, int8_t r) |
| 136 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 137 | +Writes a left and right 8-bit sample to the I2S buffers. Blocks until space |
| 138 | +is available. |
| 139 | + |
| 140 | +size_t write16(int16_t l, int16_t r) |
| 141 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 142 | +Writes a left and right 16-bit sample to the I2S buffers. Blocks until space |
| 143 | +is available. |
| 144 | + |
| 145 | +size_t write24(int32_t l, int32_t r) |
| 146 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 147 | +Writes a left and right 24-bit sample to the I2S buffers. See note below |
| 148 | +about 24-bit mode. Blocks until space is available. |
| 149 | + |
| 150 | +size_t write32(int32_t l, int32_t r) |
| 151 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 152 | +Writes a left and right 32-bit sample to the I2S buffers. Blocks until space |
| 153 | +is available. |
| 154 | + |
| 155 | +bool read8(int8_t \*l, int8_t \*r) |
| 156 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 157 | +Reads a left and right 8-bit sample and returns ``true`` on success. Will block |
| 158 | +until data is available. |
| 159 | + |
| 160 | +bool read16(int16_t \*l, int16_t \*r) |
| 161 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 162 | +Reads a left and right 16-bit sample and returns ``true`` on success. Will block |
| 163 | +until data is available. |
| 164 | + |
| 165 | +bool read24(int32_t \*l, int32_t \*r) |
| 166 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 167 | +Reads a left and right 24-bit sample and returns ``true`` on success. See note below |
| 168 | +about 24-bit mode. Will block until data is available. |
| 169 | + |
| 170 | +bool read32(int32_t \*l, int32_t \*r) |
| 171 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 172 | +Reads a left and right 32-bit sample and returns ``true`` on success. Will block |
| 173 | +until data is available. |
| 174 | + |
| 175 | + |
| 176 | +Note About 24-bit Samples |
| 177 | +------------------------- |
| 178 | +24-bit samples are stored as left-aligned 32-bit values with bits 7..0 |
| 179 | +ignored. Only the upper 24 bits 31...8 will be transmitted or |
| 180 | +received. The actual I2S protocol will only transmit or receive 24 bits |
| 181 | +in this mode, even though the data is 32-bit packed. |
0 commit comments