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 <cyacd2_file> | Programs the device with the specified file and exits. |
--verify-device <cyacd2_file> | Verifies the programming of the device with the specified file and exits. |
--erase-device <cyacd2_file> | 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). Also, applicable to *.cyacd2 files usage. |
--mtbdfu-data-file | Sets the firmware image hex file 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:
I2C flags
Flag | Description |
|---|---|
--i2c-address <int> | Sets the address for the I 2 C protocol. Valid values are between 8 "0x08", and 120 "0x78)". |
--i2c-speed <int> | Sets the speed for the I 2 C protocol in kHz. Common values are 50, 100, 400, and 1000. |
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 |
|---|---|
| Sets the nominal communication bitrate. The supported nominal bitrates are: 125000, 250000, 500000, 1000000. |
| Sets data communication bitrate.The supported data bitrates are: 2000000, 4000000, 8000000, 10000000. |
| Sets output frame ID. |
| (Optional) Sets input frame ID. |
| Enables switching between default and data bitrates. |
| Disables switching between default and data bitrates. |
| Enables extended frame support. |
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 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). Applicable to the *.cyacd2 files usage. |
--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 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_Dev
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-enable-bitrate-switch