Microchip Device Firmware Update Tools (pymdfu package)

The pymdfu Python package contains various tools to support firmware updates of clients that implement the Microchip Device Firmware Update (MDFU) protocol.

Installation

Install using pip from pypi:

pip install pymdfu

MDFU host application command line interface pymdfu

pymdfu is a command line interface for the Microchip Device Firmware Update (MDFU) host application. It provides various actions to interact with MDFU clients, including updating firmware, retrieving client information, and getting help on tool-specific parameters.

Usage

pymdfu [-h | --help] [-v <level> | --verbose <level>] [-V | --version] [-R | --release-info] [<action>]

Actions

• client-info: Get MDFU client information.
• tools-help: Get help on tool-specific parameters.
• update: Perform a firmware update.

Global Options

• -h, --help: Show help message and exit.
• -v <level>, --verbose <level>: Set logging verbosity/severity level. Valid levels are [debug, info, warning, error, critical]. Default is info.
• -V, --version: Print pymdfu version number and exit.
• -R, --release-info: Print pymdfu release details and exit.

Examples

Update Firmware

Update firmware through a serial port with update_image.img:

pymdfu update --tool serial --image update_image.img --port COM11 --baudrate 115200

Get Client Information

Retrieve MDFU client information using a serial tool:

pymdfu client-info --tool serial --port COM11 --baudrate 115200

Version and release information

To print the version of pymdfu command line tool and the supported MDFU protocol version:

pymdfu --version

To print release details:

pymdfu --release-info

Help

For general help:

pymdfu --help

For help on a specific action:

pymdfu <action> --help

Get help on tool-specific parameters:

pymdfu tools-help

Configuration File

For some actions like update and client-info it is possible to specify a configuration file using the -c or --config-file option. The configuration file should be in TOML format and can include common parameters and tool-specific parameters. Parameters provided on the command line will take precedence over parameters specified in the config file. Options in tool-specific section will only be applied if the corresponding tool is used e.g. if --tool serial is provided the parameters in the section [serial] will be applied.

Example Configuration File

[common]
verbose = "debug"

[serial]
port = "COM11"
baudrate = 115200

[network]
host = "192.168.1.100"
port = 8080

CAN support

CAN support

MDFU client command line interface pymdfuclient

The pymdfuclient is a MDFU client with a command line interface and can be used to test MDFU hosts. The client implements the MDFU protocol but not any firmware image specific functions like decoding or verifying the firmware image. This means the tool is firmware image file agnostic and any file can be transferred with the client returning an image state as success after the transfer.

Future versions of this tool might offer specific client implementations that can decode and verify FW images e.g. FW images for Microchip 8-bit microcontroller that use the pyfwimagebuilder tool: https://pypi.org/project/pyfwimagebuilder/

Usage

pymdfuclient [-h | --help] [-v <level> | --verbose <level>] [-V | --version] [-R | --release-info]  [--config <path-to-config-file>] --tool <tool> [<tools-args>...]

Examples

Start MDFU client on localhost port 5558 and use the serial transport layer:

pymdfuclient --tool network --host localhost --port 5558 --transport serial

Start MDFU client on serial port COM11 with baudrate 115200:

pymdfuclient --tool serial --port COM11 --baudrate 115200

Client configuration

The MDFU client can be configured with the client information that is passed to a host and delays for command responses to simulate e.g. the time needed to verify the image or to program flash. The configuration can be done by passing a TOML file on the command line with the --config argument. When no configuration is provided all response delays are set to zero and the following default values are used for the client information.

Default client information:

• Version: 1.2.0
• Buffer count: 1
• Buffer size: 512
• Default timeout 10 seconds
• Inter transaction delay: 0 seconds

The configuration TOML file must contain sections for client information and response delays.

Example configuration file:

[client_info]
version = "1.2.0"
# Inter transaction delay in seconds
inter_transaction_delay = 0
buffer_count = 1
# Client buffer size in bytes
buffer_size = 512
# Default timeout in seconds that is used for all unspecified timeouts
default_timeout = 10 

# Client reported timeouts for commands in seconds
[client_info.timeouts]
GET_CLIENT_INFO = 0.1
START_TRANSFER = 1
WRITE_CHUNK = 0.5
GET_IMAGE_STATE = 4
END_TRANSFER = 1

# Response delays must not exceed corresponding client info timeouts
# All delays are specified in seconds
[response_delays]
GET_CLIENT_INFO = 0
START_TRANSFER = 0
WRITE_CHUNK = 0.2
GET_IMAGE_STATE = 2
END_TRANSFER = 0

Changelog

MDFU tools changelog