usbip-autobind

usbip-autobind is a Python script designed to automatically bind all attached USB devices to the usbip driver, making it easy to share USB devices over IP. I use this to so I can use the same periferals for multiple devices without repluging cables every time i switch. Instead I just have one USB hub connected to a raspberry pi hosting this and i have the client on all my other devices.

I originally used https://github.com/mozram/usbip-autobind but i wanted more functionality so i expanded it.

---

Features

• Automatic USB Device Binding: Detects all attached USB devices and binds them to the usbip driver.
• Perfect for multiple clients: The host can handle as many clients as you want and assign any USB device to any client.
• Easy Integration: Simple to run, no complicated setup required (except you consider creating services to run in the background complicated)
• Cross-Platform: Tested on host on Raspbian and client on Arch and Windows 11.
• Verbose Logging: Provides detailed output for troubleshooting and monitoring.
• Web UI: Provides a webui to configure which client gets which USB device.
• API: Provides an API to do the same stuff as the webui if you want to automate stuff.
• Whitelist: Only touches USB ports you allowed it to use.
• Stable: Automatic freeing of drivers if something fails or connection retries etc ensure the your usb connections stay attached.
• Persistent State: The host memorizes which USB devices were assigned to which client even between reboots and automatically attaches them again.

---

Requirements (Server Side)

• Linux (tested on Raspbian and Arch)
• Python 3.10+ (may work with previous versions but untested)
• pip (Python package manager)
• systemd (for running services, optional if you dont want to run it as a service or know how to do it without systemd)
• Root privileges (binding devices typically requires administrative access)

Requirements (Client Side)

• Linux or Windows (tested on Arch and Windows 11)
• Python 3.10+ (may work with previous versions but untested)
• pip (Python package manager)
• Root privileges (binding devices typically requires administrative access)

---

Installation (Server Side)

Automatic (Recommended)

You can use the provided install script to set up everything automatically, including installing usbip, enabling kernel modules, creating required services, and running the server with uvx.

Just run this one-liner (it will fetch the latest install script from GitHub and execute it):

curl -fsSL https://raw.githubusercontent.com/virus-rpi/usbip-autobind/master/install_usbip_autobind_server.sh | bash

The script will prompt you for configuration options (socket host/port, web host/port, physical ports whitelist, assignments file path) and set up a systemd service that runs the server with uvx. The service will always use your chosen settings and ensure usbipd is running.

---

Manual (Advanced)

1. Install usbip and uvx:

   sudo apt install usbip
   # or for other distros:
   # sudo dnf install usbip
   # sudo pacman -Sy usbip
   
   # Install uvx if not already installed
   pip3 install uvx
   # or
   pip install uvx

2. Enable kernel modules:

   sudo modprobe usbip-core usbip-host

3. Create and enable the usbipd service: Create the file /etc/systemd/system/usbipd.service with:

   [Unit]
   Description=usbip host daemon
   After=network.target
   
   [Service]
   Type=forking
   ExecStart=/usr/sbin/usbipd -D
   
   [Install]
   WantedBy=multi-user.target

   Then run:

   sudo systemctl daemon-reload
   sudo systemctl enable usbipd
   sudo systemctl start usbipd

4. Run the server with uvx: You can run the server directly with uvx, specifying your configuration options:

   sudo uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-server \
     --socket-host 0.0.0.0 --socket-port 65432 \
     --web-host 0.0.0.0 --web-port 8080 \
     --physical-ports 1-1,1-2,2-1,2-2 \
     --assignments-file /var/lib/usbip-autobind/assignments.json

   Example whitelist: 1-1,1-2,2-1,2-2 (these are bus IDs for USB ports; use usbip list -l to find yours).

5. (Optional instead of step 4) Create a systemd service for the server: Create /etc/systemd/system/usbip-autobind.service with:

   [Unit]
   Description=usbip-autobind server
   After=network.target usbipd.service
   Requires=usbipd.service
   
   [Service]
   Type=simple
   ExecStart=uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-server --socket-host 0.0.0.0 --socket-port 65432 --web-host 0.0.0.0 --web-port 8080 --physical-ports <comma-separated-whitelist> --assignments-file /var/lib/usbip-autobind/assignments.json
   Restart=always
   RestartSec=10s
   
   [Install]
   WantedBy=multi-user.target

   Then run:

   sudo systemctl daemon-reload
   sudo systemctl enable usbip-autobind
   sudo systemctl start usbip-autobind

---

Installation (Client Side)

Linux

1. Install usbip:

sudo apt install usbip

2. Enable kernel modules:

sudo modprobe usbip-core usbip-host

3. Run the client using uvx:

uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip> [other options]

Replace <server-ip> with the IP address of your server. You can pass additional options as needed.

4. (Optional but recommended) Add a service to start the client automatically:

Create the file /etc/systemd/system/usbip-autoattach.service with the following content:

[Unit]
Description=USBIP Client Service
After=network-online.target

