ModusToolbox DFU Host tool user guide

The DFU Host tool is a cross platform utility for managing DFU firmware upgrades. The tool has both GUI and CLI interfaces.

This tool allows you to:

• Program new application data onto the supported MCU device using supported input files. See Supported devices and file formats.
• Verify the program data that is already contained on the device.
• Erase the application from the device.
• Select the *.mtbdfu file output from a ModusToolbox™ application in order to program, write, read, erase and communicate with the device.
• Abort the current operation.
  Note:

  This operation leaves the device in whatever state it is in when the abort message is acted upon.

The DFU Host tool supports communicating via I²C, SPI, UART, USB-CDC, USB-HID, and CAN-FD. They are displayed to configure their settings and view the programming status. For I²C and SPI, supported MCU should include the KitProg3 firmware module or other bridge interface, which implements USB-UART, USB-I²C, and USB-SPI bridges. For UART, communication can be done directly from the PC simply by connecting an appropriate cable. For CAN-FD, PEAK System hardware must be used.

All MCUs can be used with the all files formats.

The source code for the DFU Host tool is provided in the installation directory:

• Windows: ~/ModusToolbox/tools_<version>/dfuh-tool/sample_code
• Linux™: /opt/Tools/ModusToolbox/tools_<version>/dfuh-tool/share/dfuh-tool/sample_code/
• macOS: /Applications/ModusToolbox/tools_<version>/dfuh-tool/dfuh-tool.app/Contents/sample_code/

Use this source code as a reference to build your own tool. Refer to the README.md file for instructions on how to install the required dependencies and build the DFU Host Tool.

This section contains a simple workflow for how to use the DFU Host tool.

1. Ensure that you have a supported MCU that has been programmed with an application that includes the DFU capability.
2. Launch the DFU Host tool.
3. Click File > Open to browse to the location of your application file: *.cyacd2, *.mtbdfu, *.hex or *.bin).
4. Connect the device with an application that includes the DFU capability.
5. Wire the hardware port pins to the corresponding pins on the target device.
6. Update the Port configuration. These values are set from the communication component used by the bootloader component.
7. Click Program/Execute to load the new application from *.bin, *.cyacd2 or *.hex file and to execute and send the commands from the .*mtbdfu file.

There are several ways to launch the DFU Host tool, and those ways depend on how you use the various tools in ModusToolbox™ software.

Menus

File

• Open… – Opens an existing input file of the supported formats. If a file is already open, it will be closed.
• Save Log As… – Opens the dialog to save the log file in a specified location.
• Clear Log – Clears the current log.
• Exit – Closes the DFU Host tool.

Actions

• Program – Programs the application to the device.
• Execute – Executes the .mtbdfu file on the host, establishes a DFU session with the target and processes the DFU commands
• Verify – Verifies the programming of the device.
• Erase All – Erases the program from the device.
• Abort – Aborts the action.

View

• Toolbar – Shows/hides the toolbar.

Help

• View Help – Opens this document.
• About Device Firmware Update Host Tool – Opens the About box for version information, with links to open https://www.infineon.com and the current session log file.

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:

Use the following flag to specify which device to use:

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.

.mtbdfu generation (--generate mtbdfu) flags

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

The DFU Host tool requires the .mtbdfu file file (JSON format) as the default input file. It also supports the *.cyacd2 file format for the basic program, verify, and erase operations as an input to retain the backward compatibility for PSOC™ 4 and PSOC™ 6 legacy devices.

The details for the supported input file:

• *.mtbdfu file: The JSON input file for the DFU Host tool. It can be used for communication with the device using different commands available in the file. It should include a set of commands with respective data to be sent to the device through the DFU Host tool, using the DFU Command-Response protocol.
• *.cyacd2 file: This can only be used for the firmware update use case. The file will consist of the required header information for the firmware image along with the firmware binary and address where data will be loaded. This format is only supported for PSOC™ 6 and PSOC™ 4 devices.

However, for the basic program, verify, and erase operations, the DFU Host tool can generate an *.mtbdfu file using the *.hex file provided as an input with the necessary header parameters required for the *.mtbdfu file. The below figure shows the dynamic window of the DFU Host tool, which displays when the *.hex file is selected as the input.

