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 cf6b3fa29c7..bc10b6112e8 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 ` 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 208996149a7..9f25e4049b3 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 `__. + +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 3 + nsh> wapi essid wlan0 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 `__. 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 26f99b53c98..4d458ccf69f 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 ` 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 092ed3da257..036a4ec56f2 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 `__. + +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 3 + nsh> wapi essid wlan0 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 d8515fd1235..6aa571a4575 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 ` 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 `_. -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://:8080/nuttx.bin - -For more information, check `this demo `_. - modbus ------ diff --git a/Documentation/platforms/xtensa/esp32/index.rst b/Documentation/platforms/xtensa/esp32/index.rst index 6a1e8c9aff1..656dc2cfd59 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 `__. + +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 3 + nsh> wapi essid wlan0 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 `__. 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 15d6679c86a..2901da7ee69 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 ` section to execute OTA update. + nsh --- diff --git a/Documentation/platforms/xtensa/esp32s2/index.rst b/Documentation/platforms/xtensa/esp32s2/index.rst index 82b68012cef..f0394902fa2 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 `__. + +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 3 + nsh> wapi essid wlan0 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 `__. 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 d84861996e9..48b49e9561f 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 ` section to execute OTA update. + nsh --- diff --git a/Documentation/platforms/xtensa/esp32s3/index.rst b/Documentation/platforms/xtensa/esp32s3/index.rst index 085d489919a..8b414f1de27 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 `__. + +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 3 + nsh> wapi essid wlan0 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.