Skip to content

Commit bbdb75b

Browse files
fdcavalcantiAlan C. Assis
fdcavalcanti
authored and
Alan C. Assis
committed
documentation: update documentation for MCUBoot on Espressif devices
Updates MCUBoot documentation and usage example. Signed-off-by: Filipe Cavalcanti <filipe.cavalcanti@espressif.com>
1 parent 3468c8e commit bbdb75b

File tree

10 files changed

+510
-40
lines changed

10 files changed

+510
-40
lines changed

‎Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,21 @@ After successfully built and flashed, run on the boards's terminal::
322322

323323
nsh> i2schar
324324

325+
mcuboot_nsh
326+
-----------
327+
328+
This configuration is the same as the ``nsh`` configuration, but it generates the application
329+
image in a format that can be used by MCUboot. It also makes the ``make bootloader`` command to
330+
build the MCUboot bootloader image using the Espressif HAL.
331+
332+
mcuboot_update_agent
333+
--------------------
334+
335+
This configuration is used to represent an MCUboot image that contains an update agent
336+
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.
337+
338+
Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update C3>` section to execute OTA update.
339+
325340
nimble
326341
------
327342

‎Documentation/platforms/risc-v/esp32c3/index.rst‎

Lines changed: 94 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -408,11 +408,100 @@ Then, it can be customized in the menu :menuselection:`System Type --> ADC Confi
408408

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

411+
.. _MCUBoot and OTA Update C3:
412+
413+
MCUBoot and OTA Update
414+
======================
415+
416+
The ESP32-C3 supports over-the-air (OTA) updates using MCUBoot.
417+
418+
Read more about the MCUBoot for Espressif devices `here <https://docs.mcuboot.com/readme-espressif.html>`__.
419+
420+
Executing OTA Update
421+
--------------------
422+
423+
This section describes how to execute OTA update using MCUBoot.
424+
425+
1. First build the default ``mcuboot_update_agent`` config. This image defaults to the primary slot and already comes with Wi-Fi settings enabled::
426+
427+
./tools/configure.sh esp32c3-generic:mcuboot_update_agent
428+
429+
2. Build the MCUBoot bootloader::
430+
431+
make bootloader
432+
433+
3. Finally, build the application image::
434+
435+
make
436+
437+
Flash the image to the board and verify it boots ok.
438+
It should show the message "This is MCUBoot Update Agent image" before NuttShell is ready.
439+
440+
At this point, the board should be able to connect to Wi-Fi so we can download a new binary from our network::
441+
442+
NuttShell (NSH) NuttX-12.4.0
443+
This is MCUBoot Update Agent image
444+
nsh>
445+
nsh> wapi psk wlan0 <wifi_ssid> 3
446+
nsh> wapi essid wlan0 <wifi_password> 1
447+
nsh> renew wlan0
448+
449+
Now, keep the board as is and execute the following commands to **change the MCUBoot target slot to the 2nd slot**
450+
and modify the message of the day (MOTD) as a mean to verify the new image is being used.
451+
452+
1. Change the MCUBoot target slot to the 2nd slot::
453+
454+
kconfig-tweak -d CONFIG_ESPRESSIF_ESPTOOL_TARGET_PRIMARY
455+
kconfig-tweak -e CONFIG_ESPRESSIF_ESPTOOL_TARGET_SECONDARY
456+
kconfig-tweak --set-str CONFIG_NSH_MOTD_STRING "This is MCUBoot UPDATED image!"
457+
make olddefconfig
458+
459+
.. note::
460+
The same changes can be accomplished through ``menuconfig`` in :menuselection:`System Type --> Bootloader and Image Configuration --> Target slot for image flashing`
461+
for MCUBoot target slot and in :menuselection:`System Type --> Bootloader and Image Configuration --> Search (motd) --> NSH Library --> Message of the Day` for the MOTD.
462+
463+
2. Rebuild the application image::
464+
465+
make
466+
467+
At this point the board is already connected to Wi-Fi and has the primary image flashed.
468+
The new image configured for the 2nd slot is ready to be downloaded.
469+
470+
To execute OTA, create a simple HTTP server on the NuttX directory so we can access the binary remotely::
471+
472+
cd nuttxspace/nuttx
473+
python3 -m http.server
474+
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
475+
476+
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::
477+
478+
nsh> mcuboot_agent http://10.42.0.1:8000/nuttx.bin
479+
MCUboot Update Agent example
480+
Downloading from http://10.42.0.1:8000/nuttx.bin
481+
Firmware Update size: 1048576 bytes
482+
Received: 512 of 1048576 bytes [0%]
483+
Received: 1024 of 1048576 bytes [0%]
484+
Received: 1536 of 1048576 bytes [0%]
485+
[.....]
486+
Received: 1048576 of 1048576 bytes [100%]
487+
Application Image successfully downloaded!
488+
Requested update for next boot. Restarting...
489+
490+
NuttShell should now show the new MOTD, meaning the new image is being used::
491+
492+
NuttShell (NSH) NuttX-12.4.0
493+
This is MCUBoot UPDATED image!
494+
nsh>
495+
496+
Finally, the image is loaded but not confirmed.
497+
To make sure it won't rollback to the previous image, you must confirm with ``mcuboot_confirm`` and reboot the board.
498+
The OTA is now complete.
499+
411500
Secure Boot and Flash Encryption
412-
================================
501+
--------------------------------
413502

