diff --git a/samples/subsys/usb/dfu/README.rst b/samples/subsys/usb/dfu/README.rst index 6ac797977a5..dccb53db10f 100644 --- a/samples/subsys/usb/dfu/README.rst +++ b/samples/subsys/usb/dfu/README.rst @@ -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] 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] 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/