.. _esp32c3: ================== Espressif ESP32-C3 ================== The ESP32-C3 is an ultra-low-power and highly integrated SoC with a RISC-V core and supports 2.4 GHz Wi-Fi and Bluetooth Low Energy. * Address Space - 800 KB of internal memory address space accessed from the instruction bus - 560 KB of internal memory address space accessed from the data bus - 1016 KB of peripheral address space - 8 MB of external memory virtual address space accessed from the instruction bus - 8 MB of external memory virtual address space accessed from the data bus - 480 KB of internal DMA address space * Internal Memory - 384 KB ROM - 400 KB SRAM (16 KB can be configured as Cache) - 8 KB of SRAM in RTC * External Memory - Up to 16 MB of external flash * Peripherals - 35 peripherals * GDMA - 7 modules are capable of DMA operations. ESP32-C3 Toolchain ================== A generic RISC-V toolchain can be used to build ESP32-C3 projects. It's recommended to use the same toolchain used by NuttX CI. Please refer to the Docker `container `_ and check for the current compiler version being used. For instance: .. code-block:: ############################################################################### # Build image for tool required by RISCV builds ############################################################################### FROM nuttx-toolchain-base AS nuttx-toolchain-riscv # Download the latest RISCV GCC toolchain prebuilt by xPack RUN mkdir riscv-none-elf-gcc && \ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ | tar -C riscv-none-elf-gcc --strip-components 1 -xz It uses the xPack's prebuilt toolchain based on GCC 13.2.0-2. Installing ---------- First, create a directory to hold the toolchain: .. code-block:: console $ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc Download and extract toolchain: .. code-block:: console $ curl -s -L "https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/download/v13.2.0-2/xpack-riscv-none-elf-gcc-13.2.0-2-linux-x64.tar.gz" \ | tar -C /path/to/your/toolchain/riscv-none-elf-gcc --strip-components 1 -xz Add the toolchain to your `PATH`: .. code-block:: console $ echo "export PATH=/path/to/your/toolchain/riscv-none-elf-gcc/bin:$PATH" >> ~/.bashrc You can edit your shell's rc files if you don't use bash. Building and flashing NuttX =========================== Bootloader and partitions ------------------------- NuttX can boot the ESP32-C3 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, like `Secure Boot and Flash Encryption`_, 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-C3 image and to flash the image into the board. It can be installed with: ``pip install esptool==4.8.dev4``. Configure the NuttX project: ``./tools/configure.sh esp32c3-generic:nsh`` Run ``make`` to build the project. Note that the conversion mentioned above is included in the build process. The ``esptool.py`` is used to flash all the binaries. However, this is also included in the build process and we can build and flash with:: make flash ESPTOOL_PORT= ESPTOOL_BINDIR=./ Where ```` is typically ``/dev/ttyUSB0`` or similar and ``./`` is the path to the folder containing the externally-built 2nd stage bootloader for the ESP32-C3 as explained above. Debugging ========= This section describes debugging techniques for the ESP32-C3. Debugging with ``openocd`` and ``gdb`` -------------------------------------- Espressif uses a specific version of OpenOCD to support ESP32-C3: `openocd-esp32 `_. Please check `Building OpenOCD from Sources `_ for more information on how to build OpenOCD for ESP32-C3. ESP32-C3 has a built-in JTAG circuitry and can be debugged without any additional chip. Only an USB cable connected to the D+/D- pins is necessary: ============ ========== ESP32-C3 Pin USB Signal ============ ========== GPIO18 D- GPIO19 D+ 5V V_BUS GND Ground ============ ========== .. note:: One must configure the USB drivers to enable JTAG communication. Please check `Configure USB Drivers `_ for more information. OpenOCD can then be used:: openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-builtin.cfg If you want to debug with an external JTAG adapter it can be connected as follows: ============ =========== ESP32-C6 Pin JTAG Signal ============ =========== GPIO4 TMS GPIO5 TDI GPIO6 TCK GPIO7 TDO ============ =========== Furthermore, an efuse needs to be burnt to be able to debug:: espefuse.py -p burn_efuse DIS_USB_JTAG .. warning:: Burning eFuses is an irreversible operation, so please consider the above option before starting the process. OpenOCD can then be used:: openocd -c 'set ESP_RTOS hwthread; set ESP_FLASH_SIZE 0' -f board/esp32c3-ftdi.cfg Once OpenOCD is running, you can use GDB to connect to it and debug your application:: riscv-none-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. Stack Dump and Backtrace Dump ----------------------------- NuttX has a feature to dump the stack of a task and to dump the backtrace of it (and of all the other tasks). This feature is useful to debug the system when it is not behaving as expected, especially when it is crashing. In order to enable this feature, the following options must be enabled in the NuttX configuration: ``CONFIG_SCHED_BACKTRACE``, ``CONFIG_DEBUG_SYMBOLS`` and, optionally, ``CONFIG_ALLSYMS``. .. note:: The first two options enable the backtrace dump. The third option enables the backtrace dump with the associated symbols, but increases the size of the generated NuttX binary. Espressif also provides a tool to translate the backtrace dump into a human-readable format. This tool is called ``btdecode.sh`` and is available at ``tools/espressif/btdecode.sh`` of NuttX repository. .. note:: This tool is not necessary if ``CONFIG_ALLSYMS`` is enabled. In this case, the backtrace dump contains the function names. Example - Crash Dump ^^^^^^^^^^^^^^^^^^^^ A typical crash dump, caused by an illegal load with ``CONFIG_SCHED_BACKTRACE`` and ``CONFIG_DEBUG_SYMBOLS`` enabled, is shown below:: riscv_exception: EXCEPTION: Store/AMO access fault. MCAUSE: 00000007, EPC: 42012df2, MT0 riscv_exception: PANIC!!! Exception = 00000007 _assert: Current Version: NuttX 10.4.0 2ae3246e40-dirty Sep 19 2024 14:34:41 risc-v _assert: Assertion failed panic: at file: :0 task: backtrace process: backtrace 0x42012dac up_dump_register: EPC: 42012df2 up_dump_register: A0: 0000005a A1: 3fc88a54 A2: 00000001 A3: 00000088 up_dump_register: A4: 00007fff A5: 00000001 A6: 00000000 A7: 00000000 up_dump_register: T0: 00000000 T1: 00000000 T2: ffffffff T3: 00000000 up_dump_register: T4: 00000000 T5: 00000000 T6: 00000000 up_dump_register: S0: 3fc87b16 S1: 3fc87b00 S2: 00000000 S3: 00000000 up_dump_register: S4: 00000000 S5: 00000000 S6: 00000000 S7: 00000000 up_dump_register: S8: 00000000 S9: 00000000 S10: 00000000 S11: 00000000 up_dump_register: SP: 3fc88ab0 FP: 3fc87b16 TP: 00000000 RA: 42012df2 dump_stack: User Stack: dump_stack: base: 0x3fc87b20 dump_stack: size: 00004048 dump_stack: sp: 0x3fc88ab0 stack_dump: 0x3fc88a90: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00001800 stack_dump: 0x3fc88ab0: 00000000 3fc87718 42012dac 42006dd0 00000000 00000000 3fc87b00 00000002 stack_dump: 0x3fc88ad0: 00000000 00000000 00000000 42004d4c 00000000 00000000 00000000 00000000 stack_dump: 0x3fc88af0: 00000000 00000000 00000000 00000000 00000000 00000000 00000000 00000000 sched_dumpstack: backtrace| 2: 0x42012df2 dump_tasks: PID GROUP PRI POLICY TYPE NPX STATE EVENT SIGMASK STACKBASE STACKSIZE COMMAND dump_tasks: ---- --- --- -------- ------- --- ------- ---------- ---------------- 0x3fc845e0 1536 irq dump_task: 0 0 0 FIFO Kthread - Ready 0000000000000000 0x3fc85d18 2032 Idle_Task dump_task: 1 1 100 RR Task - Waiting Semaphore 0000000000000000 0x3fc86c30 2000 nsh_main dump_task: 2 2 255 RR Task - Running 0000000000000000 0x3fc87b20 4048 backtrace task sched_dumpstack: backtrace| 0: 0x42008420 sched_dumpstack: backtrace| 1: 0x420089a8 sched_dumpstack: backtrace| 2: 0x42012df2 The lines starting with ``sched_dumpstack`` show the backtrace of the tasks. By checking it, it is possible to track the root cause of the crash. Saving this output to a file and using the ``btdecode.sh``:: ./tools/btdecode.sh esp32c3 /tmp/backtrace.txt Backtrace for task 2: 0x42012df2: assert_on_task at backtrace_main.c:158 (inlined by) backtrace_main at backtrace_main.c:194 Backtrace dump for all tasks: Backtrace for task 2: 0x42012df2: assert_on_task at backtrace_main.c:158 (inlined by) backtrace_main at backtrace_main.c:194 Backtrace for task 1: 0x420089a8: sys_call2 at syscall.h:227 (inlined by) up_switch_context at riscv_switchcontext.c:95 Backtrace for task 0: 0x42008420: up_idle at esp_idle.c:74 The above output shows the backtrace of the tasks. By checking it, it is possible to track the functions that were being executed when the crash occurred. Peripheral Support ================== The following list indicates the state of peripherals' support in NuttX: =========== ======= ==================== Peripheral Support NOTES =========== ======= ==================== ADC No AES No Bluetooth No CAN/TWAI Yes CDC Console Yes Rev.3 DMA Yes eFuse No GPIO Yes I2C Yes LED_PWM Yes RNG No RSA No RTC Yes SHA No SPI Yes SPIFLASH Yes Timers Yes Touch No UART Yes Watchdog Yes XTWDT supported Wifi Yes WPA3-SAE supported =========== ======= ==================== Secure Boot and Flash Encryption ================================ Secure Boot ----------- Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that each piece of software that is being booted is signed. On an ESP32-C3, 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 `__). The Secure Boot process on the ESP32-C3 involves the following steps performed: 1. The first stage bootloader verifies the second stage bootloader's RSA-PSS signature. If the verification is successful, the first stage bootloader loads and executes the second stage bootloader. 2. When the second stage bootloader loads a particular application image, the application's signature (RSA, ECDSA or ED25519) is verified by MCUboot. If the verification is successful, the application image is executed. .. 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-C3's Secure boot `here `__. .. note:: As the bootloader image is built on top of the Hardware Abstraction Layer component of `ESP-IDF `_, the `API port by Espressif `_ will be used by MCUboot rather than the original NuttX port. Flash Encryption ---------------- Flash encryption is intended for encrypting the contents of the ESP32-C3's off-chip flash memory. Once this feature is enabled, firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout 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-C3's Flash Encryption `here `__. Prerequisites ------------- First of all, we need to install ``imgtool`` (the MCUboot utility application to manipulate binary images):: $ pip install imgtool We also need to make sure that the python modules are added to ``PATH``:: $ echo "PATH=$PATH:/home/$USER/.local/bin" >> ~/.bashrc Now, we will create a folder to store the generated keys (such as ``~/signing_keys``):: $ mkdir ~/signing_keys && cd ~/signing_keys With all set up, we can now generate keys to sign the bootloader and application binary images, respectively, of the compiled project:: $ espsecure.py generate_signing_key --version 2 bootloader_signing_key.pem $ imgtool keygen --key app_signing_key.pem --type rsa-3072 .. important:: The contents of the key files must be stored securely and kept secret. Enabling Secure Boot and Flash Encryption ----------------------------------------- To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps: 1. Enable experimental features in :menuselection:`Build Setup --> Show experimental options`; 2. Enable MCUboot in :menuselection:`Application Configuration --> Bootloader Utilities --> MCUboot`; 3. Change image type to ``MCUboot-bootable format`` in :menuselection:`System Type --> Application Image Configuration --> Application Image Format`; 4. Enable building MCUboot from the source code by selecting ``Build binaries from source``; in :menuselection:`System Type --> Application Image Configuration --> Source for bootloader binaries`; 5. Enable Secure Boot in :menuselection:`System Type --> Application Image Configuration --> Enable hardware Secure Boot in bootloader`; 6. If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in :menuselection:`System Type --> Application Image Configuration --> Enable Flash Encryption on boot`. Now you can design an update and confirm agent to your application. Check the `MCUboot design guide `_ and the `MCUboot Espressif port documentation `_ for more information on how to apply MCUboot. Also check some `notes about the NuttX MCUboot port `_, the `MCUboot porting guide `_ and some `examples of MCUboot applied in NuttX applications `_. 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 `_). 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``. When creating update images, make sure to change :menuselection:`System Type --> Application Image Configuration --> Target slot for image flashing` to ``Application image secondary slot``. .. important:: When deploying your application, make sure to disable UART Download Mode by selecting ``Permanently disabled`` in :menuselection:`System Type --> Application Image Configuration --> UART ROM download mode` 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.** Supported Boards ================ .. toctree:: :glob: :maxdepth: 1 boards/*/*