Skip to content

espressif: fix MCUBoot OTA on Espressif devices. #16735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acassis merged 5 commits into from
Jul 22, 2025
Merged

espressif: fix MCUBoot OTA on Espressif devices. #16735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9caaddb
boards/xtensa: fixes SPI Flash for MCUBoot usage
fdcavalcanti Jul 11, 2025
d66441e
arch/xtensa: add E-Fuse support on ESP32S2
fdcavalcanti Jul 14, 2025
0a74b30
boards/risc-v: fixes SPI Flash for MCUBoot usage
fdcavalcanti Jul 11, 2025
c1e5e52
arch/risc-v: change offset for SPI Flash on Espressif devices
fdcavalcanti Jul 15, 2025
463506d
documentation: update documentation for MCUBoot on Espressif devices
fdcavalcanti Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -322,6 +322,21 @@ After successfully built and flashed, run on the boards's terminal::

nsh> i2schar

mcuboot_nsh
-----------

This configuration is the same as the ``nsh`` configuration, but it generates the application
image in a format that can be used by MCUboot. It also makes the ``make bootloader`` command to
build the MCUboot bootloader image using the Espressif HAL.

mcuboot_update_agent
--------------------

This configuration is used to represent an MCUboot image that contains an update agent
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.

Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update C3>` section to execute OTA update.

nimble
------

Expand Down
99 changes: 94 additions & 5 deletions Documentation/platforms/risc-v/esp32c3/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,11 +408,100 @@ Then, it can be customized in the menu :menuselection:`System Type --> ADC Confi

.. warning:: Maximum measurable voltage may saturate around 2900 mV.

.. _MCUBoot and OTA Update C3:

MCUBoot and OTA Update
======================

The ESP32-C3 supports over-the-air (OTA) updates using MCUBoot.

Read more about the MCUBoot for Espressif devices `here <https://docs.mcuboot.com/readme-espressif.html>`__.

Executing OTA Update
--------------------

This section describes how to execute OTA update using MCUBoot.

1. First build the default ``mcuboot_update_agent`` config. This image defaults to the primary slot and already comes with Wi-Fi settings enabled::

./tools/configure.sh esp32c3-generic:mcuboot_update_agent

2. Build the MCUBoot bootloader::

make bootloader

3. Finally, build the application image::

make

Flash the image to the board and verify it boots ok.
It should show the message "This is MCUBoot Update Agent image" before NuttShell is ready.

At this point, the board should be able to connect to Wi-Fi so we can download a new binary from our network::

NuttShell (NSH) NuttX-12.4.0
This is MCUBoot Update Agent image
nsh>
nsh> wapi psk wlan0 <wifi_ssid> 3
nsh> wapi essid wlan0 <wifi_password> 1
nsh> renew wlan0

Now, keep the board as is and execute the following commands to **change the MCUBoot target slot to the 2nd slot**
and modify the message of the day (MOTD) as a mean to verify the new image is being used.

1. Change the MCUBoot target slot to the 2nd slot::

kconfig-tweak -d CONFIG_ESPRESSIF_ESPTOOL_TARGET_PRIMARY
kconfig-tweak -e CONFIG_ESPRESSIF_ESPTOOL_TARGET_SECONDARY
kconfig-tweak --set-str CONFIG_NSH_MOTD_STRING "This is MCUBoot UPDATED image!"
make olddefconfig

.. note::
The same changes can be accomplished through ``menuconfig`` in :menuselection:`System Type --> Bootloader and Image Configuration --> Target slot for image flashing`
for MCUBoot target slot and in :menuselection:`System Type --> Bootloader and Image Configuration --> Search (motd) --> NSH Library --> Message of the Day` for the MOTD.

2. Rebuild the application image::

make

At this point the board is already connected to Wi-Fi and has the primary image flashed.
The new image configured for the 2nd slot is ready to be downloaded.

To execute OTA, create a simple HTTP server on the NuttX directory so we can access the binary remotely::

cd nuttxspace/nuttx
python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

On the board, execute the update agent, setting the IP address to the one on the host machine. Wait until image is transferred and the board should reboot automatically::

nsh> mcuboot_agent http://10.42.0.1:8000/nuttx.bin
MCUboot Update Agent example
Downloading from http://10.42.0.1:8000/nuttx.bin
Firmware Update size: 1048576 bytes
Received: 512 of 1048576 bytes [0%]
Received: 1024 of 1048576 bytes [0%]
Received: 1536 of 1048576 bytes [0%]
[.....]
Received: 1048576 of 1048576 bytes [100%]
Application Image successfully downloaded!
Requested update for next boot. Restarting...

NuttShell should now show the new MOTD, meaning the new image is being used::

NuttShell (NSH) NuttX-12.4.0
This is MCUBoot UPDATED image!
nsh>

Finally, the image is loaded but not confirmed.
To make sure it won't rollback to the previous image, you must confirm with ``mcuboot_confirm`` and reboot the board.
The OTA is now complete.

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
Expand Down Expand Up @@ -440,7 +529,7 @@ The Secure Boot process on the ESP32-C3 involves the following steps performed:
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
Expand All @@ -452,7 +541,7 @@ of flash will not be sufficient to recover most flash contents.
`here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html>`__.

Prerequisites
-------------
^^^^^^^^^^^^^

First of all, we need to install ``imgtool`` (the MCUboot utility application to manipulate binary
images)::
Expand All @@ -476,7 +565,7 @@ respectively, of the compiled project::
.. 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:

Expand Down
10 changes: 9 additions & 1 deletion Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -323,12 +323,20 @@ There is also support for an optional fault GPIO (defaults to GPIO9), which can
for quick motor braking. All GPIOs are configurable in ``menuconfig``.

