1DFU-TOOL(1)                      User Commands                     DFU-TOOL(1)
2
3
4

NAME

6       dfu-tool - dfu-tool
7

DESCRIPTION

9       This manual page documents briefly the dfu-tool command.
10
11       dfu-tool  allows a user to write various kinds of firmware onto devices
12       supporting the USB Device Firmware Upgrade protocol.  This tool can  be
13       used  to  switch  the device from the normal runtime mode to `DFU mode'
14       which allows the user to read and write  firmware.   Either  the  whole
15       device  can be written in one operation, or individual `targets' can be
16       specified with the alternative name or number.
17
18       dfu-tool uses the libdfu shared library to perform actions.   All  syn‐
19       chronous  actions  can  be  safely cancelled and on failure will return
20       errors with both a type and a full textual  description.   libdfu  sup‐
21       ports  DFU  1.0, DFU 1.1 and the ST DfuSe vendor extension, and handles
22       many device `quirks' necessary for the  real-world  implementations  of
23       DFU.
24
25       Additionally dfu-tool can be used to convert firmware from various dif‐
26       ferent formats, or to modify details about  the  elements,  images  and
27       metadata contained inside the firmware file.  For example, you can eas‐
28       ily convert DFU 1.1 firmware into  the  vendor-specific  DfuSe  format,
29       convert  a Intel HEX file into a raw file padded to a specific size, or
30       add new copyright  and  licensing  information  to  an  existing  file.
31       Fields  such  as  the  vendor  and  product IDs can be changed, and the
32       firmware elements can be encrypted and decrypted using various  differ‐
33       ent  methods.   Merging  two  DfuSe  files  together  is also possible,
34       although specifying different alt-setting numbers before merging  is  a
35       good idea to avoid confusion.
36
37       Although  dfu-tool  tries to provide a large number of easy-to-use com‐
38       mands, it may only be possible  to  do  certain  operations  using  the
39       libdfu library directly.  This is easier than it sounds, as the library
40       is built with GObject Introspection support making it  usable  in  many
41       languages  such  as  C,  Javascript and Python.  Furthermore, using the
42       library is a good idea if you want to perform  multiple  operations  on
43       large  firmware files, for instance, converting from an Intel HEX file,
44       padding to a certain size, setting vendor and adding licensing informa‐
45       tion and then saving to a remote location.
46
47   Usage:
48              dfu-tool [OPTION?]
49
50       attach Attach DFU capable device back to runtime
51
52              convert FORMAT FILE-IN FILE OUT [SIZE]
53
54              Convert firmware to DFU format
55
56              decrypt FILENAME-IN FILENAME-OUT TYPE KEY
57
58              Decrypt firmware data
59
60       detach Detach currently attached DFU capable device
61
62       dump FILENAME
63              Dump details about a firmware file
64
65              encrypt FILENAME-IN FILENAME-OUT TYPE KEY
66
67              Encrypt firmware data
68
69       list   List currently attached DFU capable devices
70
71              merge FILE-OUT FILE1 FILE2 [FILE3...]
72
73              Merge multiple firmware files into one
74
75       patch-apply
76              Apply a binary patch
77
78       patch-create
79              Create a binary patch using two files
80
81       patch-dump
82              Dump information about a binary patch to the screen
83
84       read FILENAME
85              Read firmware from device into a file
86
87              read-alt FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID
88
89              Read firmware from one partition into a file
90
91       replace-data
92              Replace data in an existing firmware file
93
94       reset  Reset a DFU device
95
96       set-address FILE ADDRESS
97              Set element address on firmware file
98
99       set-alt-setting FILE ALT-ID
100              Set alternative number on firmware file
101
102              set-alt-setting-name FILE VALUE
103
104              Set alternative name on firmware file
105
106       set-metadata FILE KEY VALUE
107              Sets metadata on a firmware file
108
109       set-product FILE PID
110              Set product ID on firmware file
111
112       set-release FILE RELEASE
113              Set release version on firmware file
114
115       set-target-size FILE SIZE
116              Set the firmware size for the target
117
118       set-vendor FILE VID
119              Set vendor ID on firmware file
120
121       watch  Watch DFU devices being hotplugged
122
123       write  Write firmware from file into device
124
125              write-alt         FILENAME         DEVICE-ALT-NAME|DEVICE-ALT-ID
126              [IMAGE-ALT-NAME|IMAGE-ALT-ID]
127
128              Write firmware from file into one partition
129
130   Help Options:
131       -h, --help
132              Show help options
133
134   Application Options:
135       --version
136              Print the version number
137
138       -v, --verbose
139              Print verbose debug statements
140
141       -d, --device=VID:PID
142              Specify Vendor/Product ID(s) of DFU device
143
144       -t, --transfer-size=BYTES
145              Specify the number of bytes per USB transfer
146
147       --force
148              Force the action ignoring all warnings
149
150
151
152dfu-tool 1.0.8                   November 2018                     DFU-TOOL(1)