You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2022/09/30 20:23:26 UTC
[incubator-nuttx] 03/03: xtensa/esp32: add documentation of the I2S/audio support on ESP32
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-nuttx.git
commit fc9b9f70ac4bada26e4915cf390e881c81136b65
Author: Tiago Medicci Serrano <ti...@espressif.com>
AuthorDate: Thu Sep 29 11:52:36 2022 -0300
xtensa/esp32: add documentation of the I2S/audio support on ESP32
---
Documentation/introduction/detailed_support.rst | 20 +-
.../esp32-devkitc/esp32-audio-config-file.png | Bin 0 -> 21276 bytes
.../xtensa/esp32/boards/esp32-devkitc/index.rst | 374 ++++++++++++++-------
Documentation/platforms/xtensa/esp32/index.rst | 38 ++-
4 files changed, 277 insertions(+), 155 deletions(-)
diff --git a/Documentation/introduction/detailed_support.rst b/Documentation/introduction/detailed_support.rst
index e297e7325e..61b49d9737 100644
--- a/Documentation/introduction/detailed_support.rst
+++ b/Documentation/introduction/detailed_support.rst
@@ -3025,27 +3025,21 @@ ESP32 (Dual Xtensa LX6)
Xtensa LX6 ESP32
----------------
-Basic architectural support for Xtensa LX6 processors and the port for
-the Espressif ESP32 were added in NuttX-7.19. The basic ESP32 port is
-function in both single CPU and dual CPU SMP configurations.
+Initial architectural support for Xtensa LX6 processors for the Espressif
+ESP32 were added in NuttX-7.19, enabling both single CPU and dual CPU
+SMP configurations.
**Espressif ESP32 DevkitC V4 Board** The NuttX release includes support for
Espressif ESP32 DevkitC V4 board. There is an NSH configuration for each
CPU configuration and an OS test configuration for verification of the
port.
-**STATUS**. ESP32 support in NuttX-7.19 is functional, but very
-preliminary. There is little yet in the way of device driver support.
-Outstanding issues include missing clock configuration logic, missing
-partition tables to support correct configuration from FLASH, and some
-serial driver pin configuration issues. The configuration is usable
-despite these limitations. Refer to the NuttX board
-`README <https://github.com/apache/incubator-nuttx/blob/master/boards/xtensa/esp32/esp32-devkitc/README.txt>`__
-file for further information.
-
-Release NuttX-10.0.0 brought a bunch of additions to the ESP32 port. This
+**STATUS**. Release NuttX-10.0.0 brought a bunch of additions to the ESP32 port. This
includes: I2C, SPI, RTC, PM, Timers, Watchdog Timer and Ethernet.
+Please, refer to the :doc:`ESP32 </platforms/xtensa/esp32/index>` on NuttX for
+further information.
+
Zilog ZNEO Z16F
===============
diff --git a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/esp32-audio-config-file.png b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/esp32-audio-config-file.png
new file mode 100644
index 0000000000..c51fa32e29
Binary files /dev/null and b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/esp32-audio-config-file.png differ
diff --git a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
index db01f6e0b2..ef589cfcb2 100644
--- a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
+++ b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
@@ -65,27 +65,36 @@ connect to an external PHY chip. Current driver also only supports RMII option.
The RMII GPIO pins are fixed, but the SMI and functional GPIO pins are optional.
-RMII GPIO pins are as following::
-
- ESP32 GPIO PHY Chip GPIO
- IO25 <--> RXD[0]
- IO26 <--> RXD[1]
- IO27 <--> CRS_DV
- IO0 <--> REF_CLK
- IO19 <--> TXD[0]
- IO21 <--> TX_EN
- IO22 <--> TXD[1]
-
-SMI GPIO pins (default option) are as following::
-
- ESP32 GPIO PHY Chip GPIO
- IO18 <--> MDIO
- IO23 <--> MDC
-
-Functional GPIO pins(default option) are as following::
-
- ESP32 GPIO PHY Chip GPIO
- IO5 <--> Reset_N
+RMII GPIO pins are as following:
+
+========== =============
+ESP32 GPIO PHY Chip GPIO
+========== =============
+IO25 RXD[0]
+IO26 RXD[1]
+IO27 CRS_DV
+IO0 REF_CLK
+IO19 TXD[0]
+IO21 TX_EN
+IO22 TXD[1]
+========== =============
+
+SMI GPIO pins (default option) are as following:
+
+========== =============
+ESP32 GPIO PHY Chip GPIO
+========== =============
+IO18 MDIO
+IO23 MDC
+========== =============
+
+Functional GPIO pins(default option) are as following:
+
+========== =============
+ESP32 GPIO PHY Chip GPIO
+========== =============
+IO5 Reset_N
+========== =============
Espressif has an `official Ethernet development
board <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-ethernet-kit.html>`_.
@@ -95,6 +104,39 @@ board + LAN8720 module. If users have some issue about using this driver,
please refer the upper official document, specially the issue that GPIO0
causes failing to bring the ESP32 chip up.
+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.
+
+.. note:: The I2S peripheral is able to work on two functional modes
+ internally: 16 and 32-bit width.
+ That limits using the I2S peripheral to play audio files other than 16/32
+ bit-widths as the internal buffer allocated for the audio content does not
+ consider the operation modes of the peripheral. This limitation is planned
+ to be removed soon by copying the buffers internally and making the
+ necessary adjustments.
+
+.. note:: The above statement is not valid when using the I2S character
+ device driver.
+ It's possible to use 8, 16, 24, and 32-bit-widths writing directly to the
+ I2S character device. Just make sure to set the bit-width::
+
+ $ make menuconfig
+ -> System Type
+ -> ESP32 Peripheral Selection
+ -> I2S
+ -> I2S0/1
+ -> Bit Witdh
+
+ And make sure the data stream buffer being written to the I2S peripheral is
+ 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.
+
Pin Mapping
===========
@@ -109,11 +151,74 @@ Pin Signal Notes
Configurations
==============
-nsh
----
+audio
+-----
-Basic NuttShell configuration (console enabled in UART0, exposed via
-USB connection by means of CP2102 converter, at 115200 bps).
+This configuration uses the I2S0 peripheral and an externally connected audio
+codec to play an audio file streamed over an HTTP connection while connected
+to a Wi-Fi network.
+
+**Audio Codec Setup**
+
+The CS4344 audio codec is connected on the following pins:
+
+========== ========== =========================================
+ESP32 Pin CS4344 Pin Description
+========== ========== =========================================
+0 MCLK Master Clock
+4 SCLK Serial Clock
+5 LRCK Left Right Clock (Word Select)
+18 SDIN Serial Data In on CS4344. (DOUT on ESP32)
+========== ========== =========================================
+
+**Simple HTTP server**
+
+Prepare a PCM-encoded (`.wav`) audio file with 16 bits/sample (sampled at
+8~48kHz). This file must be placed into a folder in a computer that could
+be accessed on the same Wi-Fi network the ESP32 will be connecting to.
+
+Python provides a simple HTTP server. `cd` to the audio file folder on the
+PC and run::
+
+ $ python3 -m http.server
+
+ Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
+
+Look for your PC IP address and test playing the prepared audio on your
+browser:
+
+.. figure:: esp32-audio-config-file.png
+ :align: center
+
+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
+
+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
+
+efuse
+-----
+
+A config with EFUSE enabled.
+
+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).
+
+After successfully built and flashed, run on the boards's terminal::
+
+ $ i2schar
+
+The corresponding output should show related debug informations.
knsh
----
@@ -137,47 +242,47 @@ Flash and PSRAM).
* The PID Controller **does not** prevent the application from accessing
CPU System Registers.
-wapi
-----
-
-Enables Wi-Fi support. You can define your credentials this way::
+mcp2515
+-------
- $ make menuconfig
- -> Application Configuration
- -> Network Utilities
- -> Network initialization (NETUTILS_NETINIT [=y])
- -> WAPI Configuration
+This config is used to communicate with MCP2515 CAN over SPI chip.
+SPI3 is used and kept with the default IOMUX pins, i.e.:
-Or if you don't want to keep it saved in the firmware you can do it
-at runtime::
+===== =======
+Pin Signal
+===== =======
+5 CS
+18 SCK
+23 MOSI
+19 MISO
+===== =======
- nsh> wapi psk wlan0 mypasswd 1
- nsh> wapi essid wlan0 myssid 1
- nsh> renew wlan0
+The MCP2515 interrupt (INT) pin is connected to the pin 22 of the
+ESP32-Devkit.
-wifinsh
--------
+mmcsdspi
+--------
-The ``wifinsh`` is similar to the ``wapi`` board example, but it will connect
-automatically to your Access Point (Wi-Fi Router) and will run telnet daemon
-in the board. Then you can connect to your board from your computer using the
-telnet program.
+This config tests the SPI driver by connecting an SD Card reader over SPI.
+SPI2 is used and kept with the default IOMUX pins, i.e.:
-After configuring the ``esp32-devkit:wifinsh`` you need to define your creden-
-tials in the menuconfig. You can define your credentials this way::
+===== =======
+Pin Signal
+===== =======
+15 CS
+14 SCK
+13 MOSI
+12 MISO
+===== =======
- $ make menuconfig
- -> Application Configuration
- -> Network Utilities
- -> Network initialization (NETUTILS_NETINIT [=y])
- -> WAPI Configuration
+Once booted the following command is used to mount a FAT file system::
-Find your board IP using ``nsh> ifconfig`` and then from your computer::
+ nsh> mount -t vfat /dev/mmcsd0 /mnt
- $ telnet 192.168.x.y
+module
+------
-Where x and y are the last two numbers of the IP that your router gave to
-your board.
+This config is to run apps/examples/module.
mqttc
-----
@@ -211,25 +316,11 @@ outputted::
From the host the message :code:`test` should be outputted.
-smp
+nsh
---
-Another NSH configuration, similar to nsh, but also enables
-SMP operation. It differs from the nsh configuration only in these
-additional settings:
-
-SMP is enabled::
-
- CONFIG_SMP=y
- CONFIG_SMP_NCPUS=2
- CONFIG_SPINLOCK=y
-
-The apps/testing/smp test is included::
-
- CONFIG_TESTING_SMP=y
- CONFIG_TESTING_SMP_NBARRIER_THREADS=8
- CONFIG_TESTING_SMP_PRIORITY=100
- CONFIG_TESTING_SMP_STACKSIZE=2048
+Basic NuttShell configuration (console enabled in UART0, exposed via
+USB connection by means of CP2102 converter, at 115200 bps).
ostest
------
@@ -242,39 +333,41 @@ version is for a single CPU but can be modified for an SMP test by adding::
CONFIG_SMP_NCPUS=2
CONFIG_SPINLOCK=y
-mcp2515
--------
-
-This config is used to communicate with MCP2515 CAN over SPI chip.
-SPI3 is used and kept with the default IOMUX pins, i.e.::
-
- CS --> 5
- SCK --> 18
- MOSI --> 23
- MISO --> 19
+psram
+-----
-The MCP2515 interrupt (INT) pin is connected to the pin 22 of the
-ESP32-Devkit.
+This config tests the PSRAM driver over SPIRAM interface.
+You can use the ramtest command to test the PSRAM memory. We are testing
+only 64KB on this example (64 * 1024), but you can change this number to
+2MB or 4MB depending on PSRAM chip used on your board::
-mmcsdspi
---------
+ nsh> ramtest -w 0x3F800000 65536
+ RAMTest: Marching ones: 3f800000 65536
+ RAMTest: Marching zeroes: 3f800000 65536
+ RAMTest: Pattern test: 3f800000 65536 55555555 aaaaaaaa
+ RAMTest: Pattern test: 3f800000 65536 66666666 99999999
+ RAMTest: Pattern test: 3f800000 65536 33333333 cccccccc
+ RAMTest: Address-in-address test: 3f800000 65536
-This config tests the SPI driver by connecting an SD Card reader over SPI.
-SPI2 is used and kept with the default IOMUX pins, i.e.::
+smp
+---
- CS --> 15
- SCK --> 14
- MOSI --> 13
- MISO --> 12
+Another NSH configuration, similar to nsh, but also enables
+SMP operation. It differs from the nsh configuration only in these
+additional settings:
-Once booted the following command is used to mount a FAT file system::
+SMP is enabled::
- nsh> mount -t vfat /dev/mmcsd0 /mnt
+ CONFIG_SMP=y
+ CONFIG_SMP_NCPUS=2
+ CONFIG_SPINLOCK=y
-module
-------
+The apps/testing/smp test is included::
-This config is to run apps/examples/module.
+ CONFIG_TESTING_SMP=y
+ CONFIG_TESTING_SMP_NBARRIER_THREADS=8
+ CONFIG_TESTING_SMP_PRIORITY=100
+ CONFIG_TESTING_SMP_STACKSIZE=2048
sotest
------
@@ -295,22 +388,6 @@ Once booted you can use the following commands to mount the file system::
Note that mksmartfs is only needed the first time.
-psram
------
-
-This config tests the PSRAM driver over SPIRAM interface.
-You can use the ramtest command to test the PSRAM memory. We are testing
-only 64KB on this example (64 * 1024), but you can change this number to
-2MB or 4MB depending on PSRAM chip used on your board::
-
- nsh> ramtest -w 0x3F800000 65536
- RAMTest: Marching ones: 3f800000 65536
- RAMTest: Marching zeroes: 3f800000 65536
- RAMTest: Pattern test: 3f800000 65536 55555555 aaaaaaaa
- RAMTest: Pattern test: 3f800000 65536 66666666 99999999
- RAMTest: Pattern test: 3f800000 65536 33333333 cccccccc
- RAMTest: Address-in-address test: 3f800000 65536
-
timer
-----
@@ -324,19 +401,6 @@ To test it, just run the following::
Where x in the timer instance.
-watchdog
---------
-
-This config test the watchdog timers. It includes the 2 MWDTS,
-adds driver support, registers the WDTs as devices and includes the watchdog
-example.
-
-To test it, just run the following::
-
- nsh> wdog -d /dev/watchdogx
-
-Where x in the watchdog instance.
-
wamr_wasi_debug
---------------
@@ -375,7 +439,57 @@ This example uses littlefs on ESP32's SPI flash to store wasm modules.
nsh> mount -t littlefs /dev/esp32flash /mnt
nsh> iwasm /mnt/....
-efuse
------
+wapi
+----
-A config with EFUSE enabled.
+Enables Wi-Fi support. You can define your credentials this way::
+
+ $ make menuconfig
+ -> Application Configuration
+ -> Network Utilities
+ -> Network initialization (NETUTILS_NETINIT [=y])
+ -> WAPI Configuration
+
+Or if you don't want to keep it saved in the firmware you can do it
+at runtime::
+
+ nsh> wapi psk wlan0 mypasswd 1
+ nsh> wapi essid wlan0 myssid 1
+ nsh> renew wlan0
+
+watchdog
+--------
+
+This config test the watchdog timers. It includes the 2 MWDTS,
+adds driver support, registers the WDTs as devices and includes the watchdog
+example.
+
+To test it, just run the following::
+
+ nsh> wdog -d /dev/watchdogx
+
+Where x in the watchdog instance.
+
+wifinsh
+-------
+
+The ``wifinsh`` is similar to the ``wapi`` board example, but it will connect
+automatically to your Access Point (Wi-Fi Router) and will run telnet daemon
+in the board. Then you can connect to your board from your computer using the
+telnet program.
+
+After configuring the ``esp32-devkit:wifinsh`` you need to define your creden-
+tials in the menuconfig. You can define your credentials this way::
+
+ $ make menuconfig
+ -> Application Configuration
+ -> Network Utilities
+ -> Network initialization (NETUTILS_NETINIT [=y])
+ -> WAPI Configuration
+
+Find your board IP using ``nsh> ifconfig`` and then from your computer::
+
+ $ telnet 192.168.x.y
+
+Where x and y are the last two numbers of the IP that your router gave to
+your board.
diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst
index 7cb1a258f5..6e5eec9ad9 100644
--- a/Documentation/platforms/xtensa/esp32/index.rst
+++ b/Documentation/platforms/xtensa/esp32/index.rst
@@ -55,8 +55,8 @@ These steps are given in the setup guide in
Flashing
========
-Firmware for ESP32 is flashed via the USB/UART interface using the ``esptool.py`` tool.
-It's a two step process where the first converts the ELF file into a ESP32-compatible binary
+Firmware for ESP32 is flashed via the USB/UART interface using the ``esptool.py`` tool.
+It's a two step process where the first converts the ELF file into a ESP32-compatible binary
and the second flashes it to the board. These steps are included into the build system and you can
flash your NuttX firmware simply by running::
@@ -68,7 +68,7 @@ Bootloader and partitions
-------------------------
ESP32 requires a bootloader to be flashed as well as a set of FLASH partitions. This is only needed the first time
-(or any time you which to modify either of these). An easy way is to use prebuilt binaries for NuttX `from here <https://github.com/espressif/esp-nuttx-bootloader>`_. In there you will find instructions to rebuild these if necessary.
+(or any time you which to modify either of these). An easy way is to use prebuilt binaries for NuttX `from here <https://github.com/espressif/esp-nuttx-bootloader>`_. In there you will find instructions to rebuild these if necessary.
Once you downloaded both binaries, you can flash them by adding an ``ESPTOOL_BINDIR`` parameter, pointing to the directory where these binaries were downloaded:
.. code-block:: console
@@ -79,7 +79,7 @@ Once you downloaded both binaries, you can flash them by adding an ``ESPTOOL_BIN
SPI FLASH erase.
.. code-block:: console
-
+
$ esptool.py erase_flash
Peripheral Support
@@ -90,12 +90,12 @@ The following list indicates the state of peripherals' support in NuttX:
========== ======= =====
Peripheral Support NOTES
========== ======= =====
-GPIO Yes
+GPIO Yes
UART Yes
-SPI Yes
-I2C Yes
-DMA Yes
-Wifi Yes
+SPI Yes
+I2C Yes
+DMA Yes
+Wifi Yes
Ethernet Yes
SPIFLASH Yes
SPIRAM Yes
@@ -109,13 +109,14 @@ ADC No
Bluetooth Yes
SDIO No
SD/MMC No
-I2S No
-LED_PWM No
+I2S Yes
+LED_PWM Yes
RMT No
MCPWM No
Pulse_CNT No
SHA No
RSA No
+CAN/TWAI Yes
========== ======= =====
Memory Map
@@ -290,7 +291,7 @@ Wi-Fi SoftAP
============
It is possible to use ESP32 as an Access Point (SoftAP). Actually there are some
-boards with a ``sta_softap`` which enables this support.
+boards config examples called sta_softap which enables this support
If you are using this board config profile you can run these commands to be able
to connect your smartphone or laptop to your board::
@@ -350,6 +351,19 @@ Enter in the NSH shell using your preferred serial console tool and run the scan
advertiser data: 1e ff 06 00 01 09 20 02 7c 33 a3 a7 cd c9 44 5b
nsh>
+I2S
+===
+
+The I2S peripheral is accessible using either the generic I2S audio driver or a specific
+audio codec driver. Also, it's possible to use the I2S character driver to bypass the
+audio subsystem and develop specific usages of the I2S peripheral.
+
+.. note:: Note that the bit-width and sample rate can be modified "on-the-go" when using
+ audio-related drivers. That is not the case for the I2S character device driver and
+ such parameters are set on compile time through `make menuconfig`.
+
+Please check for usage examples using the :doc:`ESP32 DevKitC </platforms/xtensa/esp32/boards/esp32-devkitc/index>`.
+
Using QEMU
==========