mirror of
https://github.com/apache/nuttx.git
synced 2026-08-19 20:48:19 +00:00
a754b73e4c
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 <filipe.cavalcanti@espressif.com>
237 lines
7.4 KiB
ReStructuredText
237 lines
7.4 KiB
ReStructuredText
============================
|
|
``mcuboot`` MCUboot examples
|
|
============================
|
|
|
|
``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
|
|
valid images.
|
|
|
|
This application add 3 Builtin Apps to NuttX NSH: version, set_img and confirm.
|
|
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.
|
|
|
|
After that, clean up environment and set ``mcuboot-swap-test`` as target. The
|
|
build output will generate the ``nuttx.bin`` file. You should execute the MCUboot
|
|
script called ``imgtool.py`` and sign the binary file two times.
|
|
|
|
The first time you will use ``--version 1.0.0`` and ``signedv1.bin`` as output file.
|
|
Then, the second sign you need change to ``--version 2.0.0`` and ``signedv2.bin``
|
|
as output file.
|
|
|
|
The ``signedv1.bin`` file must be at MCUboot Slot-0 partition and ``signedv2.bin``
|
|
at Slot-1.
|
|
|
|
More instructions about how to sign and flash can be found at board documentation
|
|
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 ``?``::
|
|
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> ?
|
|
help usage: help [-v] [<cmd>]
|
|
|
|
. cd echo hexdump mv rmdir true xd
|
|
[ cp exec kill printf set truncate
|
|
? cmp exit ls ps sleep uname
|
|
basename dirname false mkdir pwd source umount
|
|
break dd free mkrd reboot test unset
|
|
cat df help mount rm time usleep
|
|
|
|
Builtin Apps:
|
|
mcuboot_set_img mcuboot_confirm sh
|
|
mcuboot_version ramtest nsh
|
|
nsh>
|
|
|
|
First step (check version)::
|
|
|
|
nsh> mcuboot_version
|
|
Image version 1.0.0.0
|
|
nsh>
|
|
|
|
Second step (mark image as good because it is running). This is an optional
|
|
step that must be executed if you ran ``imgtool.py`` without optional parameter
|
|
``--confirm``::
|
|
|
|
nsh> mcuboot_confirm
|
|
Application Image successfully confirmed!
|
|
nsh>
|
|
|
|
Third step (let's reboot and see what's happen)::
|
|
|
|
nsh> reboot
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> mcuboot_version
|
|
Image version 1.0.0.0
|
|
nsh>
|
|
|
|
Fourth step (let's switch image)::
|
|
|
|
nsh> mcuboot_set_img
|
|
Requested update for next boot. Restarting...
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> mcuboot_version
|
|
Image version 2.0.0.0
|
|
nsh>
|
|
|
|
Now, we switched from image version 1.0.0 to image 2.0.0. However, we intentionally
|
|
will not run ``mcuboot_confirm`` app::
|
|
|
|
nsh> reboot
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> mcuboot_version
|
|
Image version 1.0.0.0
|
|
nsh>
|
|
|
|
This means that if for any reason App reboot, have a malfunctioning or not boot,
|
|
MCUboot will switch back to old ``good`` image! Remember that we executed
|
|
``mcuboot_confirm`` at step two.
|
|
|
|
Fifth step (switch to image version 2 and mark as permanent)::
|
|
|
|
nsh> mcuboot_set_img
|
|
Requested update for next boot. Restarting...
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> mcuboot_confirm
|
|
Application Image successfully confirmed!
|
|
nsh> mcuboot_version
|
|
Image version 2.0.0.0
|
|
nsh>
|
|
|
|
Sixth step (Reboot and confirm V2 image)::
|
|
|
|
nsh> reboot
|
|
*** Booting MCUboot build 7c890f4b075aed73e4c825ccf875b2fb9ebf2ded ***
|
|
NuttShell (NSH) NuttX-10.2.0
|
|
nsh> mcuboot_version
|
|
Image version 2.0.0.0
|
|
nsh>
|
|
|
|
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>
|