414503
Secure Boot
415-
-----------
504+
^^^^^^^^^^^
416505

417506
Secure Boot protects a device from running any unauthorized (i.e., unsigned) code by checking that
418507
each piece of software that is being booted is signed. On an ESP32-C3, these pieces of software include
@@ -440,7 +529,7 @@ The Secure Boot process on the ESP32-C3 involves the following steps performed:
440529
by MCUboot rather than the original NuttX port.
441530

442531
Flash Encryption
443-
----------------
532+
^^^^^^^^^^^^^^^^
444533

445534
Flash encryption is intended for encrypting the contents of the ESP32-C3's off-chip flash memory. Once this feature is enabled,
446535
firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout
@@ -452,7 +541,7 @@ of flash will not be sufficient to recover most flash contents.
452541
`here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html>`__.
453542

454543
Prerequisites
455-
-------------
544+
^^^^^^^^^^^^^
456545

457546
First of all, we need to install ``imgtool`` (the MCUboot utility application to manipulate binary
458547
images)::
@@ -476,7 +565,7 @@ respectively, of the compiled project::
476565
.. important:: The contents of the key files must be stored securely and kept secret.
477566

478567
Enabling Secure Boot and Flash Encryption
479-
-----------------------------------------
568+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
480569

481570
To enable Secure Boot for the current project, go to the project's NuttX directory, execute ``make menuconfig`` and the following steps:
482571

‎Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -323,12 +323,20 @@ There is also support for an optional fault GPIO (defaults to GPIO9), which can
323323
for quick motor braking. All GPIOs are configurable in ``menuconfig``.
324324

325325
mcuboot_nsh
326-
--------------------
326+
-----------
327327

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

332+
mcuboot_update_agent
333+
--------------------
334+
335+
This configuration is used to represent an MCUboot image that contains an update agent
336+
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.
337+
338+
Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update C6>` section to execute OTA update.
339+
332340
nsh
333341
---
334342

‎Documentation/platforms/risc-v/esp32c6/index.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,95 @@ Then, it can be customized in the menu :menuselection:`System Type --> ADC Confi
397397
6 6
398398
========== ===========
399399

