Contributing

usbx is an open-source project that happily accepts contributions, usually in the form of GitHub pull requests.

Setting up your development environment

To work on the project, you will typically want to use a virtual environment and install this package in editable mode:

git clone https://github.com/manuelbl/usbx.git
cd usbx
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install --editable .

Running unit tests

In order to run the unit tests, a test device must be connected. They can be built from inexpensive microcontroller development boards (BluePill, BlackPill) and are shared with the Java Does USB project. Instructions on how to build them can be found on GitHub:

• Loopback device

• Composite device

The boards mostly cover the same features. The differences are:

• The loopback device covers all explicit tests.

• The composite device omits the alternate interface settings and the interrupt endpoints but adds a composite function (USB to serial interface). Thus, it implicitly tests the correct handling of composite devices, which is particularly tricky on Windows.

To run the test from the command line:

python -m unittest

For a good test coverage, unit tests must be run on Windows, macOS and Linux as mostly separate code is used for these operating systems.

Contributing to documentation

The documentation can be built locally:

cd docs
pip install -r requirements.txt
make html

The resulting HTML files are found in docs/_build.