Documentation: Improve pages for ESP boards

Documentation/introduction/detailed_support.rst

@@ -3040,6 +3040,17 @@ Espressif ESP32-C3 Devkit board.
 Please, refer to the :doc:`ESP32-C3 </platforms/risc-v/esp32c3/index>` on NuttX for
 further information.
 
+ESP32-C6
+--------
+
+Initial architectural support for ESP32-C6 (RISC-V) was added in NuttX-12.1.0
+
+**Espressif ESP32-C6 Devkit Board** The NuttX release includes support for
+Espressif ESP32-C6 Devkit board.
+
+Please, refer to the :doc:`ESP32-C6 </platforms/risc-v/esp32c6/index>` on NuttX for
+further information.
+
 ESP32 (Dual Xtensa LX6)
 =======================
 

Documentation/introduction/supported_platforms.rst

@@ -70,6 +70,7 @@ from board-to-board. Follow the links for the details:
 
          - :ref:`introduction/detailed_support:LiteX on Arty A7` (1)
          - :ref:`introduction/detailed_support:ESP32-C3` (1)
+         - :ref:`introduction/detailed_support:ESP32-C6` (1)
 
        - Xtensa LX6:
 

Documentation/platforms/risc-v/esp32c3/index.rst

@@ -49,10 +49,10 @@ First make sure that ``esptool.py`` is installed.  This tool is used to convert
 the ELF to a compatible ESP32 image and to flash the image into the board.
 It can be installed with: ``pip install esptool``.
 
-Configure the NUttX project: ``./tools/configure.sh esp32c3-devkit:nsh``
+Configure the NuttX project: ``./tools/configure.sh esp32c3-devkit:nsh``
 Run ``make`` to build the project.  Note that the conversion mentioned above is
-included in the build process.  
+included in the build process.
-The `esptool.py` command to flash all the binaries is::
+The ``esptool.py`` command to flash all the binaries is::
 
      esptool.py --chip esp32c3 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin
 
@@ -60,7 +60,7 @@ However, this is also included in the build process and we can build and flash w
 
    make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
 
-Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is 
+Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is
 the path to the folder containing the bootloader and the partition table
 for the ESP32-C3 as explained above.
 Note that this step is required only one time.  Once the bootloader and partition
@@ -70,11 +70,11 @@ would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX``
 Debugging with OpenOCD
 ======================
 
-Download and build OpenOCD from Espressif, that can be found in 
+Download and build OpenOCD from Espressif, that can be found in
-https://github.com/espressif/openocd-esp32  
+https://github.com/espressif/openocd-esp32
 
 If you have an ESP32-C3 ECO3, no external JTAG is required to debug, the ESP32-C3
-integrates a USB-to-JTAG adapter.  
+integrates a USB-to-JTAG adapter.
 
 OpenOCD can then be used::
 
@@ -89,7 +89,7 @@ It can be connected as follows::
   TDO -> GPIO7
 
 Furthermore, an efuse needs to be burnt to be able to debug::
-  
+
   espefuse.py -p <port> burn_efuse DIS_USB_JTAG
 
 OpenOCD can then be used::
@@ -104,25 +104,26 @@ The following list indicates the state of peripherals' support in NuttX:
 =========== ======= =====
 Peripheral  Support NOTES
 =========== ======= =====
-GPIO         Yes       
+ADC          Yes
-UART         Yes
+AES          Yes
-SPI          Yes       
+Bluetooth    Yes
-I2C          Yes       
+CDC Console  Yes    Rev.3
-DMA          Yes       
+DMA          Yes
-Wifi         Yes       
+eFuse        Yes
+GPIO         Yes
+I2C          Yes
+LED_PWM      Yes
+RNG          Yes
+RSA          Yes
+RTC          Yes
+SHA          Yes
+SPI          Yes
 SPIFLASH     Yes
 Timers       Yes
+Touch        Yes
+UART         Yes
 Watchdog     Yes
-RTC          Yes
+Wifi         Yes
-RNG          Yes
-AES          Yes
-eFuse        Yes
-ADC          Yes
-Bluetooth    Yes
-LED_PWM      Yes
-SHA          Yes
-RSA          Yes
-CDC Console  Yes    Rev.3
 =========== ======= =====
 
 Secure Boot and Flash Encryption

Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkit/index.rst

@@ -0,0 +1,104 @@
+==================
+ESP32-C6-DevKitC-1
+==================
+
+ESP32-C6-DevKitC-1 is an entry-level development board based on ESP32-C6-WROOM-1(U),
+a general-purpose module with a 8 MB SPI flash. This board integrates complete Wi-Fi,
+Bluetooth LE, Zigbee, and Thread functions. You can find the board schematic
+`here <https://espressif-docs.readthedocs-hosted.com/projects/espressif-esp-dev-kits/en/latest/_static/esp32-c6-devkitc-1/schematics/esp32-c6-devkitc-1-schematics_v1.2.pdf>`_.
+
+Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing.
+Developers can either connect peripherals with jumper wires or mount ESP32-C6-DevKitC-1 on
+a breadboard.
+
+.. figure:: esp32-c6-devkitc-1-isometric_v1.2.png
+    :alt: ESP32-C6-DevKitC-1 Board Layout
+    :figclass: align-center
+
+    ESP32-C6-DevKitC-1 Board Layout
+
+The block diagram below presents main components of the ESP32-C6-DevKitC-1.
+
+.. figure:: esp32-c6-devkitc-1-v1.2-block-diagram.png
+    :alt: ESP32-C6-DevKitC-1 Electrical Block Diagram
+    :figclass: align-center
+
+    ESP32-C6-DevKitC-1 Electrical Block Diagram
+
+Hardware Components
+-------------------
+
+.. figure:: esp32-c6-devkitc-1-v1.2-annotated-photo.png
+    :alt: ESP32-C6-DevKitC-1 Hardware Components
+    :figclass: align-center
+
+    ESP32-C6-DevKitC-1 Hardware Components
+
+Buttons and LEDs
+================
+
+Board Buttons
+--------------
+There are two buttons labeled Boot and RST. The RST button is not available
+to software. It pulls the chip enable line that doubles as a reset line.
+
+The BOOT button is connected to IO9. On reset it is used as a strapping
+pin to determine whether the chip boots normally or into the serial
+bootloader. After reset, however, the BOOT button can be used for software
+input.
+
+Board LEDs
+----------
+
+There is one on-board LED that indicates the presence of power.
+Another WS2812 LED is connected to GPIO8 and is available for software.
+
+Current Measurement
+===================
+
+The J5 headers on the ESP32-C6-DevKitC-1 can be used for measuring the current
+drawn by the ESP32-C6-WROOM-1(U) module:
+
+    - Remove the jumper: Power supply between the module and peripherals on the
+      board is cut off. To measure the module's current, connect the board with an
+      ammeter via J5 headers;
+    - Apply the jumper (factory default): Restore the board's normal functionality.
+
+.. note::
+    When using 3V3 and GND pin headers to power the board, please remove the J5 jumper,
+    and connect an ammeter in series to the external circuit to measure the module's current.
+
+Pin Mapping
+===========
+
+.. figure:: esp32-c6-devkitc-1-pin-layout.png
+    :alt: ESP32-C6-DevKitC pin layout
+    :figclass: align-center
+
+    ESP32-C6-DevKitC-1 Pin Layout
+
+Configurations
+==============
+
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32c6-devkit:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
+coremark
+--------
+
+This configuration sets the CoreMark benchmark up for running on the maximum
+number of cores for this system. It also enables some optimization flags and
+disables the NuttShell to get the best possible score.
+
+.. note:: As the NSH is disabled, the application will start as soon as the
+  system is turned on.
+
+nsh
+---
+
+Basic configuration to run the NuttShell (nsh).

