Documentation/platforms/xtensa/esp32s3/index.rst - nuttx - Git at Google

 ==================
 Espressif ESP32-S3
 ==================

 The ESP32-S3 is a series of single and dual-core SoCs from Espressif
 based on Harvard architecture Xtensa LX7 CPUs and with on-chip support
 for Bluetooth and Wi-Fi.

 All embedded memory, external memory and peripherals are located on the
 data bus and/or the instruction bus of these CPUs. With some minor
 exceptions, the address mapping of two CPUs is symmetric, meaning they
 use the same addresses to access the same memory. Multiple peripherals in
 the system can access embedded memory via DMA.

 On dual-core SoCs, the two CPUs are typically named "PRO_CPU" and "APP_CPU"
 (for "protocol" and "application"), however for most purposes the
 two CPUs are interchangeable.

 ESP32-S3 Toolchain
 ==================

 The toolchain used to build ESP32-S3 firmware can be either downloaded or built from the sources.
 It is **highly** recommended to use (download or build) the same toolchain version that is being
 used by the NuttX CI.

 Please refer to the Docker
 `container <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ and
 check for the current compiler version being used. For instance:

 .. code-block::

   ###############################################################################
   # Build image for tool required by ESP32 builds
   ###############################################################################
   FROM nuttx-toolchain-base AS nuttx-toolchain-esp32
   # Download the latest ESP32 GCC toolchain prebuilt by Espressif
   RUN mkdir -p xtensa-esp32-elf-gcc && \
     curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
     | tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ

   RUN mkdir -p xtensa-esp32s2-elf-gcc && \
     curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
     | tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ

   RUN mkdir -p xtensa-esp32s3-elf-gcc && \
     curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
     | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ

 For ESP32-S3, the toolchain version is based on GGC 12.2.0 (``xtensa-esp32s3-elf-12.2.0_20230208``)

 The prebuilt Toolchain (Recommended)
 ------------------------------------

 First, create a directory to hold the toolchain:

 .. code-block:: console

   $ mkdir -p /path/to/your/toolchain/xtensa-esp32s3-elf-gcc

 Download and extract toolchain:

 .. code-block:: console

   $ curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
   | tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ

 Add the toolchain to your `PATH`:

 .. code-block:: console

   $ echo "export PATH=/path/to/your/toolchain/xtensa-esp32s3-elf-gcc/bin:$PATH" >> ~/.bashrc

 You can edit your shell's rc files if you don't use bash.

 Building from source
 --------------------

 You can also build the toolchain yourself. The steps to
 build the toolchain with crosstool-NG on Linux are as follows

 .. code-block:: console

   $ git clone https://github.com/espressif/crosstool-NG.git
   $ cd crosstool-NG
   $ git submodule update --init

   $ ./bootstrap && ./configure --enable-local && make

   $ ./ct-ng xtensa-esp32s3-elf
   $ ./ct-ng build

   $ chmod -R u+w builds/xtensa-esp32s3-elf

   $ export PATH="crosstool-NG/builds/xtensa-esp32-elf/bin:$PATH"

 These steps are given in the setup guide in
 `ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.

 Building and flashing NuttX
 ===========================

 Bootloader and partitions
 -------------------------

 NuttX can boot the ESP32-S3 directly using the so-called "Simple Boot". An externally-built
 2nd stage bootloader is not required in this case as all functions required to boot the device
 are built within NuttX. Simple boot does not require any specific configuration (it is selectable
 by default if no other 2nd stage bootloader is used).

 If other features are required, an externally-built 2nd stage bootloader is needed. The bootloader
 is built using the ``make bootloader`` command. This command generates the firmware in the
 ``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command to specify the path
 to the bootloader. For compatibility among other SoCs and future options of 2nd stage bootloaders,
 the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be
 used even if no externally-built 2nd stage bootloader is being built (they will be ignored if
 Simple Boot is used, for instance)::

   $ make bootloader

 .. note:: It is recommended that if this is the first time you are using the board with NuttX to
    perform a complete SPI FLASH erase.

     .. code-block:: console

       $ esptool.py erase_flash

 Building and Flashing
 ---------------------

 First, make sure that ``esptool.py`` is installed.  This tool is used to convert the ELF to a
 compatible ESP32-S3 image and to flash the image into the board.
 It can be installed with: ``pip install esptool==4.8.dev4``.

 It's a two-step process where the first converts the ELF file into an ESP32-S3 compatible binary
 and the second flashes it to the board. These steps are included in the build system and it is
 possible to build and flash the NuttX firmware simply by running::

     $ make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=./

 where ``<port>`` is typically ``/dev/ttyUSB0`` or similar. ``ESPTOOL_BINDIR=./`` is the path of the
 externally-built 2nd stage bootloader and the partition table (if applicable): when built using the
 ``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to
 change the flash baud rate if desired.

 Debugging with ``openocd`` and ``gdb``
 ======================================

 Espressif uses a specific version of OpenOCD to support ESP32-S3: `openocd-esp32 <https://github.com/espressif/>`_.

 Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
 for more information on how to build OpenOCD for ESP32-S3.

 The quickest and most convenient way to start with JTAG debugging is through a USB cable
 connected to the D+/D- USB pins of ESP32-S3. No need for an external JTAG adapter and
 extra wiring/cable to connect JTAG to ESP32-S3. Most of the ESP32-S3 boards have a
 USB connector that can be used for JTAG debugging.
 This is the case for the :ref:`ESP32-S3-DevKit <platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:ESP32S3-DevKit>` board.

 .. note:: One must configure the USB drivers to enable JTAG communication. Please check
   `Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/configure-builtin-jtag.html?highlight=udev#configure-usb-drivers>`_
   for more information.

 OpenOCD can then be used::

   openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s3-builtin.cfg

 Once OpenOCD is running, you can use GDB to connect to it and debug your application::

   xtensa-esp32s3-elf-gdb -x gdbinit nuttx

 whereas the content of the ``gdbinit`` file is::

   target remote :3333
   set remote hardware-watchpoint-limit 2
   mon reset halt
   flushregs
   monitor reset halt
   thb nsh_main
   c

 .. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.

 Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.

 Peripheral Support
 ==================

 The following list indicates the state of peripherals' support in NuttX:

 ========== ======= =====
 Peripheral Support NOTES
 ========== ======= =====
 ADC          YES
 AES          YES
 Bluetooth    No
 CAMERA       No
 CAN/TWAI     Yes
 DMA          Yes
 eFuse        No
 GPIO         Yes
 I2C          No
 I2S          Yes
 LCD          No
 LED_PWM      No
 MCPWM        Yes
 Pulse_CNT    No
 RMT          No
 RNG          No
 RSA          No
 RTC          Yes
 SD/MMC       Yes
 SDIO         No
 SHA          No
 SPI          Yes
 SPIFLASH     Yes
 SPIRAM       Yes
 Timers       Yes
 Touch        Yes
 UART         Yes
 USB OTG      No
 USB SERIAL   Yes
 Watchdog     Yes
 Wi-Fi        Yes   WPA3-SAE supported
 ========== ======= =====

 .. _esp32s3_peripheral_support:

 Wi-Fi
 -----

 .. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi. On ESP32-S3,
    SMP is enabled to enhance Wi-Fi performance.

 A standard network interface will be configured and can be initialized such as::

     nsh> ifup wlan0
     nsh> wapi psk wlan0 mypasswd 3
     nsh> wapi essid wlan0 myssid 1
     nsh> renew wlan0

 In this case a connection to AP with SSID ``myssid`` is done, using ``mypasswd`` as
 password. IP address is obtained via DHCP using ``renew`` command. You can check
 the result by running ``ifconfig`` afterwards.

 .. tip:: Please refer to :ref:`ESP32 Wi-Fi Station Mode <esp32_wi-fi_sta>`
   for more information.

 Wi-Fi SoftAP
 ------------

 It is possible to use ESP32-S3 as an Access Point (SoftAP).

 .. tip:: Boards usually expose a ``sta_softap`` defconfig which enables Wi-Fi
    (STA + SoftAP). On ESP32-S3, SMP is enabled to enhance Wi-Fi performance.

 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::

     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.

 .. tip:: Please refer to :ref:`ESP32 Wi-Fi SoftAP Mode <esp32_wi-fi_softap>`
   for more information.

 The ``dhcpd_start`` is necessary to let your board to associate an IP to your smartphone.

 Supported Boards
 ================

 .. toctree::
   :glob:
   :maxdepth: 1

   boards/*/*
	==================
	Espressif ESP32-S3
	==================

	The ESP32-S3 is a series of single and dual-core SoCs from Espressif
	based on Harvard architecture Xtensa LX7 CPUs and with on-chip support
	for Bluetooth and Wi-Fi.

	All embedded memory, external memory and peripherals are located on the
	data bus and/or the instruction bus of these CPUs. With some minor
	exceptions, the address mapping of two CPUs is symmetric, meaning they
	use the same addresses to access the same memory. Multiple peripherals in
	the system can access embedded memory via DMA.

	On dual-core SoCs, the two CPUs are typically named "PRO_CPU" and "APP_CPU"
	(for "protocol" and "application"), however for most purposes the
	two CPUs are interchangeable.

	ESP32-S3 Toolchain
	==================

	The toolchain used to build ESP32-S3 firmware can be either downloaded or built from the sources.
	It is highly recommended to use (download or build) the same toolchain version that is being
	used by the NuttX CI.

	Please refer to the Docker
	`container <https://github.com/apache/nuttx/tree/master/tools/ci/docker/linux/Dockerfile>`_ and
	check for the current compiler version being used. For instance:

	.. code-block::

	###############################################################################
	# Build image for tool required by ESP32 builds
	###############################################################################
	FROM nuttx-toolchain-base AS nuttx-toolchain-esp32
	# Download the latest ESP32 GCC toolchain prebuilt by Espressif
	RUN mkdir -p xtensa-esp32-elf-gcc && \
	curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
	\| tar -C xtensa-esp32-elf-gcc --strip-components 1 -xJ

	RUN mkdir -p xtensa-esp32s2-elf-gcc && \
	curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s2-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
	\| tar -C xtensa-esp32s2-elf-gcc --strip-components 1 -xJ

	RUN mkdir -p xtensa-esp32s3-elf-gcc && \
	curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
	\| tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ

	For ESP32-S3, the toolchain version is based on GGC 12.2.0 (``xtensa-esp32s3-elf-12.2.0_20230208``)

	The prebuilt Toolchain (Recommended)
	------------------------------------

	First, create a directory to hold the toolchain:

	.. code-block:: console

	$ mkdir -p /path/to/your/toolchain/xtensa-esp32s3-elf-gcc

	Download and extract toolchain:

	.. code-block:: console

	$ curl -s -L "https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32s3-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz" \
	\| tar -C xtensa-esp32s3-elf-gcc --strip-components 1 -xJ

	Add the toolchain to your `PATH`:

	.. code-block:: console

	$ echo "export PATH=/path/to/your/toolchain/xtensa-esp32s3-elf-gcc/bin:$PATH" >> ~/.bashrc

	You can edit your shell's rc files if you don't use bash.

	Building from source
	--------------------

	You can also build the toolchain yourself. The steps to
	build the toolchain with crosstool-NG on Linux are as follows

	.. code-block:: console

	$ git clone https://github.com/espressif/crosstool-NG.git
	$ cd crosstool-NG
	$ git submodule update --init

	$ ./bootstrap && ./configure --enable-local && make

	$ ./ct-ng xtensa-esp32s3-elf
	$ ./ct-ng build

	$ chmod -R u+w builds/xtensa-esp32s3-elf

	$ export PATH="crosstool-NG/builds/xtensa-esp32-elf/bin:$PATH"

	These steps are given in the setup guide in
	`ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/get-started/linux-setup-scratch.html>`_.

	Building and flashing NuttX
	===========================

	Bootloader and partitions
	-------------------------

	NuttX can boot the ESP32-S3 directly using the so-called "Simple Boot". An externally-built
	2nd stage bootloader is not required in this case as all functions required to boot the device
	are built within NuttX. Simple boot does not require any specific configuration (it is selectable
	by default if no other 2nd stage bootloader is used).

	If other features are required, an externally-built 2nd stage bootloader is needed. The bootloader
	is built using the ``make bootloader`` command. This command generates the firmware in the
	``nuttx`` folder. The ``ESPTOOL_BINDIR`` is used in the ``make flash`` command to specify the path
	to the bootloader. For compatibility among other SoCs and future options of 2nd stage bootloaders,
	the commands ``make bootloader`` and the ``ESPTOOL_BINDIR`` option (for the ``make flash``) can be
	used even if no externally-built 2nd stage bootloader is being built (they will be ignored if
	Simple Boot is used, for instance)::

	$ make bootloader

	.. note:: It is recommended that if this is the first time you are using the board with NuttX to
	perform a complete SPI FLASH erase.

	.. code-block:: console

	$ esptool.py erase_flash

	Building and Flashing
	---------------------

	First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a
	compatible ESP32-S3 image and to flash the image into the board.
	It can be installed with: ``pip install esptool==4.8.dev4``.

	It's a two-step process where the first converts the ELF file into an ESP32-S3 compatible binary
	and the second flashes it to the board. These steps are included in the build system and it is
	possible to build and flash the NuttX firmware simply by running::

	$ make flash ESPTOOL_PORT=<port> ESPTOOL_BINDIR=./

	where ``<port>`` is typically ``/dev/ttyUSB0`` or similar. ``ESPTOOL_BINDIR=./`` is the path of the
	externally-built 2nd stage bootloader and the partition table (if applicable): when built using the
	``make bootloader``, these files are placed into ``nuttx`` folder. ``ESPTOOL_BAUD`` is able to
	change the flash baud rate if desired.

	Debugging with ``openocd`` and ``gdb``
	======================================

	Espressif uses a specific version of OpenOCD to support ESP32-S3: `openocd-esp32 <https://github.com/espressif/>`_.

	Please check `Building OpenOCD from Sources <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/index.html#jtag-debugging-building-openocd>`_
	for more information on how to build OpenOCD for ESP32-S3.

	The quickest and most convenient way to start with JTAG debugging is through a USB cable
	connected to the D+/D- USB pins of ESP32-S3. No need for an external JTAG adapter and
	extra wiring/cable to connect JTAG to ESP32-S3. Most of the ESP32-S3 boards have a
	USB connector that can be used for JTAG debugging.
	This is the case for the :ref:`ESP32-S3-DevKit <platforms/xtensa/esp32s3/boards/esp32s3-devkit/index:ESP32S3-DevKit>` board.

	.. note:: One must configure the USB drivers to enable JTAG communication. Please check
	`Configure USB Drivers <https://docs.espressif.com/projects/esp-idf/en/release-v5.1/esp32s3/api-guides/jtag-debugging/configure-builtin-jtag.html?highlight=udev#configure-usb-drivers>`_
	for more information.

	OpenOCD can then be used::

	openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32s3-builtin.cfg

	Once OpenOCD is running, you can use GDB to connect to it and debug your application::

	xtensa-esp32s3-elf-gdb -x gdbinit nuttx

	whereas the content of the ``gdbinit`` file is::

	target remote :3333
	set remote hardware-watchpoint-limit 2
	mon reset halt
	flushregs
	monitor reset halt
	thb nsh_main
	c

	.. note:: ``nuttx`` is the ELF file generated by the build process. Please note that ``CONFIG_DEBUG_SYMBOLS`` must be enabled in the ``menuconfig``.

	Please refer to :doc:`/quickstart/debugging` for more information about debugging techniques.

	Peripheral Support
	==================

	The following list indicates the state of peripherals' support in NuttX:

	========== ======= =====
	Peripheral Support NOTES
	========== ======= =====
	ADC YES
	AES YES
	Bluetooth No
	CAMERA No
	CAN/TWAI Yes
	DMA Yes
	eFuse No
	GPIO Yes
	I2C No
	I2S Yes
	LCD No
	LED_PWM No
	MCPWM Yes
	Pulse_CNT No
	RMT No
	RNG No
	RSA No
	RTC Yes
	SD/MMC Yes
	SDIO No
	SHA No
	SPI Yes
	SPIFLASH Yes
	SPIRAM Yes
	Timers Yes
	Touch Yes
	UART Yes
	USB OTG No
	USB SERIAL Yes
	Watchdog Yes
	Wi-Fi Yes WPA3-SAE supported
	========== ======= =====

	.. _esp32s3_peripheral_support:

	Wi-Fi
	-----

	.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi. On ESP32-S3,
	SMP is enabled to enhance Wi-Fi performance.

	A standard network interface will be configured and can be initialized such as::

	nsh> ifup wlan0
	nsh> wapi psk wlan0 mypasswd 3
	nsh> wapi essid wlan0 myssid 1
	nsh> renew wlan0

	In this case a connection to AP with SSID ``myssid`` is done, using ``mypasswd`` as
	password. IP address is obtained via DHCP using ``renew`` command. You can check
	the result by running ``ifconfig`` afterwards.

	.. tip:: Please refer to :ref:`ESP32 Wi-Fi Station Mode <esp32_wi-fi_sta>`
	for more information.

	Wi-Fi SoftAP
	------------

	It is possible to use ESP32-S3 as an Access Point (SoftAP).

	.. tip:: Boards usually expose a ``sta_softap`` defconfig which enables Wi-Fi
	(STA + SoftAP). On ESP32-S3, SMP is enabled to enhance Wi-Fi performance.

	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::

	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.

	.. tip:: Please refer to :ref:`ESP32 Wi-Fi SoftAP Mode <esp32_wi-fi_softap>`
	for more information.

	The ``dhcpd_start`` is necessary to let your board to associate an IP to your smartphone.

	Supported Boards
	================

	.. toctree::
	:glob:
	:maxdepth: 1

	boards//