• The green box on the toolbar indicates the actions available for using a *.hex or *.bin file as an input: program, verify, and erase the device. Modify the required parameter shown in the image and select the required option.
• The blue box displays the *.hex file path selected as an input to the host tool. Only limited operations/actions are possible with selecting the *.hex or *.bin file as the input. For complex operation, use the *.mtbdfu file with the required set of commands.
• The red box indicates the Configure and Generate buttons. Click the Configure button to open the "Configuration" window (see Main window) where you can define the values of the "APPInfo" section, "timeoutMS" and "flashRowLength" of the *.mtbdfu file to be generated. The window displays the default values. They can be modified per device and use case. For more details, refer to the .mtbdfu file section. The Generate button generates the reference *.mtbdfu file for the program use case, the file will be saved in the same folder as the selected *.hex or *.bin file.

{
    "APPInfo": {
        "File Version": "0x1",
        "Packet Checkum Type": "0x0",
        "Product Id": "01020304"
    },
    "commands": [
        {
            "commandSet":[
                {
                    "cmdId":"0x37",
                    "dataLength":"0x10",
                    "repeat":"0x20"
                },
                {
                    "cmdId": "0x49",
                    "dataLength": "0x08"
                }
            ],
            "dataFile":"blinky_cm4_crc.hex",
            "flashRowLength":"0x200",
            "repeat": "EoF",
            "timeoutMS": "0x12c"
        }
    ]
}

The above JSON sample displays the template *.mtbdfu file generated from the given *.hex file as the input. The DFU Host Tool will use the *.mtbdfu file for programming the firmware *.hex file to the device.

The default flow of the DFU-MW-based firmware update includes a set of repetitive Send Data commands (0x37), a program row command (0x49) with the row checksum, and the row address to write.

The set of 0x37 commands must send exactly the same number of bytes as specified in the flashRowLength field to provide enough data to the device DFU buffer for the program or verify operations. The sample JSON above sends 32 (0x20) Send Data commands and each of them passes 16 (0x10) bytes of data, so that the amount of passed data (32*16=512) equals the length of the flash row.

You can increase the number of data bytes in order to decrease the number of operations and execution time by sending 32 bytes 16 times, 64 bytes 8 times or even sending 121 bytes 4 times and 28 bytes 1 time (121*4+28=512). These combinations depend on the interface, its maximum transfer size, bootloader, and flash row length. Some bootloaders (for example, Extended Boot) support only up to 60 bytes per packet via the SPI, and common use cases of I²C and SPI via KitProg/MiniProg usually allow the maximum of 64 bytes per packet. The maximum packet size, which can be sent out of the DFU Host Tool is 128 bytes, so the maximum data size in one packet is 121 (7 bytes describe the packet).

The JSON file uses the APPInfo object required for the DFU communication setup. It contains potential information, the image version, product ID of the device the same as loaded with the loader application along with the checksum type for DFU command packet.

The sample contains the command object, which contains the list of command sent to the device. This object can be used to send a single as well as multiple DFU commands in the sequence required. The object contains another sub-object commandSet, which can group multiple commands to provide shared data across the group and repeat the set of commands.

In the JSON sample above, the command set is repeated till the end of the image file. The DFU application requires the flash row length to divide the packets into multiple sets. For more details, refer to AN 236282.

The DFU Host tool uses a set of timeouts for read operation before disconnecting and sending a "timeout" error. These internal configurations are suited for the development and field upgrade operations for programming the firmware or communicating with the device.

However, these configurations might require modification while debugging the DFU applications with transports using the multiple breakpoint in the target side. Due to the breakpoint, the device will pause execution and might not be able to send a response desired by the DFU Host Tool. Recommended – modify the timeout configuration and rebuild the DFU Host Tool while debugging the application using the DFU transport.

Modify the source code available in sample_code. See Example code for the appropriate path for your OS.

You can go to ~/sample_code/include/backend/cychannel.h and alter variable DEFAULT_TIMEOUT_MS. By default, it is equal to 300 milliseconds. Also, you can alter the variable DEFAULT_MAX_TRANSFER_SIZE to change the maximum allowed amount of bytes to be sent in one packet (including packet header and footer) for the GUI. By default, it is equal to 128 bytes.

After making the above modification in the source code of the DFU Host tool, build the DFU Host tool again. For details of building the DFU Host tool, refer to section Example code.

This section lists and describes the changes for each version of this tool.