documentation: update ESP32's documentation about the I2S RX mode

Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst

@@ -110,8 +110,10 @@ I2S
 ESP32 has two I2S peripherals accessible using either the generic I2S audio
 driver or a specific audio codec driver
 (`CS4344 <https://www.cirrus.com/products/cs4344-45-48/>`__ bindings are
-available at the moment). Also, it's possible to use the I2S character device
-driver to bypass audio systems and write directly to the I2S peripheral.
+available at the moment). The generic I2S audio driver enables using both
+the receiver module (RX) and the transmitter module (TX) without using any
+specific codec. Also, it's possible to use the I2S character device driver
+to bypass the audio subsystem and write directly to the I2S peripheral.
 
 .. note:: The I2S peripheral is able to work on two functional modes
   internally: 16 and 32-bit width.
@@ -134,6 +136,11 @@ driver to bypass audio systems and write directly to the I2S peripheral.
   aligned to the next boundary i.e. 16 bits for the 8 and 16-bit-widths and
   32 bits for 24 and 32-bit-widths.
 
+The following configurations use the I2S peripheral::
+  * :ref:`platforms/xtensa/esp32/boards/esp32-devkitc/index:audio`
+  * :ref:`platforms/xtensa/esp32/boards/esp32-devkitc/index:i2schar`
+  * :ref:`platforms/xtensa/esp32/boards/esp32-devkitc/index:nxlooper`
+
 Pin Mapping
 ===========
 
@@ -189,15 +196,15 @@ browser:
 
 After successfully built and flashed, connect the board to the Wi-Fi network::
 
-  $ nsh> wapi psk wlan0 mypasswd 1
-  $ nsh> wapi essid wlan0 myssid 1
-  $ nsh> renew wlan0
+  nsh> wapi psk wlan0 mypasswd 1
+  nsh> wapi essid wlan0 myssid 1
+  nsh> renew wlan0
 
 Once connected, open NuttX's player and play the file according to its file
 name and the IP address of the HTTP server::
 
-  $ nsh> nxplayer
-  $ nxplayer> play http://192.168.1.239:8000/tones.wav
+  nsh> nxplayer
+  nxplayer> play http://192.168.1.239:8000/tones.wav
 
 efuse
 -----
@@ -208,12 +215,35 @@ i2schar
 -------
 
 This configuration enables the I2S character device and the i2schar example
-app, which provides an easy-to-use way of testing the I2S peripheral (I2S0
-on this example).
+app, which provides an easy-to-use way of testing the I2S peripherals (I2S0
+and I2S1), enabling both the TX and the RX for those peripherals.
+
+**I2S0 pinout**
+
+========== ========== =========================================
+ESP32 Pin  Signal Pin Description
+========== ========== =========================================
+0          MCLK       Master Clock
+4          BCLK       Bit Clock (SCLK)
+5          WS         Word Select (LRCLK)
+18         DOUT       Data Out
+19         DIN        Data IN
+========== ========== =========================================
+
+**I2S1 pinout**
+
+========== ========== =========================================
+ESP32 Pin  Signal Pin Description
+========== ========== =========================================
+22         BCLK       Bit Clock (SCLK)
+23         WS         Word Select (LRCLK)
+25         DOUT       Data Out
+26         DIN        Data IN
+========== ========== =========================================
 
 After successfully built and flashed, run on the boards's terminal::
 
-  $ i2schar
+  i2schar -p /dev/i2schar[0-1]
 
 The corresponding output should show related debug informations.
 
@@ -319,6 +349,61 @@ nsh
 Basic NuttShell configuration (console enabled in UART0, exposed via
 USB connection by means of CP2102 converter, at 115200 bps).
 
+nxlooper
+--------
+
+This configuration uses the I2S1 peripheral as an I2S receiver and the I2S0
+peripheral as an I2S transmitter. The idea is to capture an I2S data frame
+using an I2S peripheral and reproduce the captured data on the other.
+
+**Receiving data on I2S1**
+
+The I2S1 will act as a receiver (master mode), capturing data from DIN, which
+needs to be connected to an external source as follows:
+
+========== ========== =========================================
+ESP32 Pin  Signal Pin Description
+========== ========== =========================================
+22         BCLK       Bit Clock (SCLK)
+23         WS         Word Select (LRCLK)
+26         DIN        Data IN
+========== ========== =========================================
+
+**Transmitting data on I2S0**
+
+The I2S0 will act as a transmitter (master mode), replicating the data
+captured on I2S1. The pinout for the transmitter is as follows:
+
+========== ========== =========================================
+ESP32 Pin  Signal Pin Description
+========== ========== =========================================
+0          MCLK       Master Clock
+4          BCLK       Bit Clock (SCLK)
+5          WS         Word Select (LRCLK)
+18         DOUT       Data Out
+========== ========== =========================================
+
+.. note:: The audio codec CS4344 can be connected to the transmitter pins
+  to reproduce the captured data if the receiver's source is an audio data.
+
+**nxlooper**
+
+The `nxlooper` application captures data from the audio device with receiving
+capabilities (the I2S1 on this example) and forwards the audio data frame to
+the audio device with transmitting capabilities (the I2S0 on this example).
+
+After successfully built and flashed, run on the boards's terminal::
+
+  nsh> nxlooper
+  nxlooper> loopback
+
+.. note:: `loopback` command default arguments for the channel configuration,
+  the data width and the sample rate are, respectively, 2 channels,
+  16 bits/sample and 48KHz. These arguments can be supplied to select
+  different audio formats, for instance::
+
+    nxlooper> loopback 2 8 44100
+
 ostest
 ------