mcuboot_nsh
--------------------
-----------

This configuration is the same as the ``nsh`` configuration, but it generates the application
image in a format that can be used by MCUboot. It also makes the ``make bootloader`` command to
build the MCUboot bootloader image using the Espressif HAL.

mcuboot_update_agent
--------------------

This configuration is used to represent an MCUboot image that contains an update agent
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.

Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update C6>` section to execute OTA update.

nsh
---

Expand Down
89 changes: 89 additions & 0 deletions Documentation/platforms/risc-v/esp32c6/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,6 +397,95 @@ Then, it can be customized in the menu :menuselection:`System Type --> ADC Confi
6 6
========== ===========

.. _MCUBoot and OTA Update C6:

MCUBoot and OTA Update
======================

The ESP32-C6 supports over-the-air (OTA) updates using MCUBoot.

Read more about the MCUBoot for Espressif devices `here <https://docs.mcuboot.com/readme-espressif.html>`__.

Executing OTA Update
--------------------

This section describes how to execute OTA update using MCUBoot.

1. First build the default ``mcuboot_update_agent`` config. This image defaults to the primary slot and already comes with Wi-Fi settings enabled::

./tools/configure.sh esp32c6-devkitc:mcuboot_update_agent

2. Build the MCUBoot bootloader::

make bootloader

3. Finally, build the application image::

make

Flash the image to the board and verify it boots ok.
It should show the message "This is MCUBoot Update Agent image" before NuttShell is ready.

At this point, the board should be able to connect to Wi-Fi so we can download a new binary from our network::

NuttShell (NSH) NuttX-12.4.0
This is MCUBoot Update Agent image
nsh>
nsh> wapi psk wlan0 <wifi_ssid> 3
nsh> wapi essid wlan0 <wifi_password> 1
nsh> renew wlan0

Now, keep the board as is and execute the following commands to **change the MCUBoot target slot to the 2nd slot**
and modify the message of the day (MOTD) as a mean to verify the new image is being used.

1. Change the MCUBoot target slot to the 2nd slot::

kconfig-tweak -d CONFIG_ESPRESSIF_ESPTOOL_TARGET_PRIMARY
kconfig-tweak -e CONFIG_ESPRESSIF_ESPTOOL_TARGET_SECONDARY
kconfig-tweak --set-str CONFIG_NSH_MOTD_STRING "This is MCUBoot UPDATED image!"
make olddefconfig

.. note::
The same changes can be accomplished through ``menuconfig`` in :menuselection:`System Type --> Bootloader and Image Configuration --> Target slot for image flashing`
for MCUBoot target slot and in :menuselection:`System Type --> Bootloader and Image Configuration --> Search (motd) --> NSH Library --> Message of the Day` for the MOTD.

2. Rebuild the application image::

make

At this point the board is already connected to Wi-Fi and has the primary image flashed.
The new image configured for the 2nd slot is ready to be downloaded.

To execute OTA, create a simple HTTP server on the NuttX directory so we can access the binary remotely::

cd nuttxspace/nuttx
python3 -m http.server
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

On the board, execute the update agent, setting the IP address to the one on the host machine. Wait until image is transferred and the board should reboot automatically::

nsh> mcuboot_agent http://10.42.0.1:8000/nuttx.bin
MCUboot Update Agent example
Downloading from http://10.42.0.1:8000/nuttx.bin
Firmware Update size: 1048576 bytes
Received: 512 of 1048576 bytes [0%]
Received: 1024 of 1048576 bytes [0%]
Received: 1536 of 1048576 bytes [0%]
[.....]
Received: 1048576 of 1048576 bytes [100%]
Application Image successfully downloaded!
Requested update for next boot. Restarting...

NuttShell should now show the new MOTD, meaning the new image is being used::

NuttShell (NSH) NuttX-12.4.0
This is MCUBoot UPDATED image!
nsh>

Finally, the image is loaded but not confirmed.
To make sure it won't rollback to the previous image, you must confirm with ``mcuboot_confirm`` and reboot the board.
The OTA is now complete.

_`Managing esptool on virtual environment`
==========================================

Expand Down
32 changes: 9 additions & 23 deletions Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -649,12 +649,20 @@ The MCP2515 interrupt (INT) pin is connected to the pin 22 of the
ESP32-Devkit.

mcuboot_nsh
--------------------
-----------

This configuration is the same as the ``nsh`` configuration, but it generates the application
image in a format that can be used by MCUboot. It also makes the ``make bootloader`` command to
build the MCUboot bootloader image using the Espressif HAL.

mcuboot_update_agent
--------------------

This configuration is used to represent an MCUboot image that contains an update agent
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.

Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update ESP32>` section to execute OTA update.

mcuboot_slot_confirm
--------------------

Expand All @@ -666,28 +674,6 @@ after flashing. The image can be confirmed by using the following command::

For more information, check `this demo <https://www.youtube.com/watch?v=Vzy0rl-ixbc>`_.

mcuboot_update_agent
--------------------

This configuration is used to represent an MCUboot image that contains an update agent
to perform OTA updates. First, you will have to setup a HTTP server to provide the update
image. To do that, we can run a simple Python server on the same folder that contains our
binary file on the computer::

sudo python -m http.server 8080

After this, we can use NSH to connect to our network and use the agent to perform the firmware
update::

nsh> ifup wlan0
nsh> wapi mode wlan0 2
nsh> wapi psk wlan0 mypasswd 3
nsh> wapi essid wlan0 myssid 1
nsh> renew wlan0
nsh> mcuboot_agent http://<SERVER_IP>:8080/nuttx.bin

For more information, check `this demo <https://www.youtube.com/watch?v=Vzy0rl-ixbc>`_.

modbus
------

Expand Down
Loading
Loading