diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index 523c1967d24..30f83519f8e 100644 --- a/Documentation/platforms/xtensa/esp32/index.rst +++ b/Documentation/platforms/xtensa/esp32/index.rst @@ -99,6 +99,22 @@ These steps are given in the setup guide in Building and flashing NuttX =========================== +Installing esptool +------------------ + +First, make sure that ``esptool.py`` is installed and up-to-date. +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>=4.8.1``. + +.. warning:: + Installing ``esptool.py`` may required a Python virtual environment on newer systems. + This will be the case if the ``pip install`` command throws an error such as: + ``error: externally-managed-environment``. + + If you are not familiar with virtual environments, refer to `Managing esptool on virtual environment`_ for instructions on how to install ``esptool.py``. + + Bootloader and partitions ------------------------- @@ -127,20 +143,66 @@ Simple Boot is used, for instance):: Building and Flashing --------------------- -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==4.8.dev4``. - -It's a two-step process where the first converts the ELF file into an ESP32 compatible binary -and the second flashes it to the board. These steps are included in the build system and it is +This is a two-step process where the first step converts the ELF file into an ESP32 compatible binary +and the second step 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= ESPTOOL_BINDIR=./ -where ```` 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. +where: + +* ``ESPTOOL_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. + +Flashing NSH Example +-------------------- + +This example shows how to build and flash the ``nsh`` defconfig for the ESP32-DevKitC board:: + + $ cd nuttx + $ make distclean + $ ./tools/configure.sh esp32-devkitc:nsh + $ make -j$(nproc) + +When the build is complete, the firmware can be flashed to the board using the command:: + + $ make -j$(nproc) flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ + +where ```` is the serial port where the board is connected:: + + $ make flash ESPTOOL_PORT=/dev/ttyUSB0 ESPTOOL_BINDIR=./ + CP: nuttx.hex + MKIMAGE: ESP32 binary + esptool.py -c esp32 elf2image --ram-only-header -fs 4MB -fm dio -ff 40m -o nuttx.bin nuttx + esptool.py v4.8.1 + Creating esp32 image... + Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended. + Merged 1 ELF section + Successfully created esp32 image. + Generated: nuttx.bin + esptool.py -c esp32 -p /dev/ttyUSB0 -b 921600 write_flash -fs detect -fm dio -ff 40m 0x1000 nuttx.bin + esptool.py v4.8.1 + Serial port /dev/ttyUSB0 + Connecting..... + Chip is ESP32-D0WD-V3 (revision v3.1) + [...] + Flash will be erased from 0x00001000 to 0x00032fff... + Flash params set to 0x0230 + Compressed 203816 bytes to 74735... + Wrote 203816 bytes (74735 compressed) at 0x00001000 in 2.2 seconds (effective 744.4 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting via RTS pin... + + +Now opening the serial port with a terminal emulator should show the NuttX console:: + + $ picocom -b 115200 /dev/ttyUSB0 + NuttShell (NSH) NuttX-12.8.0 + nsh> uname -a + NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 20:31:15 xtensa esp32-devkitc Debugging ========= @@ -330,6 +392,7 @@ Peripheral Support NOTES ADC No AES Yes Bluetooth Yes +Camera No CAN/TWAI Yes DMA Yes DAC Yes One-shot @@ -338,7 +401,8 @@ Ethernet Yes GPIO Yes I2C Yes Master and Slave mode supported I2S Yes -LED_PWM Yes +LCD No There is support for SPI displays +LED/PWM Yes MCPWM Yes Pulse_CNT Yes RMT Yes @@ -355,7 +419,7 @@ Timers Yes Touch Yes UART Yes Watchdog Yes -Wifi Yes +Wi-Fi Yes ========== ======= ===== Memory Map @@ -784,6 +848,72 @@ Things to Do 3. See SMP-related issues above +_`Managing esptool on virtual environment` +========================================== + +This section describes how to install ``esptool``, ``imgtool`` or any other Python packages in a +proper environment. + +Normally, a Linux-based OS would already have Python 3 installed by default. Up to a few years ago, +you could simply call ``pip install`` to install packages globally. However, this is no longer recommended +as it can lead to conflicts between packages and versions. The recommended way to install Python packages +is to use a virtual environment. + +A virtual environment is a self-contained directory that contains a Python installation for a particular +version of Python, plus a number of additional packages. You can create a virtual environment for each +project you are working on, and install the required packages in that environment. + +Two alternatives are explained below, you can select any one of those. + +Using pipx (recommended) +------------------------ + +``pipx`` is a tool that makes it easy to install Python packages in a virtual environment. To install +``pipx``, you can run the following command (using apt as example):: + + $ apt install pipx + +Once you have installed ``pipx``, you can use it to install Python packages in a virtual environment. For +example, to install the ``esptool`` package, you can run the following command:: + + $ pipx install esptool + +This will create a new virtual environment in the ``~/.local/pipx/venvs`` directory, which contains the +``esptool`` package. You can now use the ``esptool`` command as normal, and so will the build system. + +Make sure to run ``pipx ensurepath`` to add the ``~/.local/bin`` directory to your ``PATH``. This will +allow you to run the ``esptool`` command from any directory. + +Using venv (alternative) +------------------------ +To create a virtual environment, you can use the ``venv`` module, which is included in the Python standard +library. To create a virtual environment, you can run the following command:: + + $ python3 -m venv myenv + +This will create a new directory called ``myenv`` in the current directory, which contains a Python +installation and a copy of the Python standard library. To activate the virtual environment, you can run +the following command:: + + $ source myenv/bin/activate + +This will change your shell prompt to indicate that you are now working in the virtual environment. You can +now install packages using ``pip``. For example, to install the ``esptool`` package, you can run the following +command:: + + $ pip install esptool + +This will install the ``esptool`` package in the virtual environment. You can now use the ``esptool`` command as +normal. When you are finished working in the virtual environment, you can deactivate it by running the following +command:: + + $ deactivate + +This will return your shell prompt to its normal state. You can reactivate the virtual environment at any time by +running the ``source myenv/bin/activate`` command again. You can also delete the virtual environment by deleting +the directory that contains it. + + Supported Boards ================ diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst index 3c07f039389..542bee73186 100644 --- a/Documentation/platforms/xtensa/esp32s2/index.rst +++ b/Documentation/platforms/xtensa/esp32s2/index.rst @@ -92,6 +92,22 @@ These steps are given in the setup guide in Building and flashing NuttX =========================== +Installing esptool +------------------ + +First, make sure that ``esptool.py`` is installed and up-to-date. +This tool is used to convert the ELF to a compatible ESP32-S2 image and to flash the image into the board. + +It can be installed with: ``pip install esptool>=4.8.1``. + +.. warning:: + Installing ``esptool.py`` may required a Python virtual environment on newer systems. + This will be the case if the ``pip install`` command throws an error such as: + ``error: externally-managed-environment``. + + If you are not familiar with virtual environments, refer to `Managing esptool on virtual environment`_ for instructions on how to install ``esptool.py``. + + Bootloader and partitions ------------------------- @@ -120,20 +136,64 @@ Simple Boot is used, for instance):: Building and Flashing --------------------- -First, make sure that ``esptool.py`` is installed. This tool is used to convert the ELF to a -compatible ESP32-S2 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-S2 compatible binary -and the second flashes it to the board. These steps are included in the build system and it is +This is a two-step process where the first step converts the ELF file into an ESP32-S2 compatible binary +and the second step 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= ESPTOOL_BINDIR=./ -where ```` 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. +where: + +* ``ESPTOOL_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. + +Flashing NSH Example +-------------------- + +This example shows how to build and flash the ``nsh`` defconfig for the ESP32-S2-Saola-1 board:: + + $ cd nuttx + $ make distclean + $ ./tools/configure.sh esp32s2-saola-1:nsh + $ make -j$(nproc) + +When the build is complete, the firmware can be flashed to the board using the command:: + + $ make -j$(nproc) flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ + +where ```` is the serial port where the board is connected:: + + $ make flash ESPTOOL_PORT=/dev/ttyUSB0 ESPTOOL_BINDIR=./ + CP: nuttx.hex + MKIMAGE: ESP32-S2 binary + esptool.py -c esp32s2 elf2image --ram-only-header -fs 4MB -fm dio -ff 40m -o nuttx.bin nuttx + esptool.py v4.8.1 + Creating esp32s2 image... + Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended. + Merged 1 ELF section + Successfully created esp32s2 image. + Generated: nuttx.bin + esptool.py -c esp32s2 -p /dev/ttyUSB0 -b 921600 write_flash -fs detect -fm dio -ff 40m 0x1000 nuttx.bin + esptool.py v4.8.1 + Serial port /dev/ttyUSB0 + Connecting.... + Chip is ESP32-S2 (revision v0.0) + [...] + Flash will be erased from 0x00001000 to 0x00032fff... + Compressed 202280 bytes to 71796... + Wrote 202280 bytes (71796 compressed) at 0x00001000 in 2.3 seconds (effective 698.5 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting via RTS pin... + +Now opening the serial port with a terminal emulator should show the NuttX console:: + + $ picocom -b 115200 /dev/ttyUSB0 + NuttShell (NSH) NuttX-12.8.0 + nsh> uname -a + NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 20:26:00 xtensa esp32s2-saola-1 Debugging ========= @@ -319,15 +379,15 @@ Peripheral Support NOTES ADC No AES No CAN/TWAI Yes +DAC No DMA Yes -eFuse No -Ethernet No +eFuse Yes GPIO Yes I2C Yes Master and Slave mode supported I2S Yes -LED_PWM No +LED/PWM Yes Pulse_CNT Yes -RMT No +RMT Yes RNG Yes RSA No RTC Yes @@ -338,8 +398,9 @@ SPIRAM Yes Timers Yes Touch Yes UART Yes +USB OTG No Watchdog Yes -Wifi Yes +Wi-Fi Yes ========== ======= ===== Memory Map @@ -637,6 +698,71 @@ to ``Application image secondary slot``. and change usage mode to ``Release`` in `System Type --> Application Image Configuration --> Enable usage mode`. **After disabling UART Download Mode you will not be able to flash other images through UART.** +_`Managing esptool on virtual environment` +========================================== + +This section describes how to install ``esptool``, ``imgtool`` or any other Python packages in a +proper environment. + +Normally, a Linux-based OS would already have Python 3 installed by default. Up to a few years ago, +you could simply call ``pip install`` to install packages globally. However, this is no longer recommended +as it can lead to conflicts between packages and versions. The recommended way to install Python packages +is to use a virtual environment. + +A virtual environment is a self-contained directory that contains a Python installation for a particular +version of Python, plus a number of additional packages. You can create a virtual environment for each +project you are working on, and install the required packages in that environment. + +Two alternatives are explained below, you can select any one of those. + +Using pipx (recommended) +------------------------ + +``pipx`` is a tool that makes it easy to install Python packages in a virtual environment. To install +``pipx``, you can run the following command (using apt as example):: + + $ apt install pipx + +Once you have installed ``pipx``, you can use it to install Python packages in a virtual environment. For +example, to install the ``esptool`` package, you can run the following command:: + + $ pipx install esptool + +This will create a new virtual environment in the ``~/.local/pipx/venvs`` directory, which contains the +``esptool`` package. You can now use the ``esptool`` command as normal, and so will the build system. + +Make sure to run ``pipx ensurepath`` to add the ``~/.local/bin`` directory to your ``PATH``. This will +allow you to run the ``esptool`` command from any directory. + +Using venv (alternative) +------------------------ +To create a virtual environment, you can use the ``venv`` module, which is included in the Python standard +library. To create a virtual environment, you can run the following command:: + + $ python3 -m venv myenv + +This will create a new directory called ``myenv`` in the current directory, which contains a Python +installation and a copy of the Python standard library. To activate the virtual environment, you can run +the following command:: + + $ source myenv/bin/activate + +This will change your shell prompt to indicate that you are now working in the virtual environment. You can +now install packages using ``pip``. For example, to install the ``esptool`` package, you can run the following +command:: + + $ pip install esptool + +This will install the ``esptool`` package in the virtual environment. You can now use the ``esptool`` command as +normal. When you are finished working in the virtual environment, you can deactivate it by running the following +command:: + + $ deactivate + +This will return your shell prompt to its normal state. You can reactivate the virtual environment at any time by +running the ``source myenv/bin/activate`` command again. You can also delete the virtual environment by deleting +the directory that contains it. + Supported Boards ================ diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst index cc79ddf2155..714d52f8208 100644 --- a/Documentation/platforms/xtensa/esp32s3/index.rst +++ b/Documentation/platforms/xtensa/esp32s3/index.rst @@ -99,6 +99,21 @@ These steps are given in the setup guide in Building and flashing NuttX =========================== +Installing esptool +------------------ + +First, make sure that ``esptool.py`` is installed and up-to-date. +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.1``. + +.. warning:: + Installing ``esptool.py`` may required a Python virtual environment on newer systems. + This will be the case if the ``pip install`` command throws an error such as: + ``error: externally-managed-environment``. + + If you are not familiar with virtual environments, refer to `Managing esptool on virtual environment`_ for instructions on how to install ``esptool.py``. + Bootloader and partitions ------------------------- @@ -127,20 +142,65 @@ Simple Boot is used, for instance):: 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 +This is a two-step process where the first step converts the ELF file into an ESP32-S3 compatible binary +and the second step 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= ESPTOOL_BINDIR=./ -where ```` 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. +where: + +* ``ESPTOOL_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. + +Flashing NSH Example +-------------------- + +This example shows how to build and flash the ``nsh`` defconfig for the ESP32-S3-DevKitC-1 board:: + + $ cd nuttx + $ make distclean + $ ./tools/configure.sh esp32s3-devkit:nsh + $ make -j$(nproc) + +When the build is complete, the firmware can be flashed to the board using the command:: + + $ make -j$(nproc) flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ + +where ```` is the serial port where the board is connected:: + + $ make flash ESPTOOL_PORT=/dev/ttyUSB0 ESPTOOL_BINDIR=./ + CP: nuttx.hex + MKIMAGE: ESP32-S3 binary + esptool.py -c esp32s3 elf2image --ram-only-header -fs 4MB -fm dio -ff 40m -o nuttx.bin nuttx + esptool.py v4.8.1 + Creating esp32s3 image... + Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended. + Merged 1 ELF section + Successfully created esp32s3 image. + Generated: nuttx.bin + esptool.py -c esp32s3 -p /dev/ttyUSB0 -b 921600 write_flash -fs detect -fm dio -ff 40m 0x0000 nuttx.bin + esptool.py v4.8.1 + Serial port /dev/ttyUSB0 + Connecting.... + Chip is ESP32-S3 (QFN56) (revision v0.1) + [...] + Flash will be erased from 0x00000000 to 0x00032fff... + Flash params set to 0x0230 + Compressed 206776 bytes to 74469... + Wrote 206776 bytes (74469 compressed) at 0x00000000 in 2.7 seconds (effective 620.3 kbit/s)... + Hash of data verified. + + Leaving... + Hard resetting via RTS pin... + +Now opening the serial port with a terminal emulator should show the NuttX console:: + + $ picocom -b 115200 /dev/ttyUSB0 + NuttShell (NSH) NuttX-12.8.0 + nsh> uname -a + NuttX 12.8.0 759d37b97c-dirty Mar 5 2025 20:23:46 xtensa esp32s3-devkit Debugging ========= @@ -348,26 +408,26 @@ The following list indicates the state of peripherals' support in NuttX: ========== ======= ===== Peripheral Support NOTES ========== ======= ===== -ADC YES -AES YES -Bluetooth No -CAMERA No +ADC Yes +AES Yes +Bluetooth Yes +Camera No CAN/TWAI Yes DMA Yes -eFuse No +eFuse Yes GPIO Yes I2C Yes Master and Slave mode supported I2S Yes LCD No -LED_PWM No +LED/PWM Yes MCPWM Yes Pulse_CNT Yes -RMT No -RNG No +RMT Yes +RNG Yes RSA No RTC Yes -SD/MMC Yes SDIO No +SD/MMC Yes SHA No SPI Yes SPIFLASH Yes @@ -375,7 +435,7 @@ SPIRAM Yes Timers Yes Touch Yes UART Yes -USB OTG No +USB OTG Yes CDC/ACM console supported USB SERIAL Yes Watchdog Yes Wi-Fi Yes WPA3-SAE supported @@ -452,6 +512,72 @@ Set the attribute ``__attribute__ ((section (".ext_ram.bss")))`` to the variable This is particularly useful when the internal RAM is not enough to hold all the data. +_`Managing esptool on virtual environment` +========================================== + +This section describes how to install ``esptool``, ``imgtool`` or any other Python packages in a +proper environment. + +Normally, a Linux-based OS would already have Python 3 installed by default. Up to a few years ago, +you could simply call ``pip install`` to install packages globally. However, this is no longer recommended +as it can lead to conflicts between packages and versions. The recommended way to install Python packages +is to use a virtual environment. + +A virtual environment is a self-contained directory that contains a Python installation for a particular +version of Python, plus a number of additional packages. You can create a virtual environment for each +project you are working on, and install the required packages in that environment. + +Two alternatives are explained below, you can select any one of those. + +Using pipx (recommended) +------------------------ + +``pipx`` is a tool that makes it easy to install Python packages in a virtual environment. To install +``pipx``, you can run the following command (using apt as example):: + + $ apt install pipx + +Once you have installed ``pipx``, you can use it to install Python packages in a virtual environment. For +example, to install the ``esptool`` package, you can run the following command:: + + $ pipx install esptool + +This will create a new virtual environment in the ``~/.local/pipx/venvs`` directory, which contains the +``esptool`` package. You can now use the ``esptool`` command as normal, and so will the build system. + +Make sure to run ``pipx ensurepath`` to add the ``~/.local/bin`` directory to your ``PATH``. This will +allow you to run the ``esptool`` command from any directory. + +Using venv (alternative) +------------------------ +To create a virtual environment, you can use the ``venv`` module, which is included in the Python standard +library. To create a virtual environment, you can run the following command:: + + $ python3 -m venv myenv + +This will create a new directory called ``myenv`` in the current directory, which contains a Python +installation and a copy of the Python standard library. To activate the virtual environment, you can run +the following command:: + + $ source myenv/bin/activate + +This will change your shell prompt to indicate that you are now working in the virtual environment. You can +now install packages using ``pip``. For example, to install the ``esptool`` package, you can run the following +command:: + + $ pip install esptool + +This will install the ``esptool`` package in the virtual environment. You can now use the ``esptool`` command as +normal. When you are finished working in the virtual environment, you can deactivate it by running the following +command:: + + $ deactivate + +This will return your shell prompt to its normal state. You can reactivate the virtual environment at any time by +running the ``source myenv/bin/activate`` command again. You can also delete the virtual environment by deleting +the directory that contains it. + + Supported Boards ================