README.rst
1.. zephyr:code-sample:: legacy-usb-dfu
2 :name: Legacy USB DFU (Device Firmware Upgrade)
3 :relevant-api: _usb_device_core_api
4
5 Implement device firmware upgrade using the USB DFU class driver.
6
7Overview
8********
9
10This sample app demonstrates use of a USB DFU Class driver provided
11by the Zephyr project.
12
13.. note::
14 This samples demonstrate deprecated :ref:`usb_device_stack`.
15
16Requirements
17************
18
19This project requires an USB device driver. Currently, the USB DFU
20class provided by the Zephyr project depends on DFU image manager and
21partition layout. Refer to :ref:`flash_map_api` for details about
22partition layout. You SoC must run MCUboot as the stage 1 bootloader.
23This sample is built as an application for the MCUboot bootloader.
24
25.. note::
26 This example explicitly turns :kconfig:option:`CONFIG_USB_DFU_ENABLE_UPLOAD` on.
27
28Building and Testing
29********************
30
31Building and signing the application
32====================================
33
34This sample can be built in the usual way (see :ref:`build_an_application`
35for more details) and flashed with regular flash tools, but will need
36to be loaded at the offset of SLOT-0.
37
38Application images (such as this sample) must be signed.
39The build system can do this for you by setting the :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE` symbol.
40
41For example:
42
43.. code-block:: console
44
45 west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/legacy/dfu -d build-dfu -- \
46 -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"
47
48Build and flash MCUboot bootloader for Zephyr project as it is described in
49the `Using MCUboot with Zephyr`_ documentation. Then build, sign and flash
50the USB DFU sample at the offset of SLOT-0.
51
52Build and sign a second application image e.g. :zephyr:code-sample:`hello_world`,
53which will be used as an image for the update.
54Do not forget to enable the required :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT` option (as described
55in :ref:`mcuboot`). For example:
56
57.. code-block:: console
58
59 west build -b nrf52840dk/nrf52840 zephyr/samples/hello_world -d build-hello_world -- \
60 -DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"'
61
62Testing
63=======
64
65The Linux ``dfu-util`` tool can be used to backup or update the application
66image.
67
68Use the following command to backup the SLOT-0 image:
69
70.. code-block:: console
71
72 dfu-util --alt 0 --upload slot0_backup.bin
73
74Use the following command to update the application:
75
76.. code-block:: console
77
78 dfu-util --alt 1 --download build-hello_world/zephyr/zephyr.signed.bin
79
80Reset the SoC. MCUboot boot will swap the images and boot the new application,
81showing this output to the console:
82
83.. code-block:: console
84
85 *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
86 I: Starting bootloader
87 I: Primary image: magic=good, swap_type=0x3, copy_done=0x1, image_ok=0x1
88 I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
89 I: Boot source: none
90 I: Swap type: test
91 I: Bootloader chainload address offset: 0xc000
92 I: Jumping to the first image slot
93 *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
94 Hello World! nrf52840dk
95
96
97Reset the SoC again and MCUboot should revert the images and boot
98USB DFU sample, showing this output to the console:
99
100.. code-block:: console
101
102 *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
103 I: Starting bootloader
104 I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
105 I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
106 I: Boot source: none
107 I: Swap type: revert
108 I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
109 I: Bootloader chainload address offset: 0xc000
110 I: Jumping to the first image slot
111 *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
112 [00:00:00.005,920] <inf> main: This device supports USB DFU class.
113
114Permanent download and automatic reboot
115=======================================
116
117There are some symbols that can be used to enable a hands free download:
118
119To mark SLOT-1 as permanent after the download completes,
120enable the :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` symbol.
121
122To automatically reboot after the download completes,
123enable the :kconfig:option:`CONFIG_USB_DFU_REBOOT` symbol.
124
125.. warning::
126 Enabling :kconfig:option:`CONFIG_USB_DFU_PERMANENT_DOWNLOAD` can lead to a bricked device!
127 Make sure there is another way to download firmware.
128 For example via a debugger or Mcuboot's recovery mode.
129
130Both symbols can be enabled with the :file:`overlay-permanent-download.conf` overlay. For example:
131
132.. code-block:: console
133
134 west build -b nrf52840dk/nrf52840 zephyr/samples/subsys/usb/legacy/dfu -d build-dfu -- \
135 -DCONFIG_BOOTLOADER_MCUBOOT=y '-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE="bootloader/mcuboot/root-rsa-2048.pem"' \
136 -DEXTRA_CONF_FILE=overlay-permanent-download.conf
137
138
139The listing below shows the output to the console when downloading via dfu-util.
140Note the ``Swap type: perm``.
141
142.. code-block:: console
143
144 *** Booting Zephyr OS build zephyr-v3.0.0-361-ge6900e2451d5 ***
145 [00:00:00.005,920] <inf> main: This device supports USB DFU class.
146
147 *** Booting Zephyr OS build zephyr-v3.0.0-360-gc0dd594d4d3d ***
148 I: Starting bootloader
149 I: Primary image: magic=good, swap_type=0x4, copy_done=0x1, image_ok=0x1
150 I: Secondary image: magic=good, swap_type=0x3, copy_done=0x3, image_ok=0x1
151 I: Boot source: none
152 I: Swap type: perm
153 I: Bootloader chainload address offset: 0xc000
154 I: Jumping to the first image slot
155 *** Booting Zephyr OS build zephyr-v3.0.0-361-gb987e6daa2f9 ***
156 Hello World! nrf52840dk
157
158
159.. _MCUboot GitHub repo: https://github.com/zephyrproject-rtos/mcuboot
160.. _Using MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr
161