CLI description

In addition to the dfuh-tool GUI executable, there is also the dfuh-cli executable. The CLI allows programming, verifying, and erasing devices from a command-line prompt or from within batch files or shell scripts. The exit code for the dfuh-cli executable is zero if the operation is successful, or non-zero if the operation encounters an error.

To use the dfuh-cli executable, provide one of the following flags:


Flag	Description
`--program-device <input file(s)>`	Programs the device with the specified file and exits.
`--verify-device <input file(s)>`	Verifies the programming of the device with the specified file and exits.
`--erase-device <input file(s)>`	Erases the specified program from the device and exits.
`--custom-command <mtbdfu file>`	Executes commands defined in the specified *.mtbdfu file (JSON format).
`--generate-mtbdfu <mtbdfu file>`	Generates an *.mtbdfu file from the provided input arguments.

Use the following flag to specify which device to use:


Flag	Description
`--hwid <string>`	Specifies the hardware ID.

Host mode flags

When the DFU host communicates with a companion device through a bridge MCU, use the following flags to enable and configure Bridging mode.


Flag	Description
`--bridging`	Enables DFU Host Bridging mode on the target main MCU (sends 0x20 command with mode byte 0x00 for-bridging before starting the normal DFU flow and sends 0x23 on exit).
`--companion-interface <string>`	Sets the companion interface byte for the 0x20 command using the string values ("I2C", "UART") or a corresponding byte value. Default: 0x00.
`--companion-address <int>`	Sets the companion device address. For I2C, this is the slave address. Valid values: from 8 (0x08) to 120 (0x78. Required when the companion interface is I2C (0x01). Default: 0x00.

.mtbdfu generation (--generate mtbdfu) flags


Flag	Description
`--product-id <string>`	(Optional) Sets the product ID as a parameter for the generated *.mtbdfu file. Default value – 01020304.
`--file-version <string>`	(Optional) Sets the file version as a parameter for the generated *.mtbdfu file. Default value – 0x1.
`--checksum-type <string>`	Sets the packet checksum type as a parameter for the generated *.mtbdfu file. Default value – 0x0.
`--application-id <string>`	(Optional) Sets the application ID as a parameter for the generated *.mtbdfu file. Required only for legacy devices or devices with the DFU-MW-based bootloader.
`--application-start <string>`	(Optional) Sets the application start address as a parameter for the generated *.mtbdfu file. Required only for legacy devices or devices with the DFU-MW-based bootloader.
`--application-length <string>`	(Optional) Sets the application size as a parameter for the generated *.mtbdfu file. Required only for legacy devices or devices with the DFU MW based bootloader.
`--data-length <hex>`	(Optional) Sets the data packet length (in bytes) for Send Data commands during `program-device` and `verify-device`. The repeat count is computed automatically based on `flash-row-length`/`data-length`. Supports hexadecimal values. Default value – 0x10
`--flash-row-length <string>`	(Optional) Sets the flash row length on the device. Default value – 0x200.
`--timeout-ms <string>`	(Optional) Sets the timeout for the response packet (milliseconds). Default value – 0x12c.
`--start-address <string>`	Sets the start address for the .bin file as a parameter for the generated .mtbdfu file.
`--mtbdfu-data-file <input files(s)>`	Sets the firmware image file(s) for the generated *.mtbdfu file.

Note:

The above flags are also used to program the *.hex file because it generates an *.mtbdfu file and uses the same for programming the*.hex file.

Note:

The options “--application-start” and “--application-length” can be used to set the address range for filtering the needed part of the*.hex file. All extended linear address blocks before the “--application-start” address will be skipped as well as all the data at addresses after “--application-length” address.

In addition, you must provide the appropriate configuration values for one of the following protocols:

I²C flags


Flag	Description
`--i2c-address <int>`	Sets the address for I²C protocol. Valid values: from 8 (0x08) to 120 (0x78).
`--i2c-speed <int>`	Sets the speed for I²C protocol in kHz. Valid values: 50, 100, 400, 1000.
`--i2c-use-pmbus`	(Optional) Enables PMBus mode for I²C communication. Requires: --i2c-address and --i2c-speed. Allowed --i2c-speed values: 100, 400, 1000 kHz.
`--i2c-use-pec`	(Optional) Uses PMBus PEC byte. Requires: --i2c-use-pmbus.
`--i2c-cmd-code <int>`	(Optional) Sets PMBus user-defined command code byte. Requires: --i2c-use-pmbus. Valid values: from 0 (0x0) to 255 (0xFF). Default value – 0xE0.
`--i2c-cmd-size <int>`	(Optional) Sets the number of data bytes for the PMBus command. Requires: --i2c-use-pmbus. Valid values: from 0 to 255.

SPI flags


Flag	Description
`--spi-clockspeed <float>`	Sets the clock speed for SPI protocol in MHz.
`--spi-mode <int>`	Sets the mode for SPI protocol in binary. Valid values: 00, 01, 10, 11. The first byte defines CPHA, the second defines CPOL.
`--spi-lsb-first`	Sets the SPI bit order to LSB-first. When not specified, MSB-first is used (default).

UART flags


Flag	Description
`--uart-baudrate <int>`	Sets the baud rate for UART protocol.
`--uart-databits <int>`	Sets the number of data bits for UART protocol.
`--uart-paritytype <string>`	Sets the parity type for UART protocol. Valid strings are “None”, “Odd”, “Even”.
`--uart-stopbits <float>`	Sets the stop bits for UART protocol. Valid values are 1, 1.5, 2.

CAN-FD flags


Flag	Description
`--canfd-bitrate-switch`	Enables the switching between default and data bitrates.
`--canfd-bitrate <int>`	Sets the nominal communication bitrate. Supported nominal bitrates: 125000, 250000, 500000, 1000000.
`--canfd-data-bitrate <int>`	Sets the data communication bitrate for CAN-FD protocol. Supported data bitrates: 2000000, 4000000, 8000000, 10000000.
`--canfd-output-frame-id <string>`	Sets the output frame ID for CAN-FD protocol. Valid values: from 0x0 to 0x1FFFFFFF.
`--canfd-input-frame-id <string>`	(Optional) Sets input frame ID for CAN-FD protocol. Valid values: from 0x0 to 0x1FFFFFFF.
`--canfd-ext-frame`	Enables the extended frame support for CAN-FD protocol.

Note:

The DFU Host tool does not require any additional parameters to select the required interface besides the above specified parameters.

Command-line flags

The following flags change the overall functioning of the tool:


Flag	Description
`-?, -h, --help`	Displays information about all valid command-line arguments and exits.
`-v, --version`	Displays the version information and exits.
`--debug`	Outputs debug messages during a DFU process.
`--display-hw`	Outputs compatible hardware attached to the computer and exits.
`--timeout-ms <hex>`	(Optional) Sets the timeout for the response packet (milliseconds). Default value – 0x12c.
`--max-transfer-size <hex>`	Sets the max transfer size (in bytes) for a packet. Supports hexadecimal values from 0x0 to 0x1007. Default value – 0x80 (128 bytes).

CLI example

The following shows simple examples for using the dfuh-cli executable

Programming image via *.cyacd2 file

To program an image using the *.cyacd2 file under I2C:

dfuh-cli.exe --program-device test_app.cyacd2 --i2c-address 8 --i2c-speed 100

Generating and programming image via *.mtbdfu file and *.hex file

To generate an *.mtbdfu file (without metadata):

dfuh-cli.exe --generate-mtbdfu test_gen.mtbdfu --mtbdfu-data-file blinky_cm4_crc.hex --file-version 0x1 --product-id 01020304 --checksum-type 0x0

To generate an *.mtbdfu file for legacy devices (with metadata):

dfuh-cli.exe --generate-mtbdfu test_gen.mtbdfu --mtbdfu-data-file blinky_cm4_crc.hex --file-version 0x1 --product-id 01020304 --checksum-type 0x0 --application-id 0x1 --application-start 1005 --application-length fffc

To program a *.hex file through the *.mtbdfu file under UART (without metadata):

dfuh-cli --program-device test_app.hex --hwid COM5 --uart-baudrate 115200 --uart-databits 8 --uart-paritytype None --uart-stopbits 1 --file-version 0x1 --product-id 01020304 --checksum-type 0x0

To program a *.bin file through the *.mtbdfu file under I2C:

dfuh-cli --program-device test_app.bin --hwid <device> --i2c-address 0x12 --i2c-speed 400 --start-address 0x10000

To program a *.hex file through the *.mtbdfu file under I2C with PMBus mode:

dfuh-cli --program-device test_app.hex --hwid <device> --i2c-speed 100 --i2c-address 0x8 --i2c-use-pmbus --i2c-use-pec --i2c-cmd-code 0xAA

To execute or send commands through the *.mtbdfu file under SPI:

dfuh-cli --custom-command test.mtbdfu --hwid MiniProg4-0C0806F801071400 --spi-clockspeed 1.0 --spi-mode 0

To execute or send commands through the *.mtbdfu file under USB-HID:

dfuh-cli --custom-command test.mtbdfu --hwid PSoC_DFU_HID_De

To execute or send commands through the *.mtbdfu file under CAN-FD:

dfuh-cli --custom-command test.mtbdfu --hwid usb0  --canfd-bitrate 1000000 --canfd-data-bitrate 2000000 --canfd-output-frame-id 0x013 --canfd-bitrate-switch

To program a companion device through Bridging mode under I2C:

dfuh-cli --hwid KitProg3-14100A5A012D2400 --i2c-address 51 --i2c-speed 100 --program-device test-app.cyacd2 --bridging --companion-interface i2c --companion-address 52

I2C flags

SPI flags

UART flags

CAN-FD flags

Command-line flags

CLI example

I²C flags