esp32,stm32: Add new machine.I2S class for I2S protocol support.

This commit adds I2S protocol support for the esp32 and stm32 ports, via
a new machine.I2S class.  It builds on the stm32 work of blmorris, #1361.

Features include:
- a consistent I2S API across the esp32 and stm32 ports
- I2S configurations supported:
  - master transmit and master receive
  - 16-bit and 32-bit sample sizes
  - mono and stereo formats
  - sampling frequency
  - 3 modes of operation:
    - blocking
    - non-blocking with callback
    - uasyncio
  - internal ring buffer size can be tuned
- documentation for Pyboards and esp32-based boards
- tested on the following development boards:
  - Pyboard D SF2W
  - Pyboard V1.1
  - ESP32 with SPIRAM
  - ESP32

Signed-off-by: Mike Teachman <mike.teachman@gmail.com>

1 files changed, 18 insertions, 0 deletions

diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
index 77c7027c4..0b825d520 100644
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -385,6 +385,24 @@ has the same methods as software I2C above::
     i2c = I2C(0)
     i2c = I2C(1, scl=Pin(5), sda=Pin(4), freq=400000)
 
+I2S bus
+-------
+
+See :ref:`machine.I2S <machine.I2S>`. ::
+
+    from machine import I2S, Pin
+    
+    i2s = I2S(0, sck=Pin(13), ws=Pin(14), sd=Pin(34), mode=I2S.TX, bits=16, format=I2S.STEREO, rate=44100, ibuf=40000) # create I2S object
+    i2s.write(buf)             # write buffer of audio samples to I2S device
+    
+    i2s = I2S(1, sck=Pin(33), ws=Pin(25), sd=Pin(32), mode=I2S.RX, bits=16, format=I2S.MONO, rate=22050, ibuf=40000) # create I2S object
+    i2s.readinto(buf)          # fill buffer with audio samples from I2S device
+    
+The I2S class is currently available as a Technical Preview.  During the preview period, feedback from 
+users is encouraged.  Based on this feedback, the I2S class API and implementation may be changed.
+
+ESP32 has two I2S buses with id=0 and id=1
+
 Real time clock (RTC)
 ---------------------