Bi-directional I2S support (earlephilhower#2775)

* Initial bi-directional I2S support.

* Formatting update on pioasm file.

* Added loopback example.

* Updated documentation.

* Fix `getOverUnderflow` naming.

* Revert `getOverUnderflow` naming changes.

* Remove python cache file.

* Remove `availableForRead`.

* Updated naming convention of OverUnderflow methods.

* Update constructor to prevent conflicts with existing code.

* Avoid ambiguous `setDATA` in bi-directional mode.

* Use only input buffer manager in `available`.

* Fix input checks in `read` and `peek`.

* Fix erroneous comment.

* Update pio_i2s.pio to pio v1.

* Change pio_i2s.pio back to pio v0.

Author: relic-se

docs/i2s.rst

@@ -30,14 +30,31 @@ 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.
 
+I2S(INPUT_PULLUP)
+~~~~~~~~~~~~~~~~~
+Creates a bi-directional I2S input and output port.  Needs to be
+connected up to the desired pins (see below) and started before
+any input or output 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()``
 
 bool setDATA(pin_size_t pin)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sets the DOUT or DIN pin of the I2S device.  Any pin may be used.
+Sets the DOUT or DIN pin of the I2S device.  Any pin may be used. In bi-directional
+operation, must use ``I2S::setDOUT()`` and ``I2S::setDIN`` instead.
+Call before ``I2S::begin()``
+
+bool setDOUT(pin_size_t pin)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the DOUT pin of the I2S device.  Any pin may be used.
+Call before ``I2S::begin()``
+
+bool setDIN(pin_size_t pin)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sets the DIN pin of the I2S device.  Any pin may be used.
 Call before ``I2S::begin()``
 
 bool setMCLK(pin_size_t pin)
@@ -115,6 +132,14 @@ void getOverUnderflow()
 Returns a flag indicating if the I2S system ran our of data to send on output,
 or had to throw away data on input.
 
+void getOverflow()
+~~~~~~~~~~~~~~~~~~~~~~~
+Returns a flag indicating if the I2S system had to throw away data on input.
+
+void getUnderflow()
+~~~~~~~~~~~~~~~~~~~~~~~
+Returns a flag indicating if the I2S system ran our of data to send on 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

libraries/I2S/examples/I2SLoopback/I2SLoopback.ino

@@ -0,0 +1,36 @@
+/*
+   I2S bi-directional input and output loopback example
+   Released to the Public Domain by Cooper Dalrymple
+*/
+
+#include <I2S.h>
+
+I2S i2s(INPUT_PULLUP);
+
+void setup() {
+  Serial.begin(115200);
+
+  i2s.setDOUT(0);
+  i2s.setDIN(1);
+  i2s.setBCLK(2); // Note: LRCLK = BCLK + 1
+  i2s.setBitsPerSample(16);
+  i2s.setFrequency(22050);
+  // NOTE: The following values are known to work with the Adafruit microphone:
+  // i2s.setBitsPerSample(32);
+  // i2s.setFrequency(16000);
+  i2s.begin();
+
+  while (1) {
+    int16_t l, r;
+    i2s.read16(&l, &r);
+    i2s.write16(l, r);
+    // NOTE: Adafruit microphone word size needs to match the BPS above.
+    // int32_t l, r;
+    // i2s.read32(&l, &r);
+    // i2s.write32(l, r);
+  }
+}
+
+void loop() {
+  /* Nothing here */
+}