[Service]
ExecStart=/usr/bin/uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip> [other options]
Restart=always
RestartSec=10s

[Install]
WantedBy=multi-user.target

Replace <server-ip> and add any other options you need. Also make sure the path to uvx is correct (you can find it with which uvx).

Then run:

sudo systemctl daemon-reload
sudo systemctl enable usbip-autoattach
sudo systemctl start usbip-autoattach

Alternatively, you can run the client directly with sudo uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip>.

Windows

1. Install usbip: Follow the instructions in the readme of https://github.com/vadimgrn/usbip-win2

2. Run the client using uvx: Download uvx for Windows from https://github.com/virus-rpi/uvx/releases and place it somewhere accessible.

   Example command:

   uvx.exe --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip> [other options]

   Replace <server-ip> with the IP address of your server.

3. (Optional but recommended) Add a service to start the client automatically: The easiest way to add a service on Windows is with nssm. (to install nssm do winget install nssm)

   Create a .bat file containing:

   @echo off
   "C:\path\to\uvx.exe" --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip> [other options]

   Place it at a location accessible for services, e.g., C:\usbip\start-client.bat.

   Then start cmd or powershell as admin and run:

   nssm install USBIP-AutoAttach

   In the GUI, select the .bat file you created as the path. Optionally configure a log.txt file in the I/O tab if you want to keep logs. Configure other options as desired, then click "Install".

   After that run:

   nssm enable USBIP-AutoAttach
   nssm start USBIP-AutoAttach

   Alternatively, you can run the client directly with uvx.exe --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --socket-host <server-ip> in an admin shell.

---

Available options for the client:

• --socket-host: The server IP or hostname to connect to (default: chikaraNeko.fritz.box)
• --socket-port: The server port to connect to (default: 65432)
• --reconnect-delay: Seconds to wait before reconnecting if the connection drops (default: 5)
• --client-id: The client identifier (default: your computer's hostname, lowercased)

You can see all available options and their descriptions by running:

uvx --from git+https://github.com/virus-rpi/usbip-autobind@master usbip-client --help

Usage

• The server script automatically detects all connected USB devices and binds them to the usbip driver.

• The client connects to the server and manages device attachments as assigned.

• Visit the web UI (default: port 8080 on the server) for full control:

  • Device Management:
    • View all USB devices, their names, bus IDs, assignment status, and usage.
    • Assign any device to a client, reassign to another client, unassign, force free, or reattach.
    • Assign all devices to a client, assign all to another client, or unassign all devices at once.
    • Refresh device list at any time.
  • Client Management:
    • View all connected clients in a dedicated section.
  • Debug Panel:
    • View live debug information (internal state) in a collapsible panel.
    • Refresh debug info on demand.
  • Dark Mode Toggle:
    • Easily switch between dark and light mode.
  • Live Updates:
    • UI auto-refreshes when device/client state changes.

• If a client goes offline and comes back later, it will automatically reconnect to its assigned devices as long as they are free.

• You can also use the API endpoints for automation and troubleshooting (see below).

API Endpoints

The server exposes the following API endpoints for device and client management:

• GET /devices — List all USB devices, their bus IDs, assigned clients, usage status, and names.
• GET /devices/{bus_id} — Get details for a specific device.
• POST /devices/{bus_id}/assign — Assign a device to a client. Body: { "client_id": ... }
• POST /devices/{bus_id}/force_free — Force free a device (detach from client).
• POST /devices/{bus_id}/force_reattach — Force reattach a device to its assigned client.
• POST /assign_all — Assign all devices to a client or clear all assignments. Body: { "client_id": ... }
• GET /clients — List all connected clients.
• GET /debug — Get debug information (internal state).

You can use these endpoints to automate device assignment, management, and troubleshooting.

---

How It Works

1. Device Detection:
   The script gets the connected devices at script start and after that watches the USB ports via a udev observer.

2. Binding Process:
   For each detected device, it attempts to bind the device interface to the usbip driver using usbip commands.

3. Attaching:
   To attach a device the host sends a command to the client to bind a specific device over a socket connection. If you change to which client a device should be attached it sends a command to the old client to detach and an attach command to the new client.

---

Troubleshooting

• Permission Errors:
  Ensure you are running the script with root privileges.

• usbip Not Found:
  Make sure usbip is installed and available in your system's PATH.

• The USB device doesn't show up in the list: Make sure the port you plugged it in is on the whitelist.

• A lot of different errors can occur on linux if you dont properly install the kernel modules. Make sure you execute modprobe usbip-core usbip-host

• For connection issues check the host ip in the client script and check if a firewall is blocking something

• If your system does not use systemd you're a nerdy enough to figure out how to do services yourself

---

Contributing

Pull requests and issues are welcome!
If you find a bug or have a feature request, please open an issue in this repository.

---

License

This project is licensed under the MIT License.

---

Author

Developed and maintained by virus-rpi.