LibrariesFreeRTOS MCUBoot

Updated May 2025

MCUBoot Demo

Introduction

NOTE: The following instructions assume a Linux or Windows Subsystem for Linux (WSL) host. WSL installation and setup instructions can be found here external_link .

The demo currently supports the esp32 architecture. The following instructions are specific to this hardware.

The demo consists of MCUBoot booting an application which first disables a bootloader watchdog timer, prints its version number, then confirms itself so it won't be reverted if it's an update. The app proceeds to periodically print "hello world".

The demo also details the application signing and upgrade process, and provides a porting guide for implementing on other SoCs. Finally, use of

mcumgr

is demonstrated for retrieving image diagnostics, modifying/uploading images, and triggering other board functions from your host PC.

Building and Uploading The Bootloader

Download then enter the repo directory.

1git clone --recurse-submodules https://github.com/FreeRTOS/Lab-Project-FreeRTOS-MCUBoot.git
2cd Lab-Project-FreeRTOS-MCUBoot

Apply the patches required for the bootloader and application.

1git -C lib/mcuboot apply ../../patches/mcuboot.patch
2git -C lib/mcuboot/boot/espressif/hal/esp-idf/ apply ../../../../../../patches/esp-idf.patch

Configure the ESP-IDF tools, then enter the bootloader project directory.

1./lib/mcuboot/boot/espressif/hal/esp-idf/install.sh
2source lib/mcuboot/boot/espressif/hal/esp-idf/export.sh
3cd proj/espressif/esp32/bootloader

Connect your esp32 and identify it's USB descriptor (for example '/dev/ttyUSB0'), then set this ID.
```
1export ESPPORT=/dev/<USB>
```
Decide which, if any, cryptographic verification you want from the following choices:
- ecdsa-p256
- rsa-2048
- rsa-3072
If you want cryptographic image verification, generate the build files as follows, setting
```
SIGNING_SCHEME
```
to be exactly equal to one of the choices above.
```
1cmake -GNinja -DSIGNING_SCHEME=ecdsa-p256 -B build
```
This will generate a private key, of the selected scheme, in the bootloader project directory. The name defaults as
```
mcuboot-private-key.pem
```
. The private key will be used for signing the application images. Meanwhile, the cmake targets take care of embedding the public key in the bootloader, so it can verify the images.

If you don't want cryptographic image verfication you can omit the
```
SIGNING_SCHEME
```
definition in the command above.

Finally, to upload the bootloader to the board, run the following.

1cmake --build build --target mcuboot-flash

Building and Uploading The Application

After building and flashing the bootloader, proceed with the following. If you're in a new shell session you likely need to re-run the steps above for configuring the IDF toolchain and set

ESPPORT

Enter the application project directory.

1cd proj/espressif/esp32/app

Similarly, when generating build files for the application, you must set
```
SIGNING_SCHEME
```
to match whichever scheme was selected for the Bootloader. Moreover, you must set
```
KEY_PATH
```
to point to the private key generated by the bootloader project. If you opted out of cryptographic image verification in the bootloader, you must similarly omit the
```
SIGNING_SCHEME
```
and
```
KEY_PATH
```
definitions below. Finally, you can set the application version by adding
```
-DAPP_VERSION=X.Y.Z
```
to the command below.
```
1cmake -DSIGNING_SCHEME=ecdsa-p256 -DKEY_PATH=../bootloader/mcuboot-private-key.pem -GNinja -B build
```

Build the application.

1cmake --build build --target app

There are two options for uploading the image: directly flashing to the primary image slot, or flashing to the secondary image slot which prompts an upgrade on the subsequent boot if the image has a newer version than that of the primary image. If you don't yet have an image in the primary slot, then directly upload the image there:
```
1cmake --build build --target mcuboot-app-flash
```
When queuing an upgrade, if the secondary image has a newer version than the primary image, the two images will be swapped and the update image will be tentatively booted, and revert upon the subsequent boot if the update image does not confirm itself. Hence the application calls
```
boot_set_confirmed
```
so that it persists as the primary image. Updated images that don't do this will be reverted. To upgrade the image, perform the following:
```
1cmake --build build --target mcuboot-app-upgrade
```
Finally, view the output from the device.
```
1idf.py monitor
```

Debugging The Application

Configure the ESP-IDF tools in two separate shell sessions using the following commands in each:

1./lib/mcuboot/boot/espressif/hal/esp-idf/install.sh
2source lib/mcuboot/boot/espressif/hal/esp-idf/export.sh

In one terminal, enter the app directory and start the OpenOCD server.

1cd proj/espressif/esp32/app
2idf.py openocd

In the other terminal, enter the app directory and start the GDB session.

1cd proj/espressif/esp32/app
2idf.py gdb

Serial Boot Mode and MCUMGR Interface

Serial boot mode is enabled by default, but can be disabled by setting

MCUBOOT_SERIAL

to 0 in

mcuboot_config.h

located in

lib/mcuboot/boot/freertos

. The serial boot pin is checked during boot up, and if activated, serial boot mode is entered. For the demo, the serial boot pin is configured as

GPIO 5

, and is active high. Tying the serial boot pin to VCC will trigger serial mode, tying to GND will skip it. Once serial mode is running, you may interface the board with

mcumgr

. Installation instructions for

mcumgr

can be found here external_link

MCUMGR will communicate with the board via UART pins which, for this demo, are set as

GPIO 27 (RX)

and

GPIO 26 (TX)

. You can use a USB-to-UART cable such as this one external_link

Define a connection for

mcumgr

setting the USB descriptor that corresponds with your USB-to-UART that connects with the device.

1mcumgr conn add esp type="serial" connstring="dev=/dev/<USB>,baud=115200,mtu=256"

Tie the boot serial pin to VCC, then reset the board to enter serial boot recovery mode. The board will log that it has entered serial boot mode. You may proceed with the

mcumgr

interface.

To list images on the device:

1mcumgr -c esp image list

To upload an image:

1mcumgr -c esp image upload /path/to/mcuboot-image.bin

This expects a signed/formatted MCUBoot image. After building the application, this can be found in its build directory as

build/mcuboot-app.bin

To reset the board:

1mcumgr -c esp reset