awusb
Client-server software to share USB devices over the network.
| Source | https://github.com/epics-containers/awusb |
|---|---|
| PyPI | pip install awusb |
| Docker | docker run ghcr.io/epics-containers/awusb:latest |
| Releases | https://github.com/epics-containers/awusb/releases |
Documentation
- Quick Start Guide - Get started from installation to first device share
- Architecture - Understand the client-server model and design
Multi-Server Configuration
You can configure awusb to scan multiple USB device servers automatically. The client discovers configuration files in the following priority order:
- Environment variable:
AWUSB_CONFIG=/path/to/config.yaml - Project-local config:
.awusb.configin current directory - User config:
~/.config/awusb/awusb.config(default)
Create a configuration file with the following format:
servers:
- localhost
- raspberrypi
- 192.168.1.100
- usb-server-1.local
# Optional: Connection timeout in seconds (default: 5.0)
timeout: 5.0
See awusb.config.example for a sample configuration file.
Config File Discovery Examples
# Use default config from ~/.config/awusb/awusb.config
awusb list
# Use project-specific config from current directory
cd /path/to/project
echo "servers: [myserver]" > .awusb.config
awusb list
# Use environment variable (useful in CI/CD)
export AWUSB_CONFIG=/etc/awusb/production.config
awusb list
Connection Timeout
The timeout setting controls how long to wait when connecting to each server before giving up. This prevents the client from hanging when a server is unreachable. The default is 5 seconds, but you can adjust it based on your network conditions:
- Fast local network: Use a shorter timeout (e.g.,
2.0seconds) - Slow or remote servers: Use a longer timeout (e.g.,
10.0seconds)
When a server times out, it's logged as a warning and skipped, allowing other servers to be queried.
Behavior
- list: Without
--host, queries all configured servers and displays devices grouped by server - attach/detach: Without
--host, scans all servers to find a matching device- Fails if no match is found across all servers
- Fails if multiple matches are found across different servers (unless
--firstis used) - Succeeds if exactly one match is found (reports which server it was found on)
- With
--firstflag: Attaches the first matching device found, even if multiple servers have matching devices
- --host flag: When specified, only queries that specific server (ignores config file)
Examples
# List devices on all configured servers
awusb list
# List devices on a specific server
awusb list --host raspberrypi
# Attach a device (scans all servers, fails if multiple matches)
awusb attach --desc "Camera"
# Attach first matching device across servers
awusb attach --desc "Camera" --first
# Attach a device from a specific server
awusb attach --desc "Camera" --host 192.168.1.100
# Detach with first match (if same device attached from multiple servers)
awusb detach --desc "Camera" --first
Installing as a Service
You can install the awusb server as a systemd service to run automatically at boot.
System Service (Recommended)
Install as a system service (runs at boot, before login):
# Install as system service (requires sudo)
sudo awusb install-service --system
# Enable and start
sudo systemctl enable awusb.service
sudo systemctl start awusb.service
# Check status
sudo systemctl status awusb.service
User Service (Not Recommended)
Install as a user service (runs when you log in) useful for testing if you don't have sudo access:
# Install the service
awusb install-service
# Enable it to start on login
systemctl --user enable awusb.service
# Start the service now
systemctl --user start awusb.service
# Check status
systemctl --user status awusb.service
# View logs
journalctl --user -u awusb.service -f
Uninstalling
# Uninstall user service
awusb uninstall-service
# Uninstall system service (requires sudo)
sudo awusb uninstall-service --system
Metadata
Release files for awusb 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| awusb-1.0.0.tar.gz | 99.4 kB | Without provenance | Details for awusb-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| awusb-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for awusb-1.0.0-py3-none-any.whl |
Total release size: 124.6 kB
Release files / awusb-1.0.0.tar.gz
| Download URL | awusb-1.0.0.tar.gz |
|---|---|
| Size | 99.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a6e8abf7bf323da7618d95ed6590157c47478a9cb96fffe19b0fdf058685581e
|
|
BLAKE2b-256 checksum How to use checksums |
5cd7287283efab4a3492d85e942b4fc8014e3b25942b00f5350a3485096dcfa0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Release files / awusb-1.0.0-py3-none-any.whl
| Download URL | awusb-1.0.0-py3-none-any.whl |
|---|---|
| Size | 25.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f223364891340f4e3d87d6b5530953057234ac0087fc3f1dd7c3ae0ce804c6f6
|
|
BLAKE2b-256 checksum How to use checksums |
8ebef69c45bee4faffbc856511b5a6aa583e03ed92b4eb61eeace55640249afd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Security for awusb 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.