[FEATURE] Basic implementation of Arduino's I2S library

CMakeLists.txt

@@ -86,6 +86,7 @@ set(LIBRARY_SRCS
   libraries/HTTPClient/src/HTTPClient.cpp
   libraries/HTTPUpdate/src/HTTPUpdate.cpp
   libraries/LittleFS/src/LittleFS.cpp
+  libraries/I2S/src/I2S.cpp
   libraries/NetBIOS/src/NetBIOS.cpp
   libraries/Preferences/src/Preferences.cpp
   libraries/RainMaker/src/RMaker.cpp
@@ -161,7 +162,6 @@ set(BLE_SRCS
   libraries/BLE/src/GeneralUtils.cpp
   )
 
-
 set(includedirs
   variants/${IDF_TARGET}/
   cores/esp32/
@@ -178,6 +178,7 @@ set(includedirs
   libraries/HTTPClient/src
   libraries/HTTPUpdate/src
   libraries/LittleFS/src
+  libraries/I2S/src
   libraries/NetBIOS/src
   libraries/Preferences/src
   libraries/RainMaker/src
@@ -233,6 +234,8 @@ function(maybe_add_component component_name)
     endif()
 endfunction()
 
+maybe_add_component(esp-dsp)
+
 if(IDF_TARGET MATCHES "esp32" AND CONFIG_ESP_RMAKER_TASK_STACK)
     maybe_add_component(esp_rainmaker)
     maybe_add_component(qrcode)

libraries/I2S/examples/ADCPlotter/ADCPlotter.ino

@@ -0,0 +1,86 @@
+/*
+ This example is only for ESP devices.
+
+ This example demonstrates usage of integrated Digital to Analog Converter (DAC)
+ You can display sound wave from audio device, or just measure voltage.
+
+ To display audio prepare circuit found in following link or drafted as ASCII art
+ https://forum.arduino.cc/index.php?topic=567581.0
+ (!) Note that unlike in the link we are connecting the supply line to 3.3V (not 5V)
+ because ADC can measure only up to around 3V. Anything above 3V will be very inaccurate.
+
+                      ^ +3.3V
+                      |
+                      _
+                     | |10k
+                     |_|
+                      |            | |10uF
+   GPIO34-------------*------------| |----------- line in
+(Default ADC pin)     |           +| |      
+                      |
+                      _
+                     | |10k
+                     |_|
+                      |
+                      |
+                      V GND
+
+Connect hot wire of your audio to Line in and GNd wire of audio cable to common ground (GND)
+
+Second option to measure voltage on trimmer / potentiometer has following connection
+                      ^ +3.3V
+                      |
+                      _
+                     | |
+   GPIO34----------->| |
+(Default ADC pin)    |_|
+                      |
+                      |
+                      _
+                     | | optional resistor
+                     |_|
+                      |
+                      |
+                      V GND
+ Optional resistor will decrease read value.
+
+ Steps to run:
+ 1. Select target board:
+   Tools -> Board -> ESP32 Arduino -> your board
+ 2. Upload sketch
+   Press upload button (arrow in top left corner)
+   When you see in console line like this: "Connecting........_____.....__"
+     On your board press and hold Boot button and press EN button shortly. Now you can release both buttons.
+     You should see lines like this: "Writing at 0x00010000... (12 %)" with rising percentage on each line.
+     If this fails, try the board buttons right after pressing upload button, or reconnect the USB cable.
+ 3. Open plotter
+   Tools -> Serial Plotter
+     Enjoy
+
+Created by Tomas Pilny
+on 17th June 2021
+*/
+
+#include <I2S.h>
+
+void setup() {
+  // Open serial communications and wait for port to open:
+  // A baud rate of 115200 is used instead of 9600 for a faster data rate
+  // on non-native USB ports
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+
+  // start I2S at 8 kHz with 32-bits per sample
+  if (!I2S.begin(ADC_DAC_MODE, 8000, 16)) {
+    Serial.println("Failed to initialize I2S!");
+    while (1); // do nothing
+  }
+}
+
+void loop() {
+  // read a sample
+  int sample = I2S.read();
+  Serial.println(sample);
+}

libraries/I2S/examples/FullDuplex/FullDuplex.ino

@@ -0,0 +1,59 @@
+/*
+ This example is only for ESP
+ This example demonstrates simultaneous usage of microphone and speaker using single I2S module.
+ The application transfers data from input to output
+
+ Circuit:
+ * ESP32
+   * GND connected GND
+   * VIN connected 5V
+   * SCK 5
+   * FS 25
+   * DIN 35
+   * DOUT 26
+ * I2S microphone
+ * I2S decoder + headphones / speaker
+
+ created 8 October 2021
+ by Tomas Pilny
+ */
+
+#include <I2S.h>
+const long sampleRate = 16000;
+const int bitsPerSample = 32;
+uint8_t *buffer;
+
+void setup() {
+  Serial.begin(115200);
+  //I2S.setAllPins(5, 25, 35, 26); // you can change default pins; order of pins = (CLK, WS, IN, OUT)
+  if(!I2S.setDuplex()){
+    Serial.println("ERROR - could not set duplex");
+    while(true){
+      vTaskDelay(10); // Cannot continue
+    }
+  }
+  if (!I2S.begin(I2S_PHILIPS_MODE, sampleRate, bitsPerSample)) {
+    Serial.println("Failed to initialize I2S!");
+    while(true){
+      vTaskDelay(10); // Cannot continue
+    }
+  }
+  buffer = (uint8_t*) malloc(I2S.getBufferSize() * (bitsPerSample / 8));
+  if(buffer == NULL){
+    Serial.println("Failed to allocate buffer!");
+    while(true){
+      vTaskDelay(10); // Cannot continue
+    }
+  }
+  Serial.println("Setup done");
+}
+
+void loop() {
+  //I2S.write(I2S.read()); // primitive implementation sample-by-sample
+
+  // Buffer based implementation
+  I2S.read(buffer, I2S.getBufferSize() * (bitsPerSample / 8));
+  I2S.write(buffer, I2S.getBufferSize() * (bitsPerSample / 8));
+
+  //optimistic_yield(1000); // yield if last yield occurred before <parameter> CPU clock cycles ago
+}

libraries/I2S/examples/InputSerialPlotter/InputSerialPlotter.ino

@@ -0,0 +1,44 @@
+/*
+ This example reads audio data from an Invensense's ICS43432 I2S microphone
+ breakout board, and prints out the samples to the Serial console. The
+ Serial Plotter built into the Arduino IDE can be used to plot the audio
+ data (Tools -> Serial Plotter)
+
+ Circuit:
+ * Arduino/Genuino Zero, MKR family and Nano 33 IoT
+ * ICS43432:
+   * GND connected GND
+   * 3.3V connected to 3.3V (Zero, Nano, ESP32), VCC (MKR)
+   * WS connected to pin 0 (Zero) or 3 (MKR), A2 (Nano) or 25 (ESP32)
+   * CLK connected to pin 1 (Zero) or 2 (MKR), A3 (Nano) or 5 (ESP32)
+   * SD connected to pin 9 (Zero) or A6 (MKR), 4 (Nano) or 26 (ESP32)
+ created 17 November 2016
+ by Sandeep Mistry
+ */
+
+#include <I2S.h>
+
+void setup() {
+  // Open serial communications and wait for port to open:
+  // A baud rate of 115200 is used instead of 9600 for a faster data rate
+  // on non-native USB ports
+  Serial.begin(115200);
+  while (!Serial) {
+    ; // wait for serial port to connect. Needed for native USB port only
+  }
+
+  // start I2S at 8 kHz with 32-bits per sample
+  if (!I2S.begin(I2S_PHILIPS_MODE, 8000, 32)) {
+    Serial.println("Failed to initialize I2S!");
+    while (1); // do nothing
+  }
+}
+
+void loop() {
+  // read a sample
+  int sample = I2S.read();
+
+  if (sample && sample != -1 && sample != 1) {
+    Serial.println(sample);
+  }
+}

libraries/I2S/examples/SimpleTone/SimpleTone.ino

@@ -0,0 +1,79 @@
+/*
+ This example generates a square wave based tone at a specified frequency
+ and sample rate. Then outputs the data using the I2S interface to a
+ MAX08357 I2S Amp Breakout board.
+
+ I2S Circuit:
+ * Arduino/Genuino Zero, MKR family and Nano 33 IoT
+ * MAX08357:
+   * GND connected GND
+   * VIN connected 5V
+   * LRC connected to pin 0 (Zero) or 3 (MKR), A2 (Nano) or 25 (ESP32)
+   * BCLK connected to pin 1 (Zero) or 2 (MKR), A3 (Nano) or 5 (ESP32)
+   * DIN connected to pin 9 (Zero) or A6 (MKR), 4 (Nano) or 26 (ESP32)
+
+ DAC Circuit:
+ * ESP32 or ESP32-S2
+ * Audio amplifier
+   - Note:
+     - ESP32 has DAC on GPIO pins 25 and 26.
+     - ESP32-S2 has DAC on GPIO pins 17 and 18.
+  - Connect speaker(s) or headphones.
+
+ created 17 November 2016
+ by Sandeep Mistry
+ For ESP extended
+ Tomas Pilny
+ 2nd September 2021
+ */
+
+#include <I2S.h>
+const int frequency = 440; // frequency of square wave in Hz
+const int amplitude = 500; // amplitude of square wave
+const int sampleRate = 8000; // sample rate in Hz
+const int bps = 16;
+
+const int halfWavelength = (sampleRate / frequency); // half wavelength of square wave
+
+short sample = amplitude; // current sample value
+int count = 0;
+
+i2s_mode_t mode = I2S_PHILIPS_MODE; // I2S decoder is needed
+// i2s_mode_t mode = ADC_DAC_MODE; // Audio amplifier is needed
+
+// Mono channel input
+// This is ESP specific implementation -
+//   samples will be automatically copied to both channels inside I2S driver
+//   If you want to have true mono output use I2S_PHILIPS_MODE and interlay
+//   second channel with 0-value samples.
+//   The order of channels is RIGH followed by LEFT
+//i2s_mode_t mode = I2S_RIGHT_JUSTIFIED_MODE; // I2S decoder is needed
+
+void setup() {
+  Serial.begin(115200);
+  Serial.println("I2S simple tone");
+
+  // start I2S at the sample rate with 16-bits per sample
+  if (!I2S.begin(mode, sampleRate, bps)) {
+    Serial.println("Failed to initialize I2S!");
+    while (1); // do nothing
+  }
+}
+
+void loop() {
+    if (count % halfWavelength == 0 ) {
+      // invert the sample every half wavelength count multiple to generate square wave
+      sample = -1 * sample;
+    }
+
+    if(mode == I2S_PHILIPS_MODE || mode == ADC_DAC_MODE){ // write the same sample twice, once for Right and once for Left channel
+      I2S.write(sample); // Right channel
+      I2S.write(sample); // Left channel
+    }else if(mode == I2S_RIGHT_JUSTIFIED_MODE || mode == I2S_LEFT_JUSTIFIED_MODE){
+      // write the same only once - it will be automatically copied to the other channel
+      I2S.write(sample);
+    }
+
+    // increment the counter for the next sample
+    count++;
+}

libraries/I2S/keywords.txt

@@ -0,0 +1,61 @@
+#######################################
+# Syntax Coloring Map I2S
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+I2S	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+I2SClass	KEYWORD2
+begin	KEYWORD2
+end	KEYWORD2
+
+onReceive	KEYWORD2
+onTransmit	KEYWORD2
+
+setSckPin	KEYWORD2
+setFsPin	KEYWORD2
+setDataInPin	KEYWORD2
+setDataOutPin	KEYWORD2
+setAllPins	KEYWORD2
+
+getSckPin	KEYWORD2
+getFsPin	KEYWORD2
+getDataPin	KEYWORD2
+getDataInPin	KEYWORD2
+getDataOutPin	KEYWORD2
+
+setDuplex	KEYWORD2
+setSimplex	KEYWORD2
+isDuplex	KEYWORD2
+
+setBufferSize	KEYWORD2
+getBufferSize	KEYWORD2
+
+write	KEYWORD2
+availableForWrite	KEYWORD2
+
+read	KEYWORD2
+available	KEYWORD2
+
+gpioToAdcUnit	KEYWORD2
+gpioToAdcChannel	KEYWORD2
+
+#######################################
+# Constants (LITERAL1)
+#######################################
+I2S_PHILIPS_MODE	LITERAL1
+I2S_RIGHT_JUSTIFIED_MODE	LITERAL1
+I2S_LEFT_JUSTIFIED_MODE	LITERAL1
+I2S_ADC_DAC	LITERAL1
+I2S_PDM	LITERAL1
+
+PIN_I2S_SCK	LITERAL1
+PIN_I2S_FS	LITERAL1
+PIN_I2S_SD	LITERAL1
+PIN_I2S_SD_OUT	LITERAL1

libraries/I2S/library.properties

@@ -0,0 +1,9 @@
+name=I2S
+version=1.0
+author=Tomas Pilny
+maintainer=Tomas Pilny <[email protected]>
+sentence=Enables the communication with devices that use the Inter-IC Sound (I2S) Bus. Specific implementation for ESP.
+paragraph=
+category=Communication
+url=http://www.arduino.cc/en/Reference/I2S
+architectures=esp32