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:
###############################################################################
# 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:
$ mkdir -p /path/to/your/toolchain/riscv-none-elf-gcc
Download and extract toolchain:
$ 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:
$ 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.
$ 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=<port> ESPTOOL_BINDIR=./
Where <port>
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 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 <port> 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 Debugging for more information about debugging techniques.
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:
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.
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:
Enable experimental features in
;Enable MCUboot in
;Change image type to
MCUboot-bootable format
in ;Enable building MCUboot from the source code by selecting
Build binaries from source
; in ;Enable Secure Boot in
;If you want to protect the SPI Bus against data sniffing, you can enable Flash Encryption in
.
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
and compile it using make -j ESPSEC_KEYDIR=~/signing_keys
.
When creating update images, make sure to change Application image secondary slot
.
Important
When deploying your application, make sure to disable UART Download Mode by selecting Permanently disabled
in
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.