Rewrite I2S from scratch, add input support

.github/workflows/pull-request.yml

@@ -20,8 +20,8 @@ jobs:
     - name: Run codespell
       uses: codespell-project/actions-codespell@master
       with:
-        skip: ./pico-extras,./ArduinoCore-API,./libraries/ESP8266SdFat,./libraries/Adafruit_TinyUSB_Arduino,./libraries/LittleFS/lib,./tools/pyserial,./pico-sdk,./.github,./docs/i2s.rst,./cores/rp2040/api,./libraries/FreeRTOS
-        ignore_words_list: ser,DOUT
+        skip: ./ArduinoCore-API,./libraries/ESP8266SdFat,./libraries/Adafruit_TinyUSB_Arduino,./libraries/LittleFS/lib,./tools/pyserial,./pico-sdk,./.github,./docs/i2s.rst,./cores/rp2040/api,./libraries/FreeRTOS
+        ignore_words_list: ser,dout
 
 # Consistent style
   astyle:
@@ -81,8 +81,6 @@ jobs:
       run: |
         cd pico-sdk
         git submodule update --init
-        cd ../pico-extras
-        git submodule update --init
         cd ..
         bash ./tests/build.sh
 
@@ -111,8 +109,6 @@ jobs:
       run: |
         cd pico-sdk
         git submodule update --init
-        cd ../pico-extras
-        git submodule update --init
         cd ..
         bash ./tests/build-tinyusb.sh
 
@@ -147,8 +143,6 @@ jobs:
         try { Get-Command python3 } catch { copy (get-command python).source (get-command python).source.Replace("python.exe", "python3.exe") }
         cd pico-sdk
         git submodule update --init
-        cd ../pico-extras
-        git submodule update --init
         cd ..
         bash ./tests/build.sh
 
@@ -181,8 +175,6 @@ jobs:
       run: |
         cd pico-sdk
         git submodule update --init
-        cd ../pico-extras
-        git submodule update --init
         cd ..
         bash ./tests/build.sh
 

.gitmodules

@@ -13,9 +13,6 @@
 [submodule "libraries/SdFat"]
 	path = libraries/ESP8266SdFat
 	url = https://github.com/earlephilhower/ESP8266SdFat.git
-[submodule "pico-extras"]
-	path = pico-extras
-	url = https://github.com/raspberrypi/pico-extras.git
 [submodule "libraries/Keyboard"]
 	path = libraries/Keyboard
 	url = https://github.com/earlephilhower/Keyboard

README.md

@@ -70,8 +70,6 @@ cd ~/Arduino/hardware/pico/rp2040
 git submodule update --init
 cd pico-sdk
 git submodule update --init
-cd ../pico-extras
-git submodule update --init
 cd ../tools
 python3 ./get.py
 `````
@@ -145,12 +143,13 @@ The installed tools include a version of OpenOCD (in the pqt-openocd directory)
 * Multicore support (setup1() and loop1())
 * Overclocking and underclocking from the menus
 * digitalWrite/Read, shiftIn/Out, tone, analogWrite(PWM)/Read, temperature
-* Peripherals:  SPI master, Wire(I2C) master/slave, dual UART, emulated EEPROM, I2S audio output, Servo
+* Peripherals:  SPI master, Wire(I2C) master/slave, dual UART, emulated EEPROM, I2S audio input, I2S audio output, Servo
 * printf (i.e. debug) output over USB serial
 
 The RP2040 PIO state machines (SMs) are used to generate jitter-free:
 * Servos
 * Tones
+* I2S Input
 * I2S Output
 * Software UARTs (Serial ports)
 
@@ -168,7 +167,7 @@ If you want to contribute or have bugfixes, drop me a note at <earlephilhower@ya
 # Licensing and Credits
 * The [Arduino IDE and ArduinoCore-API](https://arduino.cc) are developed and maintained by the Arduino team. The IDE is licensed under GPL.
 * The [RP2040 GCC-based toolchain](https://github.com/earlephilhower/pico-quick-toolchain) is licensed under under the GPL.
-* The [Pico-SDK](https://github.com/raspberrypi/pico-sdk) and [Pico-Extras](https://github.com/raspberrypi/pico-extras) are by Raspberry Pi (Trading) Ltd and licensed under the BSD 3-Clause license.
+* The [Pico-SDK](https://github.com/raspberrypi/pico-sdk) is by Raspberry Pi (Trading) Ltd and licensed under the BSD 3-Clause license.
 * [Arduino-Pico](https://github.com/earlephilhower/arduino-pico) core files are licensed under the LGPL.
 * [LittleFS](https://github.com/ARMmbed/littlefs) library written by ARM Limited and released under the [BSD 3-clause license](https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md).
 * [UF2CONV.PY](https://github.com/microsoft/uf2) is by Microsoft Corporation and licensed under the MIT license.

docs/i2s.rst

@@ -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.

libraries/I2S/examples/I2SInput/I2SInput.ino

@@ -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 */
+}