michaelh/zephyr
1
0
Fork 0
Code Releases Activity

usb: dfu: update sample README

Browse source 
Some information in the USB DFU sample was out of date.

Also added some example lines for the Permanent download and automatic
reboot features.

Signed-off-by: Martijn Stommels <martijn@martijnpc.nl>
This commit is contained in:
Martijn Stommels 2022-02-23 18:52:21 +01:00 • committed by Carles Cufí
commit 0b1f97031a
1 changed files with 78 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

113
samples/subsys/usb/dfu/README.rst
View file

@ -32,20 +32,14 @@ for more details) and flashed with regular flash tools, but will need
to be loaded at the offset of SLOT-0.
Application images (such as this sample) must be signed.
Use the ``scripts/imgtool.py`` script from the `MCUboot GitHub repo`_
to sign the image. (See the `Using MCUboot with Zephyr`_ documentation for
details.)
The build system can do this for you by setting the :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE` symbol.
For example:
.. code-block:: console
~/src/mcuboot/scripts/imgtool.py sign \
--key ~/src/mcuboot/root-rsa-2048.pem \
--header-size 0x200 \
--align 8 \
--version 1.2 \
--slot-size 0x60000 \
./zephyr/zephyr.bin \
signed-zephyr.bin
west build -b nrf52840dk_nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"
Build and flash MCUboot bootloader for Zephyr project as it is described in
the `Using MCUboot with Zephyr`_ documentation. Then build, sign and flash
@ -53,13 +47,13 @@ the USB DFU sample at the offset of SLOT-0.
Build and sign a second application image e.g. :ref:`hello_world`,
which will be used as an image for the update.
Do not forget to enable the required MCUboot Kconfig option (as described
in :ref:`mcuboot`) by adding the following line to
:zephyr_file:`samples/hello_world/prj.conf`:
Do not forget to enable the required :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` option (as described
in :ref:`mcuboot`). For example:
.. code-block:: console
CONFIG_BOOTLOADER_MCUBOOT=y
west build -b nrf52840dk_nrf52840 zephyr/samples/hello_world -d build-hello_world -- \
-DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"'
Testing
=======
@ -77,37 +71,86 @@ Use the following command to update the application:
.. code-block:: console
dfu-util --alt 1 --download signed-hello.bin
dfu-util --alt 1 --download build-hello_world/zephyr/zephyr.signed.bin
Reset the SoC. MCUboot boot will swap the images and boot the new application,
showing this output to the console:
.. code-block:: console
***** Booting Zephyr OS v1.1.0-65-g4ec7f76 *****
[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=unset, copy_done=0xff, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0xe, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Boot source: slot 0
[MCUBOOT] [INF] boot_swap_type: Swap type: test
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x20000
[MCUBOOT] [INF] main: Jumping to the first image slot0
***** Booting Zephyr OS v1.11.0-830-g9df01813c4 *****
Hello World! arm
*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x3, copy_done=0x1, image_ok=0x1
I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Swap type: test
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
Hello World! nrf52840dk_nrf52840
Reset the SoC again and MCUboot should revert the images and boot
USB DFU sample, showing this output to the console:
.. code-block:: console
***** Booting Zephyr OS v1.1.0-65-g4ec7f76 *****
[MCUBOOT] [INF] main: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=good, copy_done=0x1, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0xe, image_ok=0xff
[MCUBOOT] [INF] boot_status_source: Boot source: none
[MCUBOOT] [INF] boot_swap_type: Swap type: revert
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x20000
***** Booting Zephyr OS v1.11.0-830-g9df01813c4 *****
*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Boot source: none
I: Swap type: revert
I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
[00:00:00.005,920] <inf> main: This device supports USB DFU class.
.. _MCUboot GitHub repo: https://github.com/runtimeco/mcuboot
Permanent download and automatic reboot
=======================================
There are some symbols that can be used to enable a hands free download:
To mark SLOT-1 as permanent after the download completes,
enable the :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` symbol.
To automatically reboot after the download completes,
enable the :kconfig:option:`CONFIG_USB_DFU_REBOOT` symbol.
.. warning::
Enabling :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` can lead to a bricked device!
Make sure there is another way to download firmware.
For example via a debugger or Mcuboot's recovery mode.
Both symbols can be enabled with the :file:`overlay-permanent-download.conf` overlay. For example:
.. code-block:: console
west build -b nrf52840dk_nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
-DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"' \
-DOVERLAY_CONFIG=overlay-permanent-download.conf
The listing below shows the output to the console when downloading via dfu-util.
Note the ``Swap type: perm``.
.. code-block:: console
*** Booting Zephyr OS build zephyr-v3.0.0-361-ge6900e2451d5 ***
[00:00:00.005,920] <inf> main: This device supports USB DFU class.
*** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
I: Starting bootloader
I: Primary image: magic=good, swap_type=0x4, copy_done=0x1, image_ok=0x1
I: Secondary image: magic=good, swap_type=0x3, copy_done=0x3, image_ok=0x1
I: Boot source: none
I: Swap type: perm
I: Bootloader chainload address offset: 0xc000
I: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
Hello World! nrf52840dk_nrf52840
.. _MCUboot GitHub repo: https://github.com/zephyrproject-rtos/mcuboot
.. _Using MCUboot with Zephyr: https://mcuboot.com/documentation/readme-zephyr/