.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.8.
.TH DFU-TOOL "1" "May 2021" "dfu-tool 1.2.14" "User Commands"
.SH NAME
dfu-tool \- dfu-tool
.SH DESCRIPTION
.PP
This manual page documents briefly the \fBdfu-tool\fR command.
.PP
\fBdfu-tool\fR allows a user to write various kinds of
firmware onto devices supporting the USB Device Firmware Upgrade protocol.
This tool can be used to switch the device from the normal runtime mode
to `DFU mode' which allows the user to read and write firmware.
Either the whole device can be written in one operation, or individual
`targets' can be specified with the alternative name or number.
.PP
\fBdfu-tool\fR uses the libdfu shared
library to perform actions.
All synchronous actions can be safely cancelled and on failure will return
errors with both a type and a full textual description.
libdfu supports DFU 1.0, DFU 1.1 and the ST DfuSe vendor extension, and
handles many device `quirks' necessary for the real-world implementations
of DFU\&.
.PP
Additionally \fBdfu-tool\fR can be used to convert firmware
from various different formats, or to modify details about the elements,
images and metadata contained inside the firmware file.
For example, you can easily convert DFU 1.1 firmware into the
vendor-specific DfuSe format, convert a Intel HEX file into a raw file
padded to a specific size, or add new copyright and licensing information
to an existing file.
Fields such as the vendor and product IDs can be changed, and the firmware
elements can be encrypted and decrypted using various different methods.
Merging two DfuSe files together is also possible, although specifying
different alt-setting numbers before merging is a good idea to avoid
confusion.
.PP
Although \fBdfu-tool\fR tries to provide a large number of
easy-to-use commands, it may only be possible to do certain operations
using the libdfu library directly.
This is easier than it sounds, as the library is built with GObject
Introspection support making it usable in many languages such as C,
Javascript and Python.
Furthermore, using the library is a good idea if you want to perform
multiple operations on large firmware files, for instance,
converting from an Intel HEX file, padding to a certain size, setting
vendor and adding licensing information and then saving to a remote
location.
.SS "Usage:"
.IP
dfu\-tool [OPTION?]
.TP
attach
Attach DFU capable device back to runtime
.TP
convert FORMAT FILE\-IN FILE OUT [SIZE]
Convert firmware to DFU format
.TP
decrypt FILENAME\-IN FILENAME\-OUT TYPE KEY
Decrypt firmware data
.TP
detach
Detach currently attached DFU capable device
.TP
dump FILENAME
Dump details about a firmware file
.TP
encrypt FILENAME\-IN FILENAME\-OUT TYPE KEY
Encrypt firmware data
.TP
list
List currently attached DFU capable devices
.TP
merge FILE\-OUT FILE1 FILE2 [FILE3...]
Merge multiple firmware files into one
.TP
patch\-apply
Apply a binary patch
.TP
patch\-create
Create a binary patch using two files
.TP
patch\-dump
Dump information about a binary patch to the screen
.TP
read FILENAME
Read firmware from device into a file
.TP
read\-alt FILENAME DEVICE\-ALT\-NAME|DEVICE\-ALT\-ID
Read firmware from one partition into a file
.TP
replace\-data
Replace data in an existing firmware file
.TP
reset
Reset a DFU device
.TP
set\-address FILE ADDRESS
Set element address on firmware file
.TP
set\-alt\-setting FILE ALT\-ID
Set alternative number on firmware file
.TP
set\-alt\-setting\-name FILE VALUE
Set alternative name on firmware file
.TP
set\-metadata FILE KEY VALUE
Sets metadata on a firmware file
.TP
set\-product FILE PID
Set product ID on firmware file
.TP
set\-release FILE RELEASE
Set release version on firmware file
.TP
set\-target\-size FILE SIZE
Set the firmware size for the target
.TP
set\-vendor FILE VID
Set vendor ID on firmware file
.TP
watch
Watch DFU devices being hotplugged
.TP
write
Write firmware from file into device
.TP
write\-alt FILENAME DEVICE\-ALT\-NAME|DEVICE\-ALT\-ID [IMAGE\-ALT\-NAME|IMAGE\-ALT\-ID]
Write firmware from file into one partition
.SS "Help Options:"
.TP
\fB\-h\fR, \fB\-\-help\fR
Show help options
.SS "Application Options:"
.TP
\fB\-\-version\fR
Print the version number
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print verbose debug statements
.TP
\fB\-d\fR, \fB\-\-device\fR=\fI\,VID\/\fR:PID
Specify Vendor/Product ID(s) of DFU device
.TP
\fB\-t\fR, \fB\-\-transfer\-size\fR=\fI\,BYTES\/\fR
Specify the number of bytes per USB transfer
.TP
\fB\-\-force\fR
Force the action ignoring all warnings