NOTE: The following instructions assume a Linux or Windows Subsystem for Linux (WSL) host. WSL installation and setup instructions can be found here.
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.
git clone --recurse-submodules https://github.com/FreeRTOS/Lab-Project-FreeRTOS-MCUBoot.git
Apply the patches required for the bootloader and application.
git -C lib/mcuboot apply ../../patches/mcuboot.patch
git -C lib/mcuboot/boot/espressif/hal/esp-idf/ apply ../../../../../../patches/esp-idf.patch
Configure the ESP-IDF tools, then enter the bootloader project directory.
Connect your esp32 and identify it's USB descriptor (for example '/dev/ttyUSB0'), then set this ID.
Decide which, if any, cryptographic verification you want from the following choices:
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.
cmake -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
definition in the command above.
Finally, to upload the bootloader to the board, run the following.
cmake --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
Enter the application project directory.
Similarly, when generating build files for the application, you must set
to match whichever scheme was selected for the Bootloader. Moreover, you must set
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
KEY_PATH definitions below. Finally, you can set the application version by adding
-DAPP_VERSION=X.Y.Z to the command below.
cmake -DSIGNING_SCHEME=ecdsa-p256 -DKEY_PATH=../bootloader/mcuboot-private-key.pem -GNinja -B build
Build the application.
cmake --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:
cmake --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:
cmake --build build --target mcuboot-app-upgrade
Finally, view the output from the device.
Debugging The Application
Configure the ESP-IDF tools in two separate shell sessions using the following commands in each:
In one terminal, enter the app directory and start the OpenOCD server.
In the other terminal, enter the app directory and start the GDB session.
Serial Boot Mode and MCUMGR Interface
Serial boot mode is enabled by default, but can be disabled by setting
to 0 in
mcuboot_config.h located in
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
mcumgr can be found here.
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
Define a connection for
mcumgr setting the USB descriptor that corresponds with your
USB-to-UART that connects with the device.
mcumgr 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
To list images on the device:
mcumgr -c esp image list
To upload an image:
mcumgr -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
To reset the board:
mcumgr -c esp reset
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.