Documentation/platforms/risc-v/esp32c6/index.rst

@@ -49,10 +49,10 @@ First make sure that ``esptool.py`` is installed.  This tool is used to convert
 the ELF to a compatible ESP32-C6 image and to flash the image into the board.
 It can be installed with: ``pip install esptool``.
 
-Configure the NUttX project: ``./tools/configure.sh esp32c6-devkit:nsh``
+Configure the NuttX project: ``./tools/configure.sh esp32c6-devkit:nsh``
 Run ``make`` to build the project.  Note that the conversion mentioned above is
-included in the build process.  
+included in the build process.
-The `esptool.py` command to flash all the binaries is::
+The ``esptool.py`` command to flash all the binaries is::
 
      esptool.py --chip esp32c6 --port /dev/ttyUSBXX --baud 921600 write_flash 0x0 bootloader.bin 0x8000 partition-table.bin 0x10000 nuttx.bin
 
@@ -60,9 +60,58 @@ However, this is also included in the build process and we can build and flash w
 
    make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=../esp-bins
 
-Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is 
+Where ``<port>`` is typically ``/dev/ttyUSB0`` or similar and ``../esp-bins`` is
 the path to the folder containing the bootloader and the partition table
 for the ESP32-C6 as explained above.
 Note that this step is required only one time.  Once the bootloader and partition
 table are flashed, we don't need to flash them again.  So subsequent builds
 would just require: ``make flash ESPTOOL_PORT=/dev/ttyUSBXX``
