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              Convert firmware to DFU format
54
55       decrypt FILENAME-IN FILENAME-OUT TYPE KEY
56              Decrypt firmware data
57
58       detach Detach currently attached DFU capable device
59
60       dump FILENAME
61              Dump details about a firmware file
62
63       encrypt FILENAME-IN FILENAME-OUT TYPE KEY
64              Encrypt firmware data
65
66       list   List currently attached DFU capable devices
67
68       merge FILE-OUT FILE1 FILE2 [FILE3...]
69              Merge multiple firmware files into one
70
71       patch-apply
72              Apply a binary patch
73
74       patch-create
75              Create a binary patch using two files
76
77       patch-dump
78              Dump information about a binary patch to the screen
79
80       read FILENAME
81              Read firmware from device into a file
82
83       read-alt FILENAME DEVICE-ALT-NAME|DEVICE-ALT-ID
84              Read firmware from one partition into a file
85
86       replace-data
87              Replace data in an existing firmware file
88
89       reset  Reset a DFU device
90
91       set-address FILE ADDRESS
92              Set element address on firmware file
93
94       set-alt-setting FILE ALT-ID
95              Set alternative number on firmware file
96
97       set-alt-setting-name FILE VALUE
98              Set alternative name on firmware file
99
100       set-metadata FILE KEY VALUE
101              Sets metadata on a firmware file
102
103       set-product FILE PID
104              Set product ID on firmware file
105
106       set-release FILE RELEASE
107              Set release version on firmware file
108
109       set-target-size FILE SIZE
110              Set the firmware size for the target
111
112       set-vendor FILE VID
113              Set vendor ID on firmware file
114
115       watch  Watch DFU devices being hotplugged
116
117       write  Write firmware from file into device
118
119       write-alt             FILENAME            DEVICE-ALT-NAME|DEVICE-ALT-ID
120       [IMAGE-ALT-NAME|IMAGE-ALT-ID]
121              Write firmware from file into one partition
122
123   Help Options:
124       -h, --help
125              Show help options
126
127   Application Options:
128       --version
129              Print the version number
130
131       -v, --verbose
132              Print verbose debug statements
133
134       -d, --device=VID:PID
135              Specify Vendor/Product ID(s) of DFU device
136
137       -t, --transfer-size=BYTES
138              Specify the number of bytes per USB transfer
139
140       --force
141              Force the action ignoring all warnings
142
143
144
145dfu-tool 1.2.9                     May 2019                        DFU-TOOL(1)