Metadata-Version: 2.1
Name: pyfu-usb
Version: 2.0.1
Summary: Python USB firmware update library.
Home-page: https://github.com/square/pyfu-usb
Author: Block, Inc.
License: MIT
Keywords: dfu-util,pydfu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyusb (>=1.0.2)
Requires-Dist: rich (>=12.2)
Provides-Extra: dev
Requires-Dist: black (~=22.3.0) ; extra == 'dev'
Requires-Dist: mypy (==0.942) ; extra == 'dev'
Requires-Dist: types-setuptools (~=57.4.14) ; extra == 'dev'
Requires-Dist: pylint (~=3.2.7) ; extra == 'dev'
Requires-Dist: pre-commit (~=2.18.1) ; extra == 'dev'
Requires-Dist: wheel (~=0.37.1) ; extra == 'dev'
Requires-Dist: twine (~=4.0.0) ; extra == 'dev'
Requires-Dist: pytest (~=7.1.2) ; extra == 'dev'
Requires-Dist: coverage (~=6.4) ; extra == 'dev'

# pyfu-usb: Python USB Firmware Updater

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A small library for firmware updates over USB with devices that support the [DFU](https://www.usb.org/sites/default/files/DFU_1.1.pdf) and [DfuSe](http://dfu-util.sourceforge.net/dfuse.html) protocols. Specifically, `pyfu-usb` supports _listing_ DFU capable devices and _downloading binary files_ to them.

## Compared to [`dfu-util`](http://dfu-util.sourceforge.net/)

`dfu-util` is the popular host side tool for interacting with DFU/DfuSe devices. `pyfu-usb` has only a small sliver the functionality contained in `dfu-util`: Listing and downloading binary files. The reason you would use `pyfu-usb` over `dfu-util` is if you have a Python project that needs firmware update capabilities and don't want an external (non-Python) dependency.

## Compared to [`pydfu.py`](https://github.com/openmv/openmv/blob/9f06eb4fe15f4f181250aa5848c3e3e51bb85506/tools/pydfu.py)

`pydfu.py` is a tool in the _OpenMV_ project that solves the exact problem described above, but it is only for DfuSe devices (e.g. STM32) and also hard codes a number of parameters including device address and max transfer size. It also appears to only work with `.dfu` files, which require an extra conversion step. Since binary files can be directly generated by many embedded toolchains using them is simpler, although less portable.

The code in this package originates from `pydfu.py` and the _OpenMV_ license agreement has been copied into the repository. Along with refactoring the code and adding support for "classic" DFU devices, several modernizations were added:

- Colored logs and progress bar with `rich`
- Using `logging` instead of `print` for output messages
- Consistent style with `black` and linting with `pylint`

## Dependencies

Even though this package may appear pure Python, by relying on `pyusb` we rely on `libusb` being installed. See the [`pyusb` docs](https://github.com/pyusb/pyusb#requirements-and-platform-support) for more details on platform support.

## User Guide

Install with `pip`:

```bash
pip install pyfu-usb
```

List connected DFU devices:

```bash
pyfu-usb --list
```

Download a file to a DfuSe capable device, specifying a start address in hex:

```bash
pyfu-usb --download <filename> -a <start_address>
```

Download a file to a DFU capable device:

```bash
pyfu-usb --download <filename>
```

Use the `--device` argument to specify the `vid:pid` of the device in hex if multiple are connected. See the [examples](examples/) directory for more detailed examples.

## Developer Guide

The `Makefile` contains workflow helpers for the development environment.

To setup the virtual environment:

```bash
make setup
```

To activate the virtual environment:

```bash
source .venv/bin/activate
```

To run pre-commit hooks (style, linting):

```bash
make pre_commit
```

To run unit tests:

```bash
make test
```

To build the wheel:

```bash
make wheel
```

To view code coverage metrics:

```bash
make coverage
```

To delete generated files:

```bash
make clean
```

## Contributing

Please see the [documentation](.github/CONTRIBUTING.md) prior to contributing.

## License

Licensed under the [MIT license](LICENSE).
