Building and using MCUboot with Espressif’s chips

The Espressif port is build on top of ESP-IDF HAL, therefore it is required in order to build MCUboot for Espressif SoCs.

Documentation about the MCUboot bootloader design, operation and features can be found in the design document.

SoC support availability

The current port is available for use in the following SoCs within the OSes:

  • ESP32
    • Zephyr RTOS - WIP
    • NuttX
  • ESP32-S2
    • Zephyr RTOS - WIP
    • NuttX - WIP

Installing Requirements and Dependencies

  1. Install additional packages required for development with MCUboot:
  cd ~/mcuboot  # or to your directory where MCUboot is cloned
  pip3 install --user -r scripts/requirements.txt
  1. Update the submodules needed by the Espressif port. This may take a while.
git submodule update --init --recursive --checkout boot/espressif/hal/esp-idf
  1. Next, get the Mbed TLS submodule required by MCUboot.
    git submodule update --init --recursive ext/mbedtls
  2. Now we need to install IDF dependencies and set environment variables. This step may take some time:
    cd boot/espressif/hal/esp-idf
    . ./
    cd ../..

Building the bootloader itself

The MCUboot Espressif port bootloader is built using the toolchain and tools provided by ESP-IDF. Additional configuration related to MCUboot features and slot partitioning may be made using the bootloader.conf.

Note: Replace <target> with the target ESP32 family (like esp32, esp32s2 and others).

  1. Compile and generate the ELF:
cmake -DCMAKE_TOOLCHAIN_FILE=tools/toolchain-<target>.cmake -DMCUBOOT_TARGET=<target> -B build -GNinja
cmake --build build/
  1. Convert the ELF to the final bootloader image, ready to be flashed: --chip <target> elf2image --flash_mode dio --flash_freq 40m -o build/mcuboot_<target>.bin build/mcuboot_<target>.elf
  1. Flash MCUboot in your board: -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <target> write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 build/mcuboot_<target>.bin

You may adjust the port <PORT> (like /dev/ttyUSB0) and baud rate <BAUD> (like 2000000) according to the connection with your board.