You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2025/07/22 13:55:18 UTC
(nuttx) 05/05: documentation: update documentation for MCUBoot on Espressif devices
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit bbdb75b1f7cfb9aadf99204ab9636b6eaac6de66
Author: Filipe Cavalcanti <fi...@espressif.com>
AuthorDate: Tue Jul 15 11:46:53 2025 -0300
documentation: update documentation for MCUBoot on Espressif devices
Updates MCUBoot documentation and usage example.
Signed-off-by: Filipe Cavalcanti <fi...@espressif.com>
---
.../esp32c3/boards/esp32c3-generic/index.rst | 15 ++++
Documentation/platforms/risc-v/esp32c3/index.rst | 99 ++++++++++++++++++++--
.../esp32c6/boards/esp32c6-devkitc/index.rst | 10 ++-
Documentation/platforms/risc-v/esp32c6/index.rst | 89 +++++++++++++++++++
.../xtensa/esp32/boards/esp32-devkitc/index.rst | 32 ++-----
Documentation/platforms/xtensa/esp32/index.rst | 99 ++++++++++++++++++++--
.../esp32s2/boards/esp32s2-saola-1/index.rst | 8 ++
Documentation/platforms/xtensa/esp32s2/index.rst | 99 ++++++++++++++++++++--
.../xtensa/esp32s3/boards/esp32s3-devkit/index.rst | 8 ++
Documentation/platforms/xtensa/esp32s3/index.rst | 91 +++++++++++++++++++-
10 files changed, 510 insertions(+), 40 deletions(-)
diff --git a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst
index cf6b3fa29c..bc10b6112e 100644
--- a/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst
+++ b/Documentation/platforms/risc-v/esp32c3/boards/esp32c3-generic/index.rst
@@ -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
------
diff --git a/Documentation/platforms/risc-v/esp32c3/index.rst b/Documentation/platforms/risc-v/esp32c3/index.rst
index 208996149a..9f25e4049b 100644
--- a/Documentation/platforms/risc-v/esp32c3/index.rst
+++ b/Documentation/platforms/risc-v/esp32c3/index.rst
@@ -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
@@ -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
@@ -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)::
@@ -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:
diff --git a/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst b/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst
index 26f99b53c9..4d458ccf69 100644
--- a/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst
+++ b/Documentation/platforms/risc-v/esp32c6/boards/esp32c6-devkitc/index.rst
@@ -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
---
diff --git a/Documentation/platforms/risc-v/esp32c6/index.rst b/Documentation/platforms/risc-v/esp32c6/index.rst
index 092ed3da25..036a4ec56f 100644
--- a/Documentation/platforms/risc-v/esp32c6/index.rst
+++ b/Documentation/platforms/risc-v/esp32c6/index.rst
@@ -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`
==========================================
diff --git a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
index d8515fd123..6aa571a457 100644
--- a/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
+++ b/Documentation/platforms/xtensa/esp32/boards/esp32-devkitc/index.rst
@@ -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
--------------------
@@ -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
------
diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst
index 6a1e8c9aff..656dc2cfd5 100644
--- a/Documentation/platforms/xtensa/esp32/index.rst
+++ b/Documentation/platforms/xtensa/esp32/index.rst
@@ -752,11 +752,100 @@ Networking is possible using the openeth MAC driver. Enable ``ESP32_OPENETH`` op
$ qemu-system-xtensa -nographic -machine esp32 -drive file=nuttx.merged.bin,if=mtd,format=raw -nic user,model=open_eth
+.. _MCUBoot and OTA Update ESP32:
+
+MCUBoot and OTA Update
+======================
+
+The ESP32 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 esp32-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.
+
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, these pieces of software include
@@ -784,7 +873,7 @@ The Secure Boot process on the ESP32 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'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
@@ -796,7 +885,7 @@ of flash will not be sufficient to recover most flash contents.
`here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html>`__.
Prerequisites
--------------
+^^^^^^^^^^^^^
First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary
images) and ``esptool`` (the ESP32 toolkit)::
@@ -820,7 +909,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:
diff --git a/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst b/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst
index 15d6679c86..2901da7ee6 100644
--- a/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst
+++ b/Documentation/platforms/xtensa/esp32s2/boards/esp32s2-saola-1/index.rst
@@ -334,6 +334,14 @@ This configuration is the same as the ``nsh`` configuration, but it generates th
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 S2>` section to execute OTA update.
+
nsh
---
diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst
index 82b68012ce..f0394902fa 100644
--- a/Documentation/platforms/xtensa/esp32s2/index.rst
+++ b/Documentation/platforms/xtensa/esp32s2/index.rst
@@ -625,11 +625,100 @@ using WPA2.
The ``dhcpd_start`` is necessary to let your board to associate an IP to your smartphone.
+.. _MCUBoot and OTA Update S2:
+
+MCUBoot and OTA Update
+======================
+
+The ESP32-S2 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 esp32s2-saola-1: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-S2, these pieces of software include
@@ -657,7 +746,7 @@ The Secure Boot process on the ESP32-S2 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-S2'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
@@ -669,7 +758,7 @@ of flash will not be sufficient to recover most flash contents.
`here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/flash-encryption.html>`__.
Prerequisites
--------------
+^^^^^^^^^^^^^
First of all, we need to install ``imgtool`` (a MCUboot utility application to manipulate binary
images) and ``esptool`` (the ESP32-S2 toolkit)::
@@ -693,7 +782,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:
diff --git a/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst b/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
index d84861996e..48b49e9561 100644
--- a/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
+++ b/Documentation/platforms/xtensa/esp32s3/boards/esp32s3-devkit/index.rst
@@ -411,6 +411,14 @@ This configuration is the same as the ``nsh`` configuration, but it generates th
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 S3>` section to execute OTA update.
+
nsh
---
diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst
index 085d489919..8b414f1de2 100644
--- a/Documentation/platforms/xtensa/esp32s3/index.rst
+++ b/Documentation/platforms/xtensa/esp32s3/index.rst
@@ -476,8 +476,97 @@ Then, it can be customized in the menu :menuselection:`System Type --> ADC Confi
.. warning:: Minimum and maximum measurable voltages may saturate around 100 mV and 3000 mV, respectively.
+.. _MCUBoot and OTA Update S3:
+
+MCUBoot and OTA Update
+======================
+
+The ESP32-S3 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 esp32s3-devkit: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.
+
Wi-Fi
------
+=====
.. tip:: Boards usually expose a ``wifi`` defconfig which enables Wi-Fi. On ESP32-S3,
SMP is enabled to enhance Wi-Fi performance.