USBIP Serial client

Overview

This package supports connecting to a CDC (serial) USB device exposed by a USBIPD server. USBIP is a protocol that allows sharing USB devices over a TCP/IP connection. The protocol specification can be found here. This package should be capable of running on any system that supports Python.

There are some issues sharing USB devices to docker containers, a major one being if the USB connection is lost it is difficult to recover the connection between the docker container and the hosting server.

Here's a link that discusses this issue and another solution.

The USBIP client implementation will only address USB devices that implemented the CDC protocol, basically simple serial devices. This allows for a direct connection to the USBIP server without the need of mapping USB devices into the container.

• Project Homepage: https://github.com/bp100a/serial-usbipclient

Installation

pip install serial-usbipclient should work for most users.

Usage

from serial_usbipclient.usbip_client import USBIPClient, HardwareID, USBIP_Connection

host: str = 'localhost'
port: int = 3240  # commonly used port for USBIPD servers
target: HardwareID = HardwareID(vid=1234, pid=5678)  # USB devices are identified by VID/PID
client: USBIPClient = USBIPClient(remote=(host, port))
client.connect_server()
client.attach(devices=[target])
connections: list[USBIP_Connection] = client.get_connection(device=target)

# using the established connection, data can be written to the USB device
# using the sendall() method
connections[0].sendall(data=b'\01\02\03\04')

# response data can be read either explicitly by specifying the size of the expected
# response, or if 0, the size is specified, up to a delimiter. The delimiter is a property of
# the connection and can be set, default=b'\r\n'
connections[0].delimiter = b'\n'
response: bytes = connections[0].response_data(size=0)  # reads until delimiter

SOUP

Useful Resources

For a Windows version of the usbipd server, look here. You can run this to share USB devices across a network, there are usbipd-clients for Linux & Windows.

Here's a USBIP server for testing written in RUST, https://github.com/jiegec/usbip.

Testing

A MockUSBIP service reads configuration information from the output of lsusb (e.g lsusb -d 1f46:1b01 -v). MockUSBIP will then play back this configuration. Just capture the output of the lsusb command and save with the .lsusb suffix in the test folder. The file name should be the busnum/devnum number.

1-1.lsusb
1-2.lsusb
1-3.lsusb
99-99.lsusb

Would result in 4 devices with busid values of 1-1, 1-2, 1-3 and 99-99. Please note the file 99-99.lsusb is reserved to provide a device to generate failing USBIPD attachments, and 1-2 & 1-3 have the same VID/PID (for testing multiple identical device connections).

During testing, the MockUSBIP service acts as a stand-in for an actual USBIP server. Since the tests are run in parallel, the port on which the service listens must be unique for each unit test. This is accomplished by the conftest.py::pytest_sessionstart which is run when the pytest session is started and collects all tests being run into a file called lists_of_tests.json. The unit test's index into this array is used to determine the offset to be added to the port base (typically 3240). The SocketWrapper class is overridden in unit tests to inject low-level socket failures.

Tooling

This package was created using JetBrains PyCharm Professional IDE, the repository does not contain any IDE specific files. Development work was done using Windows 11 & Python 3.12.5, with final verification on an Ubuntu 20.04 system.

Static code analysis performed using radon and xenon.

Packages required to run tests

Packages required to publish to PyPi

All tooling is defined in the pyproject.toml and managed using poetry as follows:

poetry install --with tests

Tooling is not needed to run the package but is required for testing and packaging.

Build Process

Store the PyPi API token

keyring set https://upload.pypi.org/legacy/ __token__

when prompted, enter the API token you created using PyPi.

To build the distribution and upload to PyPi

poetry build
poetry publish