This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new a754b73e4c5 documentation: update MCUBoot docs for local update agent
example
a754b73e4c5 is described below
commit a754b73e4c5faf50b30e9cf84de54d5bb99c3b45
Author: Filipe Cavalcanti <[email protected]>
AuthorDate: Tue Jul 15 14:45:11 2025 -0300
documentation: update MCUBoot docs for local update agent example
Updates the example documentation for a new example: local update agent.
This example allows the user to update MCUBoot image from a locally stored
file.
Signed-off-by: Filipe Cavalcanti <[email protected]>
---
.../applications/examples/mcuboot/index.rst | 114 ++++++++++++++++++++-
1 file changed, 110 insertions(+), 4 deletions(-)
diff --git a/Documentation/applications/examples/mcuboot/index.rst
b/Documentation/applications/examples/mcuboot/index.rst
index f91d26145a6..261db398815 100644
--- a/Documentation/applications/examples/mcuboot/index.rst
+++ b/Documentation/applications/examples/mcuboot/index.rst
@@ -3,10 +3,10 @@
============================
``swap_test``
--------------
+=============
Description
-~~~~~~~~~~~
+-----------
MCUboot Swap Image is an application to demonstrate firmware upgrade using
internal flash memory. It simulate MCUboot API steps to switch between two
@@ -17,7 +17,7 @@ After application is build and ``nuttx.bin`` be generated,
the binary must be
signed. Consult your board documentation page to get instructions how to do it.
How to build and flash
-......................
+----------------------
First step is build your board configuration using ``mcuboot-loader`` as
target.
That create the bootloader itself. The ``nuttx.bin`` must be flash as usual.
@@ -37,7 +37,7 @@ More instructions about how to sign and flash can be found at
board documentatio
page.
Running swap image test
-.......................
+-----------------------
Open you terminal and reboot your board. You can see a similar output as below.
You can check builtin apps using command ``?``::
@@ -129,3 +129,109 @@ Sixth step (Reboot and confirm V2 image)::
Conclusion, once we boot a newer image and confirm it MCUboot always run that
image, unless you instruct it to swap again!
+
+``mcuboot_local_agent``
+=======================
+
+MCUBoot Local Update Agent is an application to demonstrate firmware upgrade
+using a binary file from local storage. Unlike remote update mechanisms, this
+example copies the firmware binary directly from local storage (such as SD
Card,
+USB drive, or any mounted filesystem) to the secondary flash slot for MCUBoot
+to process during the next boot.
+
+This application provides a simple and reliable way to update firmware without
+requiring network connectivity or complex remote update infrastructure.
+
+Features:
+
+* Copy firmware binary from local storage to secondary flash slot
+* Progress indication during firmware copy
+* Automatic size validation (ensures firmware fits in secondary slot)
+* Flash area erasing and writing
+* Automatic boot marking and system restart
+
+Build and flash
+----------------------
+
+First, build your board configuration with MCUBoot, SD Card support and enable
this tool under
+`Application Configuration → Examples → MCUboot Examples → MCUBoot Local
Update Agent`.
+
+Flash the board normally.
+
+Generating the update binary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To create a firmware binary for update:
+
+1. Configure the build to target the secondary slot::
+
+ make menuconfig
+ # Configure MCUBoot to build for secondary slot
+ # (specific configuration varies by architecture)
+
+2. Optionally modify the application (e.g., change MOTD) to visually identify
+ the updated image
+
+3. Build the update binary::
+
+ make
+
+4. The resulting binary should be copied to your local storage device (i.e. SD
Card).
+ Consult your board documentation for the specific binary filename and
+ any required post-processing steps.
+
+Running the local update agent
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Mount your storage device containing the firmware binary::
+
+ nsh> mount -t vfat /dev/mmcsd0 /mnt
+
+2. Verify the firmware file is accessible::
+
+ nsh> ls /mnt
+ /mnt:
+ nuttx.bin
+ readme.txt
+
+3. Run the update agent with the firmware file path::
+
+ nsh> mcuboot_local_agent /mnt/nuttx.bin
+
+ If no path is specified, it defaults to ``/mnt/sdcard/nuttx.bin``
+
+Example output
+~~~~~~~~~~~~~~
+
+When running the update agent, you should see output similar to::
+
+ nsh> mcuboot_local_agent /mnt/nuttx.bin
+ MCUBoot Local Update Agent
+ Firmware file: /mnt/nuttx.bin
+ Firmware file size: 1048576 bytes
+ Erasing secondary flash slot...
+ Copying firmware to secondary slot...
+ Progress: 4096/1048576 bytes [0%]
+ Progress: 8192/1048576 bytes [0%]
+ Progress: 12288/1048576 bytes [1%]
+ ...
+ Progress: 1044480/1048576 bytes [99%]
+ Progress: 1048576/1048576 bytes [100%]
+ Firmware copy completed successfully!
+ Firmware successfully copied to secondary slot!
+ Update scheduled for next boot. Restarting...
+ reboot status=0
+
+After reboot, MCUBoot will detect the new firmware in the secondary slot and
+perform the update. You should see MCUBoot messages indicating the swap
process::
+
+ *** Booting MCUboot build v2.2.0-rc1 ***
+ ...
+ Primary image: magic=good, swap_type=0x1, copy_done=0x3, image_ok=0x1
+ Scratch: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
+ Boot source: primary slot
+ Image index: 0, Swap type: test
+ Starting swap using scratch algorithm.
+ ...
+ This is MCUBoot Updated Image!!
+ nsh>