400+
.. _MCUBoot and OTA Update C6:
401+
402+
MCUBoot and OTA Update
403+
======================
404+
405+
The ESP32-C6 supports over-the-air (OTA) updates using MCUBoot.
406+
407+
Read more about the MCUBoot for Espressif devices `here <https://docs.mcuboot.com/readme-espressif.html>`__.
408+
409+
Executing OTA Update
410+
--------------------
411+
412+
This section describes how to execute OTA update using MCUBoot.
413+
414+
1. First build the default ``mcuboot_update_agent`` config. This image defaults to the primary slot and already comes with Wi-Fi settings enabled::
415+
416+
./tools/configure.sh esp32c6-devkitc:mcuboot_update_agent
417+
418+
2. Build the MCUBoot bootloader::
419+
420+
make bootloader
421+
422+
3. Finally, build the application image::
423+
424+
make
425+
426+
Flash the image to the board and verify it boots ok.
427+
It should show the message "This is MCUBoot Update Agent image" before NuttShell is ready.
428+
429+
At this point, the board should be able to connect to Wi-Fi so we can download a new binary from our network::
430+
431+
NuttShell (NSH) NuttX-12.4.0
432+
This is MCUBoot Update Agent image
433+
nsh>
434+
nsh> wapi psk wlan0 <wifi_ssid> 3
435+
nsh> wapi essid wlan0 <wifi_password> 1
436+
nsh> renew wlan0
437+
438+
Now, keep the board as is and execute the following commands to **change the MCUBoot target slot to the 2nd slot**
439+
and modify the message of the day (MOTD) as a mean to verify the new image is being used.
440+
441+
1. Change the MCUBoot target slot to the 2nd slot::
442+
443+
kconfig-tweak -d CONFIG_ESPRESSIF_ESPTOOL_TARGET_PRIMARY
444+
kconfig-tweak -e CONFIG_ESPRESSIF_ESPTOOL_TARGET_SECONDARY
445+
kconfig-tweak --set-str CONFIG_NSH_MOTD_STRING "This is MCUBoot UPDATED image!"
446+
make olddefconfig
447+
448+
.. note::
449+
The same changes can be accomplished through ``menuconfig`` in :menuselection:`System Type --> Bootloader and Image Configuration --> Target slot for image flashing`
450+
for MCUBoot target slot and in :menuselection:`System Type --> Bootloader and Image Configuration --> Search (motd) --> NSH Library --> Message of the Day` for the MOTD.
451+
452+
2. Rebuild the application image::
453+
454+
make
455+
456+
At this point the board is already connected to Wi-Fi and has the primary image flashed.
457+
The new image configured for the 2nd slot is ready to be downloaded.
458+
459+
To execute OTA, create a simple HTTP server on the NuttX directory so we can access the binary remotely::
460+
461+
cd nuttxspace/nuttx
462+
python3 -m http.server
463+
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
464+
465+
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::
466+
467+
nsh> mcuboot_agent http://10.42.0.1:8000/nuttx.bin
468+
MCUboot Update Agent example
469+
Downloading from http://10.42.0.1:8000/nuttx.bin
470+
Firmware Update size: 1048576 bytes
471+
Received: 512 of 1048576 bytes [0%]
472+
Received: 1024 of 1048576 bytes [0%]
473+
Received: 1536 of 1048576 bytes [0%]
474+
[.....]
475+
Received: 1048576 of 1048576 bytes [100%]
476+
Application Image successfully downloaded!
477+
Requested update for next boot. Restarting...
478+
479+
NuttShell should now show the new MOTD, meaning the new image is being used::
480+
481+
NuttShell (NSH) NuttX-12.4.0
482+
This is MCUBoot UPDATED image!
483+
nsh>
484+
485+
Finally, the image is loaded but not confirmed.
486+
To make sure it won't rollback to the previous image, you must confirm with ``mcuboot_confirm`` and reboot the board.
487+
The OTA is now complete.
488+
400489
_`Managing esptool on virtual environment`
401490
==========================================
402491

‎Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -649,12 +649,20 @@ The MCP2515 interrupt (INT) pin is connected to the pin 22 of the
649649
ESP32-Devkit.
650650

651651
mcuboot_nsh
652-
--------------------
652+
-----------
653653

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

658+
mcuboot_update_agent
659+
--------------------
660+
661+
This configuration is used to represent an MCUboot image that contains an update agent
662+
to perform over-the-air (OTA) updates. Wi-Fi settings are already enabled and image confirmation program is included.
663+
664+
Follow the instructions in the :ref:`MCUBoot and OTA Update <MCUBoot and OTA Update ESP32>` section to execute OTA update.
665+
658666
mcuboot_slot_confirm
659667
--------------------
660668

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

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

669-
mcuboot_update_agent
670-
--------------------
671-
672-
This configuration is used to represent an MCUboot image that contains an update agent
673-
to perform OTA updates. First, you will have to setup a HTTP server to provide the update
674-
image. To do that, we can run a simple Python server on the same folder that contains our
675-
binary file on the computer::
676-
677-
sudo python -m http.server 8080
678-
679-
After this, we can use NSH to connect to our network and use the agent to perform the firmware
680-
update::
681-
682-
nsh> ifup wlan0
683-
nsh> wapi mode wlan0 2
684-
nsh> wapi psk wlan0 mypasswd 3
685-
nsh> wapi essid wlan0 myssid 1
686-
nsh> renew wlan0
687-
nsh> mcuboot_agent http://<SERVER_IP>:8080/nuttx.bin
688-
689-
For more information, check `this demo <https://www.youtube.com/watch?v=Vzy0rl-ixbc>`_.
690-
691677
modbus
692678
------
693679

0 commit comments

Comments
 (0)