README.rst
1.. zephyr:code-sample:: usb-dfu
2 :name: USB DFU
3 :relevant-api: usbd_api usbd_dfu
4
5 Implement a basic USB DFU device
6
7Overview
8********
9
10This sample application demonstrates the USB DFU implementation using the
11new experimental USB device stack.
12
13Requirements
14************
15
16This project requires an experimental USB device driver (UDC API) and uses the
17:ref:`disk_access_api` and RAM-disk to download/upload the image.
18
19Building and Running
20********************
21
22This sample can be built for multiple boards, in this example we will build it
23for the reel board:
24
25.. zephyr-app-commands::
26 :zephyr-app: samples/subsys/usb/dfu
27 :board: reel_board
28 :goals: build flash
29 :compact:
30
31`dfu-util`_ tool can be used to download or upload the images. There are two
32modes of operation in the USB DFU, runtime and DFU. The example starts in
33runtime mode. To switch to DFU mode without uploading or downloading, the
34following command can be used:
35
36.. code-block:: console
37
38 dfu-util --detach
39
40Use the following command to upload the ``ramdisk0`` image to the host:
41
42.. code-block:: console
43
44 dfu-util --alt 0 --upload ramdisk0_backup.bin
45
46Use the following command to download the ``ramdisk0`` image to the device:
47
48.. code-block:: console
49
50 dfu-util --alt 0 --download ramdisk0_backup.bin
51
52Building with flash backend enabled
53***********************************
54
55The USB DFU device support has a built-in flash backend. This backend uses
56:ref:`flash_img_api` and :ref:`flash_map_api` to write or read flash image, the
57implementation is similar to the one we had in the previous USB DFU device
58example.
59
60To use flash backend set the :kconfig:option:`CONFIG_APP_USB_DFU_USE_FLASH_BACKEND`.
61An additional interface will be available in DFU mode to upload/download the
62SLOT-1 image.
63
64It is also possible to try the sample together with the MCUboot bootloader
65library. The following example shows how to build MCUboot and this sample with
66flash backend and MCUboot support enabled using the :ref:`sysbuild`:
67
68.. zephyr-app-commands::
69 :tool: west
70 :zephyr-app: samples/subsys/usb/dfu
71 :board: reel_board
72 :goals: build flash
73 :west-args: --sysbuild
74 :gen-args: -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DCONFIG_APP_USB_DFU_USE_FLASH_BACKEND=y
75
76Another application image is required to be used as a firmware update and
77downloaded to SLOT-1. Build and sign a second application image e.g.
78:zephyr:code-sample:`hello_world`, which will be used as an image for the
79update. Do not forget to enable the required :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`
80option (as described in :ref:`mcuboot`). For example:
81
82.. zephyr-app-commands::
83 :app: zephyr/samples/hello_world
84 :board: reel_board
85 :gen-args: -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\" -DCONFIG_BOOTLOADER_MCUBOOT=y
86 :goals: flash
87
88Use the following command to download new image to the device:
89
90.. code-block:: console
91
92 dfu-util --alt 1 --download build/zephyr/zephyr.signed.bin
93
94Reset the SoC. MCUboot boot will swap the images and boot the new application,
95showing this output to the console:
96
97.. code-block:: console
98
99 *** Booting MCUboot v2.1.0-rc1-134-gb9d69dd2a2d6 ***
100 *** Using Zephyr OS build v3.7.0-4345-ga5d0d8533a41 ***
101 I: Starting bootloader
102 I: Primary image: magic=good, swap_type=0x4, copy_done=0x1, image_ok=0x1
103 I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
104 I: Boot source: none
105 I: Image index: 0, Swap type: test
106 I: Starting swap using move algorithm.
107 I: Bootloader chainload address offset: 0xc000
108 I: Image version: v0.0.0
109 I: Jumping to the first image slot
110 *** Booting Zephyr OS build v3.7.0-4345-ga5d0d8533a41 ***
111 Hello World! reel_board@1/nrf52840
112
113
114Reset the SoC again and MCUboot should revert the images and boot
115USB DFU sample, showing this output to the console:
116
117.. code-block:: console
118
119 *** Booting MCUboot v2.1.0-rc1-134-gb9d69dd2a2d6 ***
120 *** Using Zephyr OS build v3.7.0-4345-ga5d0d8533a41 ***
121 I: Starting bootloader
122 I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x3
123 I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
124 I: Boot source: none
125 I: Image index: 0, Swap type: revert
126 I: Starting swap using move algorithm.
127 I: Secondary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
128 I: Bootloader chainload address offset: 0xc000
129 I: Image version: v0.0.0
130 I: Jumping to the first image slot
131 *** Booting Zephyr OS build v3.7.0-4345-ga5d0d8533a41 ***
132 [00:00:00.000,335] <inf> main: USBD message: VBUS ready
133 [00:00:00.000,427] <inf> main: USB DFU sample is initialized
134
135
136.. _dfu-util: https://dfu-util.sourceforge.net/
137.. _Using MCUboot with Zephyr: https://docs.mcuboot.com/readme-zephyr
138