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 `__ -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 ` 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:: +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] +========== ============= +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:: +SMI GPIO pins (default option) are as following: - ESP32 GPIO PHY Chip GPIO - IO18 <--> MDIO - IO23 <--> MDC +========== ============= +ESP32 GPIO PHY Chip GPIO +========== ============= +IO18 MDIO +IO23 MDC +========== ============= -Functional GPIO pins(default option) are as following:: +Functional GPIO pins(default option) are as following: - ESP32 GPIO PHY Chip GPIO - IO5 <--> Reset_N +========== ============= +ESP32 GPIO PHY Chip GPIO +========== ============= +IO5 Reset_N +========== ============= Espressif has an `official Ethernet development board `_. @@ -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 `__ 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:: - - $ 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 - -wifinsh +mcp2515 ------- -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 is used to communicate with MCP2515 CAN over SPI chip. +SPI3 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 +===== ======= +5 CS +18 SCK +23 MOSI +19 MISO +===== ======= - $ make menuconfig - -> Application Configuration - -> Network Utilities - -> Network initialization (NETUTILS_NETINIT [=y]) - -> WAPI Configuration +The MCP2515 interrupt (INT) pin is connected to the pin 22 of the +ESP32-Devkit. -Find your board IP using ``nsh> ifconfig`` and then from your computer:: +mmcsdspi +-------- - $ telnet 192.168.x.y +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.: -Where x and y are the last two numbers of the IP that your router gave to -your board. +===== ======= +Pin Signal +===== ======= +15 CS +14 SCK +13 MOSI +12 MISO +===== ======= + +Once booted the following command is used to mount a FAT file system:: + + nsh> mount -t vfat /dev/mmcsd0 /mnt + +module +------ + +This config is to run apps/examples/module. mqttc ----- @@ -211,6 +316,39 @@ outputted:: From the host the message :code:`test` should be outputted. +nsh +--- + +Basic NuttShell configuration (console enabled in UART0, exposed via +USB connection by means of CP2102 converter, at 115200 bps). + +ostest +------ + +This is the NuttX test at apps/testing/ostest that is run against all new +architecture ports to assure a correct implementation of the OS. The default +version is for a single CPU but can be modified for an SMP test by adding:: + + CONFIG_SMP=y + CONFIG_SMP_NCPUS=2 + CONFIG_SPINLOCK=y + +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 + smp --- @@ -231,51 +369,6 @@ The apps/testing/smp test is included:: CONFIG_TESTING_SMP_PRIORITY=100 CONFIG_TESTING_SMP_STACKSIZE=2048 -ostest ------- - -This is the NuttX test at apps/testing/ostest that is run against all new -architecture ports to assure a correct implementation of the OS. The default -version is for a single CPU but can be modified for an SMP test by adding:: - - CONFIG_SMP=y - 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 - -The MCP2515 interrupt (INT) pin is connected to the pin 22 of the -ESP32-Devkit. - -mmcsdspi --------- - -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.:: - - CS --> 15 - SCK --> 14 - MOSI --> 13 - MISO --> 12 - -Once booted the following command is used to mount a FAT file system:: - - nsh> mount -t vfat /dev/mmcsd0 /mnt - -module ------- - -This config is to run apps/examples/module. - 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 `_. 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 `_. 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 `. + Using QEMU ==========