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. to be loaded at the offset of SLOT-0.
Application images (such as this sample) must be signed. Application images (such as this sample) must be signed.
Use the ``scripts/imgtool.py`` script from the `MCUboot GitHub repo`_ The build system can do this for you by setting the :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE` symbol.
to sign the image. (See the `Using MCUboot with Zephyr`_ documentation for
details.) For example:
.. code-block:: console .. code-block:: console
~/src/mcuboot/scripts/imgtool.py sign \ west build -b nrf52840dk_nrf52840 zephyr/samples/subsys/usb/dfu -d build-dfu -- \
--key ~/src/mcuboot/root-rsa-2048.pem \ -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"
--header-size 0x200 \
--align 8 \
--version 1.2 \
--slot-size 0x60000 \
./zephyr/zephyr.bin \
signed-zephyr.bin
Build and flash MCUboot bootloader for Zephyr project as it is described in Build and flash MCUboot bootloader for Zephyr project as it is described in
the `Using MCUboot with Zephyr`_ documentation. Then build, sign and flash 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`, Build and sign a second application image e.g. :ref:`hello_world`,
which will be used as an image for the update. which will be used as an image for the update.
Do not forget to enable the required MCUboot Kconfig option (as described Do not forget to enable the required :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` option (as described
in :ref:`mcuboot`) by adding the following line to in :ref:`mcuboot`). For example:
:zephyr_file:`samples/hello_world/prj.conf`:
.. code-block:: console .. 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 Testing
======= =======
@ -77,37 +71,86 @@ Use the following command to update the application:
.. code-block:: console .. 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, Reset the SoC. MCUboot boot will swap the images and boot the new application,
showing this output to the console: showing this output to the console:
.. code-block:: console .. code-block:: console
***** Booting Zephyr OS v1.1.0-65-g4ec7f76 ***** *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
[MCUBOOT] [INF] main: Starting bootloader I: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=unset, copy_done=0xff, image_ok=0xff I: Primary image: magic=good, swap_type=0x3, copy_done=0x1, image_ok=0x1
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0xe, image_ok=0xff I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
[MCUBOOT] [INF] boot_status_source: Boot source: slot 0 I: Boot source: none
[MCUBOOT] [INF] boot_swap_type: Swap type: test I: Swap type: test
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x20000 I: Bootloader chainload address offset: 0xc000
[MCUBOOT] [INF] main: Jumping to the first image slot0 I: Jumping to the first image slot
***** Booting Zephyr OS v1.11.0-830-g9df01813c4 ***** *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
Hello World! arm Hello World! nrf52840dk_nrf52840
Reset the SoC again and MCUboot should revert the images and boot Reset the SoC again and MCUboot should revert the images and boot
USB DFU sample, showing this output to the console: USB DFU sample, showing this output to the console:
.. code-block:: console .. code-block:: console
***** Booting Zephyr OS v1.1.0-65-g4ec7f76 ***** *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
[MCUBOOT] [INF] main: Starting bootloader I: Starting bootloader
[MCUBOOT] [INF] boot_status_source: Image 0: magic=good, copy_done=0x1, image_ok=0xff I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
[MCUBOOT] [INF] boot_status_source: Scratch: magic=unset, copy_done=0xe, image_ok=0xff I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[MCUBOOT] [INF] boot_status_source: Boot source: none I: Boot source: none
[MCUBOOT] [INF] boot_swap_type: Swap type: revert I: Swap type: revert
[MCUBOOT] [INF] main: Bootloader chainload address offset: 0x20000 I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
***** Booting Zephyr OS v1.11.0-830-g9df01813c4 ***** 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/ .. _Using MCUboot with Zephyr: https://mcuboot.com/documentation/readme-zephyr/