pymdfu 2.4.0.8

Description:

pymdfu 2.4.0.8

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

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] --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

Changelog
[2.4.0] - August 2024

pymdfu CLI and library

SPI transport layer
Packet based networking layer
Linux SPI subsystem support
Linux I2C subsystem support
Transport and MAC layers refactored into their own sub-modules
Aardvark tool support with SPI and I2C interfaces
MCP2221A tool support
MCP2210 tool support
Logging configuration through TOML file
Support MDFU protocol specfication version 1.1
Checks for client MDFU version and exits if not supported by host
CLI help for tool specific options
CLI configuration by file


pymdfuclient

Support for serial port.



Added

PYTOOLS-278 Packet based networking MAC
PYTOOLS-277 Serial interface support in pymdfuclient
PYTOOLS-275 Linux SPI and I2C subsystem support
PYTOOLS-274 SPI transport layer spec update
PYTOOLS-271 Transport and MAC layer restructuring
PYTOOLS-270 Aardvark tool support
PYTOOLS-269 Replace yaml logging configuration with TOML
PYTOOLS-267 Update pymdfu excludes
PYTOOLS-257 Remove @property from classmethods since it will not be supported in Python 3.13
PYTOOLS-254 SPI transport layer
PYTOOLS-253 MCP2210 tool
PYTOOLS-243 MCP2221A tool
PYTOOLS-242 I2C transport layer prototype
PYTOOLS-191 Add supported MDFU protocol version and verify client version
PYTOOLS-160 Tools API rework
PYTOOLS-111 Specification for CLI configuration file
PYTOOLS-17 Support for reading configuration file
PYTOOLS-14 CLI help for tool specific options
PYTOOLS-258 Document new CLI commands and options

Fixed

PYTOOLS-265 Handle file transfer abort response when no additional data is present
PYTOOLS-210 Code in pymdfu break binary building

[1.0.2] - December 2023
Added

PYTOOLS-211 Add missing packaging dependency

[1.0.1] - December 2023

Support MDFU get client info command

Read client command timeouts
Read client MDFU protocol version


Support individual command timeouts
Decode transport and file transfer abort error causes
Check image state command response
Bugfixes

Added

PYTOOLS-156 New get client information command with version and command timeouts
PYTOOLS-91 Decode transport and file transfer abort error causes
PYTOOLS-90 Check "get image state" command response packet payload for image status

Fixed

PYTOOLS-155 PyMDFU tool usage guideline is incorrect
PYTOOLS-84 Document link between pymdfu and pyfwimagebuilder

[0.1.4] - October 2023
Initial public beta release.
Initial beta release
[0.0.1] - October 2023

Placeholder release