Skip to main content

USB/IP server

In the USB/IP role, the board shares the device on its USB host port over USB/IP on TCP port 3240. A Linux or Windows host attaches it, and the host's own drivers take it from there, as if the device were plugged in locally. Use it for a Z-Wave or Zigbee stick mounted where the radio works best, a license dongle, a programmer, or a HID device.

Set up the board​

  1. Choose USB/IP server under Settings and Save & reboot.
  2. Plug the device into the board's USB host port. The USB/IP panel shows its name, ID, speed and interfaces.
  3. Tick Enabled: accept USB/IP clients on TCP 3240.
  4. Fill in Allowed clients (blank: anyone) with the hosts that may attach it, such as 192.168.1.0/24 10.0.0.5.
  5. Choose Save. Changes apply at once.
No password or encryption

USB/IP has no password or encryption, and the admin password doesn't cover it. Anyone allowed to connect can take the device while it is free. Use the allow list.

One host has the device at a time. While a host has it, the panel shows it under Attached to, with the traffic, and the device isn't offered to anyone else. Detach client drops the host's connection.

In the examples below, replace <board> with the board's address, such as etherjax-ab12.local or its IP address.

Set up a Linux host​

On Ubuntu or Debian, the board serves a setup script:

curl -fsSL http://<board>/usbip.sh | sudo bash

It:

  • installs the usbip tools if needed (Ubuntu's linux-tools for the running kernel, or Debian's usbip)
  • loads the vhci-hcd kernel module at boot
  • attaches the device and prints its /dev/serial/by-id/... names
  • adds a service, etherjax-usbip-<board>, that keeps the device attached

The service re-attaches after a network drop or a reboot of either end. It also notices a dead connection, which Linux alone may not for hours, and reconnects. It reaches the board as <board>.local if that resolves, and by IP address otherwise.

To undo the setup:

curl -fsSL http://<board>/usbip.sh | sudo bash -s -- --remove

The script runs as root and comes over plain HTTP, so use it only on a network you trust. Read it first at http://<board>/usbip.sh.

Attach by hand​

sudo modprobe vhci-hcd
usbip list -r <board>
sudo usbip attach -r <board> -b 1-1
sudo usbip port                    # and: sudo usbip detach -p 00

Set up a Windows host​

On Windows 10 (1903 or later) or 11, in PowerShell as administrator:

irm http://<board>/usbip.ps1 | iex

It installs usbip-win2 if needed (the latest release, silently; it checks the installer's signature, and the drivers are Microsoft-signed). Installing restarts USB 3 hubs, so other USB devices drop out for a moment. It then attaches the device and adds a scheduled task, etherjax-usbip-<board>, which runs as SYSTEM from startup and keeps the device attached the same way as on Linux. Its log is in %ProgramData%\etherjax.

To undo the setup (usbip-win2 stays installed):

iex "& { $(irm http://<board>/usbip.ps1) } -Remove"

A serial device may still need its vendor's Windows driver. The Windows script has not been tested on hardware yet.

Attach by hand​

Install usbip-win2, then as administrator:

usbip.exe attach -r <board> -b 1-1

Or use the usbip-win2 GUI. (usbipd-win works in the other direction, sharing a Windows PC's own devices, and doesn't help here.)

Detach​

Detach client drops the connection, but a host set up with the script takes the device back within 10 seconds. To free the device for good, undo the setup on that host.

What works​

  • Control, bulk and interrupt transfers go to the device as sent, several in flight per endpoint.
  • Isochronous transfers are passed through, but haven't been tested.
  • Only the configuration the board enumerated the device with can be used: switching would mean re-enumerating, so devices that need a second configuration don't work. Port resets are acknowledged but not done.
  • A transfer can be at most 127 packets (8 KB for a full-speed bulk endpoint, 63.5 KB for a high-speed one). Drivers that send bigger ones, such as USB mass storage, get errors.
  • One device, and no hubs.

Serial devices: USB/IP or serial server?​

For a serial device such as a Z-Wave stick, there is a choice:

  • The serial server role gives the port as a TCP socket, which Z-Wave JS can open as tcp://host:9000, with no driver on the host.
  • USB/IP gives the host a real /dev/ttyUSB*, including both radios on a dual stick such as the Nortek HUSBZB-1.