+
+Peripheral Support
+==================
+
+The following list indicates the state of peripherals' support in NuttX:
+
+==============  =======
+Peripheral      Support
+==============  =======
+ADC              No
+AES              No
+Bluetooth        No
+CAN/TWAI         No
+DMA              No
+ECC              No
+eFuse            No
+GPIO             No
+HMAC             No
+I2C              No
+I2S              No
+Int. Temp.       No
+LED              No
+LED_PWM          No
+MCPWM            No
+Pulse Counter    No
+RMT              No
+RNG              No
+RSA              No
+RTC              No
+SD/MMC           No
+SDIO             No
+SHA              No
+SPI              No
+SPIFLASH         No
+Timers           No
+UART             Yes
+Watchdog         Yes
+Wifi             No
+XTS              No
+==============  =======
+
+Supported Boards
+================
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   boards/*/*

Documentation/platforms/xtensa/esp32/boards/esp32-ethernet-kit/index.rst

@@ -0,0 +1,325 @@
+..
+    Ported from ESP-IDF documentation https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-ethernet-kit.html
+
+=======================
+ESP32-Ethernet-Kit V1.2
+=======================
+
+The ESP32-Ethernet-Kit is an Ethernet-to-Wi-Fi development board that enables Ethernet
+devices to be interconnected over Wi-Fi. At the same time, to provide more flexible power
+supply options, the ESP32-Ethernet-Kit also supports power over Ethernet (PoE).
+You can find the board schematic `here <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
+
+.. figure:: esp32-ethernet-kit-v1.2-overview.png
+    :alt: ESP32-Ethernet-Kit V1.2 Board Layout
+    :figclass: align-center
+
+    ESP32-Ethernet-Kit V1.2 Board Layout
+
+It consists of two development boards, the Ethernet board A and the PoE board B.
+The Ethernet board (A) contains Bluetooth/Wi-Fi dual-mode ESP32-WROVER-E module and IP101GRI,
+a Single Port 10/100 Fast Ethernet Transceiver (PHY). The PoE board (B) provides power over
+Ethernet functionality. The A board can work independently, without the board B installed.
+
+.. figure:: esp32-ethernet-kit-v1.2.jpg
+    :alt: ESP32-Ethernet-Kit V1.2
+    :figclass: align-center
+
+    ESP32-Ethernet-Kit V1.2
+
+For the application loading and monitoring, the Ethernet board (A) also features FTDI FT2232H
+chip - an advanced multi-interface USB bridge. This chip enables to use JTAG for direct debugging
+of ESP32 through the USB interface without a separate JTAG debugger.
+
+The block diagram below presents main components of the ESP32-Ethernet-Kit.
+
+.. figure:: esp32-ethernet-kit-v1.1-block-diagram.png
+    :alt: ESP32-Ethernet-Kit V1.2 Electrical Block Diagram
+    :figclass: align-center
+
+    ESP32-Ethernet-Kit V1.2 Electrical Block Diagram
+
+Features
+========
+
+    - ESP32-WROVER-E Module
+    - JTAG through USB
+    - Ethernet
+    - Power over Ethernet (PoE)
+    - USB-to-UART bridge via micro USB port
+
+Functional Description
+======================
+
+The following figures describe the key components, interfaces, and controls of the ESP32-Ethernet-Kit.
+
+Ethernet Board (A)
+------------------
+
+.. figure:: esp32-ethernet-kit-a-v1.2-layout.jpg
+    :alt: ESP32-Ethernet-Kit - Ethernet board (A) layout
+    :figclass: align-center
+
+    ESP32-Ethernet-Kit - Ethernet board (A) layout
+
+PoE Board (B)
+-------------
+
+This board converts power delivered over the Ethernet cable (PoE) to provide a power supply
+for the Ethernet board (A). The main components of the PoE board (B) are shown on the image below.
+
+.. figure:: esp32-ethernet-kit-b-v1.0-layout.png
+    :alt: ESP32-Ethernet-Kit - PoE board (B) layout
+    :figclass: align-center
+
+    ESP32-Ethernet-Kit - PoE board (B) layout
+
+The PoE board (B) has the following features:
+
+    - Support for IEEE 802.3at
+    - Power output: 5 V, 1.4 A
+
+To take advantage of the PoE functionality the RJ45 Port of the Ethernet board (A) should be connected
+with an Ethernet cable to a switch that supports PoE. When the Ethernet board (A) detects 5 V power output
+from the PoE board (B), the USB power will be automatically cut off.
+
+Function Switch
+===============
+
+When in On position, this DIP switch is routing listed GPIOs to FT2232H to provide JTAG functionality.
+When in Off position, the GPIOs may be used for other purposes.
+
+=======  ================
+DIP SW   GPIO Pin
+=======  ================
+ 1       GPIO13
+ 2       GPIO12
+ 3       GPIO15
+ 4       GPIO14
+=======  ================
+
+RMII Clock Selection
+====================
+
+The ethernet MAC and PHY under RMII working mode need a common 50 MHz reference clock (i.e. RMII clock)
+that can be provided either externally, or generated from internal ESP32 APLL (not recommended).
+
+RMII Clock Sourced Externally by PHY
+------------------------------------
+
+By default, the ESP32-Ethernet-Kit is configured to provide RMII clock for the IP101GRI PHY's 50M_CLKO output.
+The clock signal is generated by the frequency multiplication of 25 MHz crystal connected to the PHY.
+For details, please see the figure below.
+
+.. figure:: esp32-ethernet-kit-rmii-clk-from-phy.png
+    :align: center
+    :scale: 80%
+    :alt: RMII Clock from IP101GRI PHY
+    :figclass: align-center
+
+    RMII Clock from IP101GRI PHY
+
+Please note that the PHY is reset on power up by pulling the RESET_N signal down with a resistor.
+ESP32 should assert RESET_N high with GPIO5 to enable PHY. Only this can ensure the power-up of system.
+Otherwise ESP32 may enter download mode (when the clock signal of REF_CLK_50M is at a high logic level during
+the GPIO0 power-up sampling phase).
+
+
+RMII Clock Sourced Internally from ESP32's APLL
+-----------------------------------------------
+
+Another option is to source the RMII Clock from internal ESP32 APLL, see figure below.
+The clock signal coming from GPIO0 is first inverted, to account for transmission line delay,
+and then supplied to the PHY.
+
+.. figure:: esp32-ethernet-kit-rmii-clk-to-phy.png
+    :align: center
+    :scale: 80%
+    :alt: RMII Clock from ESP Internal APLL
+    :figclass: align-center
+
+    RMII Clock from ESP Internal APLL
+
+To implement this option, users need to remove or add some RC components on the board.
+For details please refer to the `ESP32-Ethernet-Kit V1.2 Ethernet board (A) schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_,
+sheet 2, location D2. Please note that if the APLL is already used for other purposes
+(e.g. I2S peripheral), then you have no choice but use an external RMII clock.
+
+Serial Console
+==============
+
+UART0 is, by default, the serial console. It connects to the on-board
+CP2102N bridge and is available on the USB connector.
+
+It will show up as /dev/ttyUSB[n] where [n] will probably be 0.
+
+Buttons and LEDs
+================
+
+Board Buttons
+-------------
+
+There are two buttons labeled Boot and EN. The EN button is not available
+to software. It pulls the chip enable line that doubles as a reset line.
+
+The BOOT button is connected to IO0. On reset it is used as a strapping
+pin to determine whether the chip boots normally or into the serial
+bootloader. After reset, however, the BOOT button can be used for software
+input.
+
+Board LEDs
+----------
+
+There are several on-board LEDs for that indicate the presence of power
+and USB activity. None of these are available for use by software.
+
+Pin Mapping
+===========
+
+.. csv-table::
+    :header: ESP32-WROVER-E,IP101GRI,UART,JTAG,GPIO,Comments
+
+    S_VP,,,,IO36,
+    S_VN,,,,IO39,
+    IO34,,,,IO34,
+    IO35,,,,IO35,
+    IO32,,,,IO32,
+    IO33,,,,IO33,
+    IO25,RXD[0],,,,
+    IO26,RXD[1],,,,
+    IO27,CRS_DV,,,,
+    IO14,,,TMS,IO14,
+    IO12,,,TDI,IO12,
+    IO13,,,TCK,IO13,
+    IO15,,,TDO,IO15,
+    IO2,,,,IO2,
+    IO0,REF_CLK,,,,See note 1
+    IO4,,,,IO4,
+    IO16,,,,IO16 (NC),See note 2
+    IO17,,,,IO17 (NC),See note 2
+    IO5,Reset_N,,,,See note 1
+    IO18,MDIO,,,,
+    IO19,TXD[0],,,,
+    IO21,TX_EN,,,,
+    RXD0,,RXD,,,
+    TXD0,,TXD,,,
+    IO22,TXD[1],,,,
+    IO23,MDC,,,,
+
+.. note::
+
+    1. To prevent the power-on state of the GPIO0 from being affected by the clock output on the PHY side,
+    the RESET_N signal to PHY defaults to low, turning the clock output off. After power-on you can control
+    RESET_N with GPIO5 to turn the clock output on. See also `RMII Clock Sourced Externally by PHY`_. For
+    PHYs that cannot turn off the clock output through RESET_N, it is recommended to use a crystal module
+    that can be disabled/enabled externally. Similarly like when using RESET_N, the oscillator module should
+    be disabled by default and turned on by ESP32 after power-up.
+    For a reference design please see `ESP32-Ethernet-Kit V1.2 Ethernet board (A) schematic <https://dl.espressif.com/dl/schematics/SCH_ESP32-Ethernet-Kit_A_V1.2_20200528.pdf>`_.
+
+    2. The ESP32 pins GPIO16 and GPIO17 are not broken out to the ESP32-WROVER-E module and therefore not available for use.
+
+Configurations
+==============
+
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32-ethernet-kit:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
+autopm
+------
+
+This configuration makes the device automatically enter the low power consumption mode
+when in the idle state, powering off the cpu and other peripherals.
+
+In minimum power save mode, the station wakes up every DTIM to receive a beacon. The broadcast
+data will not be lost because it is transmitted after DTIM. However, it can not save much more
+power if DTIM is short as the DTIM is determined by the access point.
+
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x01
+    nsh> Sample = 1
+    Sample = 0
+
+ethernet
+--------
+
+This configuration is similar to ``wifi`` but uses the Ethernet interface instead
+of the WiFi one. It also automatically configures the IP and DNS addresses of the
+device. It currently uses the following static configuration:
+
+    - IP: 192.168.15.100 (0xc0a80f64)
+    - Gateway: 192.168.15.1 (0xc0a80f01)
+    - Netmask: 255.255.255.0 (0xffffff00)
+    - DNS: 8.8.8.8 (0x08080808)
+
+nsh
+---
+
+Basic NuttShell configuration (console enabled in UART0, exposed via
+USB connection by means of CP2102 converter, at 115200 bps).
+
+oneshot
+-------
+
+This config demonstrate the use of oneshot timers present on the ESP32.
+To test it, just run the ``oneshot`` example::
+
+    nsh> oneshot
+    Opening /dev/oneshot
+    Maximum delay is 4294967295999999
+    Starting oneshot timer with delay 2000000 microseconds
+    Waiting...
+    Finished
+
+rtc
+---
+
+This configuration demonstrates the use of the RTC driver through alarms.
+You can set an alarm, check its progress and receive a notification after it expires::
+
+    nsh> alarm 10
+    alarm_daemon started
+    alarm_daemon: Running
+    Opening /dev/rtc0
+    Alarm 0 set in 10 seconds
+    nsh> alarm -r
+    Opening /dev/rtc0
+    Alarm 0 is active with 10 seconds to expiration
+    nsh> alarm_daemon: alarm 0 received
+
+tickless
+--------
+
+This configuration enables the support for tickless scheduler mode.
+
+wifi
+----
+
+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 3
+    nsh> wapi essid wlan0 myssid 1
+    nsh> renew wlan0

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

@@ -45,8 +45,8 @@ It will show up as /dev/ttyUSB[n] where [n] will probably be 0.
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 Two key labeled *Rec* and *Mode*. They are routed to **ESP32-WROVER-E Module**
 and intended for developing and testing a UI for audio applications using
@@ -72,8 +72,8 @@ Entering of the ESP32 into upload mode may be done in two ways:
   by installing jumpers in three headers **JP23**, **JP24** and **JP25**.
   Remove all jumpers after upload is complete.
 
-LEDs
+Board LEDs
-----
+----------
 
 A general purpose green LED controlled by the **ESP32-WROVER-E Module** to
 indicate certain operation states of the audio application using dedicated
@@ -390,6 +390,14 @@ JTAG Header / JP7
 Configurations
 ==============
 
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32-lyrat:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
 audio
 -----
 
@@ -433,13 +441,78 @@ name and the IP address of the HTTP server (For example `tones.wav` and
     The codec implementation on the LyraT board was validated using 16-bit,
     44.1kHz WAV files. Other configurations might not work as expected.
 
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x01
+    nsh> Sample = 1
+    Sample = 0
+
+.. note::
+    The ``BOOT`` is connected to GPIO0 that is shared among some peripherals.
+    To avoid any conflicts, it's not registered in the buttons subsystem and, thus,
+    is unable to be used.
+
+mmcsdspi
+--------
+
+This configuration is used to mount a FAT/FAT32 SD Card into the OS' filesystem.
+For the ESP32-LyraT, make sure the DIP switches 1 and 2 are turned to the ON position.
+To access the card's files, execute the following commands::
+
+    nsh> mount -t vfat /dev/mmcsd0 /mnt
+    nsh> ls /mnt/
+    /mnt:
+    song_16_88200_2ch.wav
+    song_16_96000_2ch.wav
+    song_24_44100_2ch.wav
+    song_32_44100_2ch.wav
+
 nsh
 ---
 
 Basic NuttShell configuration (console enabled in UART0, exposed via
 USB connection by means of the CP2102N bridge, at 115200 bps).
 
-wapi
+nxrecorder
+----------
+
+This configuration is used to record raw audio from the the ES8388 audio codec
+through the I2S0 peripheral to a FAT32 SD Card. By default the audio is recorded from
+the on-board microphones.
+For the ESP32-LyraT, make sure the DIP switches 1 and 2 are turned to the ON position.
+To record audio, execute the following commands::
+
+    nsh> mount -t vfat /dev/mmcsd0 /mnt
+    nsh> nxrecorder
+    nxrecorder> recordraw /mnt/record.raw
+    nxrecorder> stop
+
+To play the recorded audio, import the raw data into Audacity and set the encoding to signed
+16-bit PCM, the sample rate to 44.1kHz and the number of channels to 2.
+
+wifi
 ----
 
-Enables Wi-Fi support.
+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 3
+    nsh> wapi essid wlan0 myssid 1
+    nsh> renew wlan0

Documentation/platforms/xtensa/esp32/boards/esp32-wrover-kit/index.rst

@@ -30,7 +30,7 @@ for direct debugging of ESP32 through the USB interface without a separate
 JTAG debugger. ESP-WROVER-KIT makes development convenient, easy, and
 cost-effective.
 
-Most of the ESP32 I/O pins are broken out to the board’s pin headers for easy access.
+Most of the ESP32 I/O pins are broken out to the board's pin headers for easy access.
 
 Serial Console
 ==============
@@ -44,8 +44,8 @@ the first interface ([n] == 0) is dedicated to the USB-to-JTAG interface.
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 There are two buttons labeled Boot and EN. The EN button is not available
 to software. It pulls the chip enable line that doubles as a reset line.
@@ -55,8 +55,8 @@ pin to determine whether the chip boots normally or into the serial
 bootloader. After reset, however, the BOOT button can be used for software
 input.
 
-LEDs
+Board LEDs
-----
+----------
 
 There are several on-board LEDs for that indicate the presence of power
 and USB activity.
@@ -84,22 +84,55 @@ Pin   Signal                    Notes
 Configurations
 ==============
 
-nsh
+All of the configurations presented below can be tested by running the following commands::
----
 
-Basic NuttShell configuration (console enabled in UART0, exposed via
+    $ ./tools/configure.sh esp32-wrover-kit:<config_name>
-USB connection by means of FT2232HL converter, at 115200 bps).
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB1 -j
 
-wapi
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
-----
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
 
-Enables Wi-Fi support.
+autopm
+------
+
+This configuration makes the device automatically enter the low power consumption mode
+when in the idle state, powering off the cpu and other peripherals.
+
+In minimum power save mode, the station wakes up every DTIM to receive a beacon. The broadcast
+data will not be lost because it is transmitted after DTIM. However, it can not save much more
+power if DTIM is short as the DTIM is determined by the access point.
+
+bmp180
+------
+
+This configuration enables the use of the BMP180 pressure sensor over I2C.
+You can check that the sensor is working by using the ``bmp180`` application::
+
+    nsh> bmp180
+    Pressure value = 91531
+    Pressure value = 91526
+    Pressure value = 91525
+
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x01
+    nsh> Sample = 1
+    Sample = 0
 
 gpio
 ----
 
 This is a test for the GPIO driver. It includes the 3 LEDs and one, arbitrary, GPIO.
-For this example, GPIO22 was used.
+For this example, GPIO22 was used (defined by the board implementation).
 At the nsh, we can turn LEDs on and off with the following::
 
     nsh> gpio -o 1 /dev/gpio0
@@ -112,27 +145,49 @@ We can use the interrupt pin to send a signal when the interrupt fires::
 The pin is configured to as a rising edge interrupt, so after issuing the
 above command, connect it to 3.3V.
 
-spiflash
+lcd1602
---------
+-------
 
-This config tests the external SPI that comes with an ESP32 module connected
+This configuration is used to demonstrate the use of an LCD1602 display with
-through SPI1.
+the ESP32-WROVER-KIT. You can run an example by executing the following commands::
 
-By default a SmartFS file system is selected.
+    nsh> slcd
-Once booted you can use the following commands to mount the file system::
+    Opening /dev/slcd0 for read/write access
+    Attributes:
+    rows: 2 columns: 16 nbars: 0
+    max contrast: 0 max brightness: 1
+    Clear screen
+    WRITING:
+    0000: 1b5b46                                                            .[F
+    Set brightness to 1
+    Print [Hello]
+    WRITING:
+    0000: 1b5b471b5b30304c1b5b4548656c6c6f                                  .[G.[00L.[EHello
 
-    mksmartfs /dev/smart0
+leds
-    mount -t smartfs /dev/smart0 /mnt
+----
 
-Note that `mksmartfs` is only needed the first time.
+This configuration demonstrates the use of the on-board RGB LED with the
+`userleds` subsystem. To check the included example, you can execute the
+following application::
 
-nx
+    nsh> leds
---
+    leds_main: Starting the led_daemon
+    leds_main: led_daemon started
+    led_daemon (pid# 3): Running
+    led_daemon: Opening /dev/userleds
+    led_daemon: Supported LEDs 0x07
+    led_daemon: LED set 0x01
+    nsh> led_daemon: LED set 0x02
+    led_daemon: LED set 0x03
+    led_daemon: LED set 0x04
+    led_daemon: LED set 0x05
 
-This config adds a set of tests using the graphic examples at `apps/example/nx`.
+lua
+---
 
-This configuration illustrates the use of the LCD with the lower performance
+This configuration demonstrates the use of the of the Lua interpreter on NuttX.
-SPI interface.
+To execute it, just run the ``lua`` application.
 
 lvgl
 ----
@@ -145,10 +200,82 @@ driver. You can find LVGL here::
 
 This configuration uses the LVGL demonstration at `apps/examples/lvgldemo`.
 
-External devices
+mmcsdspi
-=================
+--------
 
-BMP180
+This configuration is used to mount a FAT/FAT32 SD Card into the OS' filesystem.
-------
+To access the card's files, execute the following commands::
 
-When using BMP180 (enabling ``CONFIG_SENSORS_BMP180``), it's expected this device is wired to I2C0 bus.
+    nsh> mount -t vfat /dev/mmcsd0 /mnt
+    nsh> ls /mnt/
+    /mnt:
+    song_16_88200_2ch.wav
+    song_16_96000_2ch.wav
+    song_24_44100_2ch.wav
+    song_32_44100_2ch.wav
+
+nsh
+---
+
+Basic NuttShell configuration (console enabled in UART0, exposed via
+USB connection by means of FT2232HL converter, at 115200 bps).
+
+nx
+--
+
+This config adds a set of tests using the graphic examples at ``apps/example/nx``.
+
+This configuration illustrates the use of the LCD with the lower performance
+SPI interface.
+
+oneshot
+-------
+
+This config demonstrate the use of oneshot timers present on the ESP32.
+To test it, just run the ``oneshot`` example::
+
+    nsh> oneshot
+    Opening /dev/oneshot
+    Maximum delay is 4294967295999999
+    Starting oneshot timer with delay 2000000 microseconds
+    Waiting...
+    Finished
+
+rtc
+---
+
+This configuration demonstrates the use of the RTC driver through alarms.
+You can set an alarm, check its progress and receive a notification after it expires::
+
+    nsh> alarm 10
+    alarm_daemon started
+    alarm_daemon: Running
+    Opening /dev/rtc0
+    Alarm 0 set in 10 seconds
+    nsh> alarm -r
+    Opening /dev/rtc0
+    Alarm 0 is active with 10 seconds to expiration
+    nsh> alarm_daemon: alarm 0 received
+
+tickless
+--------
+
+This configuration enables the support for tickless scheduler mode.
+
+wifi
+----
+
+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 3
+    nsh> wapi essid wlan0 myssid 1
+    nsh> renew wlan0

Documentation/platforms/xtensa/esp32/index.rst

@@ -90,33 +90,34 @@ The following list indicates the state of peripherals' support in NuttX:
 ========== ======= =====
 Peripheral Support NOTES
 ========== ======= =====
-GPIO         Yes
+ADC          No
-UART         Yes
+AES          Yes
-SPI          Yes
+Bluetooth    Yes
-I2C          Yes
+CAN/TWAI     Yes
 DMA          Yes
-Wifi         Yes
+eFuse        Yes
 Ethernet     Yes
+GPIO         Yes
+I2C          Yes
+I2S          Yes
+LED_PWM      Yes
+MCPWM        No
+Pulse_CNT    No
+RMT          No
+RNG          Yes
+RSA          No
+RTC          Yes
+SD/MMC       No
+SDIO         No
+SHA          No
+SPI          Yes
 SPIFLASH     Yes
 SPIRAM       Yes
 Timers       Yes
+Touch        Yes
+UART         Yes
 Watchdog     Yes
-RTC          Yes
+Wifi         Yes
-RNG          Yes
-AES          Yes
-eFuse        Yes
-ADC          No
-Bluetooth    Yes
-SDIO         No
-SD/MMC       No
-I2S          Yes
-LED_PWM      Yes
-RMT          No
-MCPWM        No
-Pulse_CNT    No
-SHA          No
-RSA          No
-CAN/TWAI     Yes
 ========== ======= =====
 
 Memory Map
@@ -285,7 +286,7 @@ In this case a connection to AP with SSID ``myssid`` is done, using ``mypasswd``
 password. IP address is obtained via DHCP using ``renew`` command. You can check
 the result by running ``ifconfig`` afterwards.
 
-.. tip:: Boards usually expose a ``wapi`` defconfig which enables Wi-Fi
+.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi
 
 Wi-Fi SoftAP
 ============
@@ -363,6 +364,9 @@ audio subsystem and develop specific usages of the I2S peripheral.
    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`.
 
+.. warning:: Some upper driver implementations might not handle both transmission and
+   reception configured at the same time on the same peripheral.
+
 Please check for usage examples using the :doc:`ESP32 DevKitC </platforms/xtensa/esp32/boards/esp32-devkitc/index>`.
 
 Using QEMU

Documentation/platforms/xtensa/esp32s2/boards/esp32s2-kaluga-1/index.rst

@@ -157,8 +157,8 @@ It will show up as /dev/ttyUSB[n] where [n] will probably be 0.
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 There are two buttons labeled Boot and EN. The EN button is not available
 to the software. It pulls the chip enable line that doubles as a reset line.
@@ -168,8 +168,8 @@ pin to determine whether the chip boots normally or into the serial
 bootloader. After resetting, however, the BOOT button can be used for
 software input.
 
-LEDs
+Board LEDs
-----
+----------
 
 There are many on-board LEDs. The only one that can be controlled by software
 is a WS2812 RGB LED (U21) addressable LED and is driven by GPIO45.
@@ -177,6 +177,39 @@ is a WS2812 RGB LED (U21) addressable LED and is driven by GPIO45.
 Configurations
 ==============
 
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32s2-kaluga-1:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons and touch pads::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x7f
+    nsh> Sample = 32
+    Sample = 0
+    Sample = 2
+    Sample = 0
+    Sample = 4
+    Sample = 0
+    Sample = 8
+    Sample = 0
+    Sample = 16
+    Sample = 0
+    Sample = 64
+    Sample = 0
+
 nsh
 ---
 

Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst

@@ -39,8 +39,8 @@ It will show up as /dev/ttyUSB[n] where [n] will probably be 0.
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 There are two buttons labeled Boot and EN.  The EN button is not available
 to the software.  It pulls the chip enable line that doubles as a reset line.
@@ -50,8 +50,8 @@ pin to determine whether the chip boots normally or into the serial
 bootloader.  After resetting, however, the BOOT button can be used for
 software input.
 
-LEDs
+Board LEDs
-----
+----------
 
 There are two on-board LEDs. RED_LED (D5) indicates the presence of 3.3V
 power and is not controlled by software. RGB LED (U6) is a WS2812 addressable
@@ -90,6 +90,14 @@ The following configurations use the I2S peripheral::
 Configurations
 ==============
 
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32s2-saola-1:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
 audio
 -----
 
@@ -114,24 +122,92 @@ ESP32-S2 Pin CS4344 Pin Description
 
 **ROMFS example**
 
-Prepare and build the `audio` defconfig::
+Prepare and build the ``audio`` defconfig::
 
   $ make -j distclean && ./tools/configure.sh esp32s2-saola-1:audio && make
 
-This will create a temporary folder in `apps/examples/romfs/testdir`. Move
+This will create a temporary folder in ``apps/examples/romfs/testdir``. Move
-a PCM-encoded (`.wav`) audio file with 16 or 24 bits/sample (sampled at 16~48kHz)
+a PCM-encoded (``.wav``) audio file with 16 or 24 bits/sample (sampled at 16~48kHz)
 to this folder.
 
 .. note:: You can use :download:`this 440 Hz sinusoidal tone <tone.wav>`.
-   The audio file should be located at `apps/examples/romfs/testdir/tone.wav`
+   The audio file should be located at ``apps/examples/romfs/testdir/tone.wav``
 
 Build the project again and flash it (make sure not to clean it, just build)
 
 After successfully built and flashed, load the romfs and play it::
 
-  $ nsh> romfs
+    nsh> romfs
-  $ nsh> nxplayer
+    nsh> nxplayer
-  $ nxplayer> play /usr/share/local/tone.wav
+    nxplayer> play /usr/share/local/tone.wav
+
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x01
+    nsh> Sample = 1
+    Sample = 0
+
+coremark
+--------
+
+This configuration sets the CoreMark benchmark up for running on the maximum
+number of cores for this system. It also enables some optimization flags and
+disables the NuttShell to get the best possible score.
+
+.. note:: As the NSH is disabled, the application will start as soon as the
+  system is turned on.
+
+cxx
+---
+
+Development enviroment ready for C++ applications. You can check if the setup
+was successfull by running ``cxxtest``::
+
+    nsh> cxxtest
+    Test ofstream ================================
+    printf: Starting test_ostream
+    printf: Successfully opened /dev/console
+    cout: Successfully opened /dev/console
+    Writing this to /dev/console
+    Test iostream ================================
+    Hello, this is only a test
+    Print an int: 190
+    Print a char: d
+    Test std::vector =============================
+    v1=1 2 3
+    Hello World Good Luck
+    Test std::map ================================
+    Test C++17 features ==========================
+    File /proc/meminfo exists!
+    Invalid file! /invalid
+    File /proc/version exists!
+
+gpio
+----
+
+This is a test for the GPIO driver. It includes one arbitrary GPIO.
+For this example, GPIO1 was used (defined by the board implementation).
+At the nsh, we can turn the GPIO output on and off with the following::
+
+    nsh> gpio -o 1 /dev/gpio0
+    nsh> gpio -o 0 /dev/gpio0
+
+i2c
+---
+
+This configuration can be used to scan and manipulate I2C devices.
+You can scan for all I2C devices using the following command::
+
+    nsh> i2c dev 0x00 0x7f
 
 i2schar
 -------
@@ -154,10 +230,17 @@ ESP32-S2 Pin Signal Pin Description
 
 After successfully built and flashed, run on the boards's terminal::
 
-  nsh> i2schar
+    nsh> i2schar
 
 The corresponding output should show related debug information.
 
+mcuboot_nsh
+-----------
+
+Similar configuration as nsh, except that it enables booting from
+MCUboot and the experimental features configuration.
+You can find more information on the `example's documentation <https://github.com/apache/nuttx-apps/blob/master/examples/mcuboot/swap_test/README.md>`_.
+
 nsh
 ---
 
@@ -194,22 +277,64 @@ The DOUT pin will output the captured data frame.
 
 **nxlooper**
 
-The `nxlooper` application captures data from the audio device with receiving
+The ``nxlooper`` application captures data from the audio device with receiving
 capabilities and forwards the audio data frame to the audio device with
 transmitting capabilities.
 
 After successfully built and flashed, run on the boards's terminal::
 
-  nsh> nxlooper
+    nsh> nxlooper
-  nxlooper> loopback
+    nxlooper> loopback
 
-.. note:: `loopback` command default arguments for the channel configuration,
+.. 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
 
+oneshot
+-------
+
+This config demonstrate the use of oneshot timers present on the ESP32-S2.
+To test it, just run the ``oneshot`` example::
+
+    nsh> oneshot
+    Opening /dev/oneshot
+    Maximum delay is 4294967295999999
+    Starting oneshot timer with delay 2000000 microseconds
+    Waiting...
+    Finished
+
+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.
+
+pwm
+------
+
+This configuration demonstrates the use of PWM through a LED connected to GPIO2.
+To test it, just execute the ``pwm`` application::
+
+    nsh> pwm
+    pwm_main: starting output with frequency: 10000 duty: 00008000
+    pwm_main: stopping output
+
+random
+------
+
+This configuration shows the use of the ESP32-S2's True Random Number Generator with
+entropy sourced from Wi-Fi and Bluetooth noise.
+To test it, just run ``rand`` to get 32 randomly generated bytes::
+
+    nsh> rand
+    Reading 8 random numbers
+    Random values (0x3ffe0b00):
+    0000  98 b9 66 a2 a2 c0 a2 ae 09 70 93 d1 b5 91 86 c8  ..f......p......
+    0010  8f 0e 0b 04 29 64 21 72 01 92 7c a2 27 60 6f 90  ....)d!r..|.'`o.
+
 timer
 -----
 
@@ -219,7 +344,7 @@ example.
 
 To test it, just run the following::
 
-  nsh> timer -d /dev/timerx
+    nsh> timer -d /dev/timerx
 
 Where x in the timer instance.
 
@@ -232,6 +357,6 @@ example.
 
 To test it, just run the following::
 
-  nsh> wdog -i /dev/watchdogx
+    nsh> wdog -i /dev/watchdogx
 
 Where x is the watchdog instance.

Documentation/platforms/xtensa/esp32s2/index.rst

@@ -48,7 +48,6 @@ Alternatively, you may follow the steps in
 Flashing
 ========
 
-
 Firmware for ESP32-S2 is flashed via the USB/UART or internal USB DEVICE JTAG interface using the
 ``esptool.py`` tool.
 It's a two-step process where the first converts the ELF file into a ESP32-S2 compatible binary
@@ -64,7 +63,7 @@ Bootloader and partitions
 
 ESP32-S2 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>`_.
+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:
 
@@ -97,29 +96,30 @@ The following list indicates the state of peripherals' support in NuttX:
 ========== ======= =====
 Peripheral Support NOTES
 ========== ======= =====
-GPIO         Yes
+ADC          No
-UART         Yes
+AES          No
-SPI          Yes
+CAN/TWAI     No
-I2C          Yes
 DMA          Yes
-Wifi         No
+eFuse        No
 Ethernet     No
+GPIO         Yes
+I2C          Yes
+I2S          Yes
+LED_PWM      No
+Pulse_CNT    No
+RMT          No
+RNG          Yes
+RSA          No
+RTC          Yes
+SHA          No
+SPI          Yes
 SPIFLASH     Yes
 SPIRAM       Yes
 Timers       Yes
+Touch        Yes
+UART         Yes
 Watchdog     Yes
-RTC          Yes
+Wifi         No
-RNG          Yes
-AES          No
-eFuse        No
-ADC          No
-I2S          Yes
-LED_PWM      No
-RMT          No
-Pulse_CNT    No
-SHA          No
-RSA          No
-CAN/TWAI     No
 ========== ======= =====
 
 Memory Map
@@ -242,7 +242,7 @@ Linker Segments
 ESP32-S2 has 4 generic timers of 64 bits (2 from Group 0 and 2 from Group 1).
 They're accessible as character drivers, the configuration along with a
 guidance on how to run the example and the description of the application level
-interface can be found :doc:`here </components/drivers/character/timer>`.
+interface can be found in the :doc:`timer documentation </components/drivers/character/timer>`.
 
 Watchdog Timers
 ===============
@@ -250,8 +250,8 @@ Watchdog Timers
 ESP32-S2 has 3 WDTs. 2 MWDTs from the Timers Module and 1 RWDT from the RTC Module
 (Currently not supported yet). They're accessible as character drivers,
 The configuration along with a guidance on how to run the example and the description
-of the application level interface can be found
+of the application level interface can be found in the
-:doc:`here </components/drivers/character/watchdog>`.
+:doc:`watchdog documentation </components/drivers/character/watchdog>`.
 
 I2S
 ===
@@ -276,7 +276,7 @@ Secure Boot protects a device from running any unauthorized (i.e., unsigned) cod
 each piece of software that is being booted is signed. On an ESP32-S2, these pieces of software include
 the second stage bootloader and each application binary. Note that the first stage bootloader does not
 require signing as it is ROM code thus cannot be changed. This is achieved using specific hardware in
-conjunction with MCUboot (read more about MCUboot `here <https://docs.mcuboot.com/>`_).
+conjunction with MCUboot (read more about MCUboot `here <https://docs.mcuboot.com/>`__).
 
 The Secure Boot process on the ESP32-S2 involves the following steps performed:
 
@@ -290,7 +290,7 @@ The Secure Boot process on the ESP32-S2 involves the following steps performed:
 .. warning:: Once enabled, Secure Boot will not boot a modified bootloader. The bootloader will only boot an
    application firmware image if it has a verified digital signature. There are implications for reflashing
    updated images once Secure Boot is enabled. You can find more information about the ESP32-S2's Secure boot
-   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/secure-boot-v2.html>`_.
+   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/secure-boot-v2.html>`__.
 
 .. note:: As the bootloader image is built on top of the Hardware Abstraction Layer component
    of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the
@@ -307,7 +307,7 @@ of flash will not be sufficient to recover most flash contents.
 .. warning::  After enabling Flash Encryption, an encryption key is generated internally by the device and
    cannot be accessed by the user for re-encrypting data and re-flashing the system, hence it will be permanently encrypted.
    Re-flashing an encrypted system is complicated and not always possible. You can find more information about the ESP32-S2's Flash Encryption
-   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/flash-encryption.html>`_.
+   `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/flash-encryption.html>`__.
 
 Prerequisites
 -------------
@@ -360,7 +360,7 @@ the `MCUboot porting guide <https://github.com/mcu-tools/mcuboot/blob/main/docs/
 
 After you developed an application which implements all desired functions, you need to flash it into the primary image slot
 of the device (it will automatically be in the confirmed state, you can learn more about image
-confirmation `here <https://docs.mcuboot.com/design.html#image-swapping>`_).
+confirmation `here <https://docs.mcuboot.com/design.html#image-swapping>`__).
 To flash to the primary image slot, select ``Application image primary slot`` in
 :menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing`
 and compile it using ``make -j ESPSEC_KEYDIR=~/signing_keys``.

Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst

@@ -30,8 +30,8 @@ It will show up as /dev/ttyUSB[n] where [n] will probably be 0.
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 There are two buttons labeled Boot and EN.  The EN button is not available
 to software.  It pulls the chip enable line that doubles as a reset line.
@@ -41,8 +41,8 @@ pin to determine whether the chip boots normally or into the serial
 bootloader.  After reset, however, the BOOT button can be used for software
 input.
 
-LEDs
+Board LEDs
-----
+----------
 
 There are several on-board LEDs for that indicate the presence of power
 and USB activity.  None of these are available for use by software.
@@ -50,8 +50,98 @@ and USB activity.  None of these are available for use by software.
 Configurations
 ==============
 
-.. tip:: Please check commonly used configurations for
+All of the configurations presented below can be tested by running the following commands::
-  :ref:`ESP32-S3 Peripherals <esp32s3_peripheral_support>`
+
+    $ ./tools/configure.sh esp32s3-devkit:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
+buttons
+-------
+
+This configuration shows the use of the buttons subsystem. It can be used by executing
+the ``buttons`` application and pressing on any of the available board buttons::
+
+    nsh> buttons
+    buttons_main: Starting the button_daemon
+    buttons_main: button_daemon started
+    button_daemon: Running
+    button_daemon: Opening /dev/buttons
+    button_daemon: Supported BUTTONs 0x01
+    nsh> Sample = 1
+    Sample = 0
+
+coremark
+--------
+
+This configuration sets the CoreMark benchmark up for running on the maximum
+number of cores for this system. It also enables some optimization flags and
+disables the NuttShell to get the best possible score.
+
+.. note:: As the NSH is disabled, the application will start as soon as the
+  system is turned on.
+
+cxx
+---
+
+Development enviroment ready for C++ applications. You can check if the setup
+was successfull by running ``cxxtest``::
+
+    nsh> cxxtest
+    Test ofstream ================================
+    printf: Starting test_ostream
+    printf: Successfully opened /dev/console
+    cout: Successfully opened /dev/console
+    Writing this to /dev/console
+    Test iostream ================================
+    Hello, this is only a test
+    Print an int: 190
+    Print a char: d
+    Test std::vector =============================
+    v1=1 2 3
+    Hello World Good Luck
+    Test std::map ================================
+    Test C++17 features ==========================
+    File /proc/meminfo exists!
+    Invalid file! /invalid
+    File /proc/version exists!
+
+i2c
+---
+
+This configuration can be used to scan and manipulate I2C devices.
+You can scan for all I2C devices using the following command::
+
+    nsh> i2c dev 0x00 0x7f
+
+knsh
+----
+
+This is identical to the nsh configuration except that (1) NuttX
+is built as PROTECTED mode, monolithic module and the user applications
+are built separately and, as a consequence, (2) some features that are
+only available in the FLAT build are disabled.
+
+Protected Mode support for ESP32-S3 relies on the World Controller (WC)
+and Permission Control (PMS) peripherals for implementing isolation
+between Kernel and Userspace.
+
+By working together with the MMU and Static MPUs of the ESP32-S3, the WC/PMS
+is able to restrict the application access to peripherals, on-chip
+memories (Internal ROM and Internal SRAM) and off-chip memories (External
+Flash and PSRAM).
+
+.. warning:: The World Controller and Permission Control **do not** prevent
+  the application from accessing CPU System Registers.
+
+mcuboot_nsh
+-----------
+
+Similar configuration as nsh, except that it enables booting from
+MCUboot and the experimental features configuration.
+You can find more information on the `example's documentation <https://github.com/apache/nuttx-apps/blob/master/examples/mcuboot/swap_test/README.md>`_.
 
 nsh
 ---
@@ -59,8 +149,137 @@ nsh
 Basic NuttShell configuration (console enabled in UART0, exposed via
 USB connection by means of CP2102 converter, at 115200 bps).
 
-mcuboot_nsh
+oneshot
------------
+-------
 
-Similar configuration as nsh, except that it enables booting from
+This config demonstrate the use of oneshot timers present on the ESP32-S3.
-MCUboot and the experimental features configuration.
+To test it, just run the ``oneshot`` example::
+
+    nsh> oneshot
+    Opening /dev/oneshot
+    Maximum delay is 4294967295999999
+    Starting oneshot timer with delay 2000000 microseconds
+    Waiting...
+    Finished
+
+pwm
+---
+
+This configuration demonstrates the use of PWM through a LED connected to GPIO2.
+To test it, just execute the ``pwm`` application::
+
+    nsh> pwm
+    pwm_main: starting output with frequency: 10000 duty: 00008000
+    pwm_main: stopping output
+
+random
+------
+
+This configuration shows the use of the ESP32-S3's True Random Number Generator with
+entropy sourced from Wi-Fi and Bluetooth noise.
+To test it, just run ``rand`` to get 32 randomly generated bytes::
+
+    nsh> rand
+    Reading 8 random numbers
+    Random values (0x3ffe0b00):
+    0000  98 b9 66 a2 a2 c0 a2 ae 09 70 93 d1 b5 91 86 c8  ..f......p......
+    0010  8f 0e 0b 04 29 64 21 72 01 92 7c a2 27 60 6f 90  ....)d!r..|.'`o.
+
+smp
+---
+
+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
+
+spiflash
+--------
+
+This config tests the external SPI that comes with the ESP32-S3 module connected
+through SPI1.
+
+By default a SmartFS file system is selected.
+Once booted you can use the following commands to mount the file system::
+
+    nsh> mksmartfs /dev/smart0
+    nsh> mount -t smartfs /dev/smart0 /mnt
+
+Note that mksmartfs is only needed the first time.
+
+sta_softap
+----------
+
+With this configuration you can run these commands to be able
+to connect your smartphone or laptop to your board::
+
+  nsh> ifup wlan1
+  nsh> dhcpd_start wlan1
+  nsh> wapi psk wlan1 mypasswd 3
+  nsh> wapi essid wlan1 nuttxap 1
+
+In this case, you are creating the access point ``nuttxapp`` in your board and to
+connect to it on your smartphone you will be required to type the password ``mypasswd``
+using WPA2.
+The ``dhcpd_start`` is necessary to let your board to associate an IP to your smartphone.
+
+tickless
+--------
+
+This configuration enables the support for tickless scheduler mode.
+
+timer
+-----
+
+This config test the general use purpose timers. It includes the 4 timers,
+adds driver support, registers the timers as devices and includes the timer
+example.
+
+To test it, just run the following::
+
+  nsh> timer -d /dev/timerx
+
+Where x in the timer instance.
+
+wifi
+----
+
+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 3
+    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 -i /dev/watchdogx
+
+Where x is the watchdog instance.

Documentation/platforms/xtensa/esp32s3/boards/esp32s3-eye/index.rst

@@ -26,17 +26,20 @@ Features
 Configurations
 ==============
 
+All of the configurations presented below can be tested by running the following commands::
+
+    $ ./tools/configure.sh esp32s3-eye:<config_name>
+    $ make flash ESPTOOL_PORT=/dev/ttyUSB0 -j
+
+Where <config_name> is the name of board configuration you want to use, i.e.: nsh, buttons, wifi...
+Then use a serial console terminal like ``picocom`` configured to 115200 8N1.
+
 nsh
 ---
 
 Basic NuttShell configuration (console enabled in USB JTAG SERIAL Device, exposed via
 USB connection at 9600 bps).
 
-You can configure this board profile this way:
-
-  $ cd nuttxspace/nuttx
-  $ ./tools/configure.sh esp32s3-eye:nsh
-
 Flashing
 ========
 
@@ -63,8 +66,8 @@ You can use minicom with /dev/ttyACM0 port at 9600 8n1 or picocom this way:
 Buttons and LEDs
 ================
 
-Buttons
+Board Buttons
--------
+-------------
 
 There are two buttons labeled BOOT and RST.  The RST button is not available
 to software.  It pulls the chip enable line that doubles as a reset line.
@@ -74,8 +77,8 @@ pin to determine whether the chip boots normally or into the serial
 bootloader.  After reset, however, the BOOT button can be used for software
 input.
 
-LEDs
+Board LEDs
-----
+----------
 
 There are several on-board LEDs for that indicate the presence of power
 and USB activity.  None of these are available for use by software.

Documentation/platforms/xtensa/esp32s3/index.rst

@@ -89,36 +89,37 @@ The following list indicates the state of peripherals' support in NuttX:
 ========== ======= =====
 Peripheral Support NOTES
 ========== ======= =====
-GPIO         Yes
+ADC          No
-UART         Yes
+AES          No
-SPI          Yes
+Bluetooth    No
-I2C          No
+CAMERA       No
 CAN/TWAI     No
 DMA          Yes
-Wi-Fi        Yes   WPA3-SAE supported
+eFuse        No
+GPIO         Yes
+I2C          No
+I2S          No
+LCD          No
+LED_PWM      No
+MCPWM        No
+Pulse_CNT    No
+RMT          No
+RNG          No
+RSA          No
+RTC          No
+SD/MMC       No
+SDIO         No
+SHA          No
+SPI          Yes
 SPIFLASH     Yes
 SPIRAM       Yes
 Timers       Yes
-Watchdog     Yes
+Touch        Yes
-RTC          No
+UART         Yes
-RNG          No
-AES          No
-eFuse        No
-ADC          No
-Bluetooth    No
-SDIO         No
-SD/MMC       No
-I2S          No
-LCD          No
-CAMERA       No
-LED_PWM      No
-RMT          No
-MCPWM        No
-Pulse_CNT    No
-SHA          No
-RSA          No
-USB SERIAL   Yes
 USB OTG      No
+USB SERIAL   Yes
+Watchdog     Yes
+Wi-Fi        Yes   WPA3-SAE supported
 ========== ======= =====
 
 .. _esp32s3_peripheral_support:
@@ -126,7 +127,7 @@ USB OTG      No
 Wi-Fi
 -----
 
-.. tip:: Boards usually expose a ``wapi`` defconfig which enables Wi-Fi
+.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi
 
 A standard network interface will be configured and can be initialized such as::