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