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] | Sends an *.mtbdfu file (JSON format) as the input to the DFU Host tool. |
--generate-mtbdfu [mtbdfu_file] | Generates an *.mtbdfu file from the provided input arguments. |
If there is more than one device connected to the host, use the following flag to specify which device to use:
| Flag | Description |
|---|---|
--hwid [string] | Specifies the ID of the hardware to program/verify/erase. If this option is skipped, the first appropriate device found will be used. |
.mtbdfu generation (--generate mtbdfu) flags
| Flag | Description |
|---|---|
--product-id [hex] | Sets the product ID as a parameter for the generated *.mtbdfu file. |
--file-version [hex] | Sets the file version as a parameter for the generated *.mtbdfu file. |
--checksum-type [hex] | Sets packet checksum type as a parameter for generated *.mtbdfu file. |
--application-id [hex] | (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 [hex] | (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 [hex] | (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. |
--flash-row-length [hex] | (Optional) Sets the flash row length on the device. |
--timeout-ms [hex] | (Optional) Alters the timeout for the response packet(milliseconds). |
--start-address | Used with a *.bin file. Defines the flash memory address where the raw binary’s first byte is written. |
--mtbdfu-data-file | Sets the firmware image hex file for the generated *.mtbdfu file. |
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.
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:
I2C flags
| Flag | Description |
|---|---|
--i2c-address [int] | Sets the address for the I2C protocol. Valid values are between 8 "0x08" and 120 "0x78". |
--i2c-speed [int] | Sets the speed for the I2C protocol in kHz. Common values are 50, 100, 400, and 1000. |
--i2c-use-pmbus | (Optional) Enable PMBus mode for I2C communication. |
--i2c-use-pec | (Optional) Enable the PMBus PEC for data integrity. Default - False. |
--i2c-cmd-code [int] | (Optional) The PMBus command byte to send. Valid values are between 0 "0x0" and 255 "0xFF". Default – 0xE0. |
--i2c-cmd-size [int] | (Optional) The number of data bytes for the PMBus command. Valid values are between 0 and 255. |
SPI flags
| Flag | Description |
|---|---|
--spi-clockspeed [float] | Sets the clock speed for the SPI protocol in MHz. |
--spi-mode [int] | Sets the mode for the SPI protocol in binary. Valid values are 00, 01, 10, and 11. |
--spi-lsb-first | Specifies that the least-significant bit should be sent first for the SPI protocol. Otherwise, the most-significant bit will be sent first. |
UART flags
| Flag | Description |
|---|---|
--uart-baudrate [int] | Sets the baud rate for the UART protocol. |
--uart-databits [int] | Sets the number of data bits for the UART protocol. |
--uart-paritytype [string] | Sets the parity type for the UART protocol. Valid strings are “None”, “Odd”, and “Even”. |
--uart-stopbits [float] | Sets the stop bits for the UART protocol. Valid values are 1, 1.5, and 2. |
CAN-FD flags
| Flag | Description |
|---|---|
--canfd-bitrate [int] | Sets the nominal communication bitrate. The supported nominal bitrates are: 125000, 250000, 500000, 1000000. |
--canfd-databitrate [int] | Sets data communication bitrate.The supported data bitrates are: 2000000, 4000000, 8000000, 10000000. |
--canfd-output-frame-id [int] | Sets output frame ID. |
--canfd-input-frame-id [int] | (Optional) Sets input frame ID. |
--canfd-ext-frame | Enables extended frame support. |
--canfd-use-fd | (Optional) Use CAN-FD packet structure. |
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 debugging information to the terminal running the CLI tool during programming, verifying or erasing. |
--display-hw | Outputs all compatible hardware attached to the computer and exits. |
--timeout-ms [hex] | Alters the timeout for the response packet(milliseconds). |
--max-transfer-size [int] | Alters the maximum size of the data payload in the command packet. By default, equals 128 bytes. Defined by variable DEFAULT_MAX_TRANSFER_SIZE in the source code. |
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:
dfuh-cli --custom-command test.mtbdfu --hwid usb0 --canfd-bitrate 1000000 --canfd-output-frame-id 0x013
To execute or send commands through the *.mtbdfu file under CAN-FD:
dfuh-cli --custom-command test.mtbdfu --hwid usb0 --canfd-use-fd.--canfd-bitrate 1000000 --canfd-data-bitrate 2000000 --canfd-output-frame-id 0x013