Commissioning a new Raspberry Pi as a usb-remote Server#

Introduction#

Choosing the recommended hardware for a usb-remote server simplifies commissioning as there is a pre-built disk image available that includes all necessary software and configuration.

Step 1: Obtain and Assemble Recommended Hardware#

See Recommended Server Hardware.

Any Raspberry Pi 4 or 5 with at least 4GB RAM and at least 16GB microSD card is suitable.

Step 2: Flash the Raspberry Pi usb-remote Server Image#

If you do not already have a pre-configured Raspberry Pi usb-remote server image, follow these steps to flash the image to a microSD card.

Download raspi-lite-usb-remote-2.2.2.img on Google Drive

Note: this image works for both Raspberry Pi 4 and Raspberry Pi 5.
TODO: make a separate image for DLS with different user/password and create a central supply of duplicates.

Insert a microSD card of at least 16GB capacity into a card reader connected to your computer.
Use lsblk to identify the device name of the microSD card (e.g. /dev/sdb).
Flash the image to a microSD card as follows. CAREFUL - replace /dev/sdX with the correct device name for your microSD card and remember that this will overwrite the specified device.
```
sudo dd if=./raspi-lite-usb-remote-2.1.0.img of=/dev/sdX bs=4M status=progress conv=fsync
```

Step 3: Extract the Raspberry Pi MAC Address#

If you have a Pico with screen then plug it into the Raspberry Pi USB port and power on the Pi. The MAC address will be displayed on the screen within a minute.
Otherwise you will need to boot the Raspberry Pi and get the MAC address from the command line.
```
ip link show eth0
```

Step 4: Configure an IP Address for the Raspberry Pi#

Launch infoblox (or other DHCP management tool) and create a new DHCP reservation for the Raspberry Pi MAC address obtained in Step 3.
At DLS the IP address should be:
- 10.x.20.1 for pi1
- 10.x.20.2 for pi2
- etc.

Step 5: Connect the Raspberry Pi to the Network and Power it On#

Connect the Raspberry Pi to the network using a wired ethernet connection.
Power on the Raspberry Pi using the USB-C power supply.
Wait a few minutes as the Pi will reboot twice to expand the root filesystem and set up read-only filesystem mode.

Step 6: Verify the New Server is Visible to the usb-remote Client#

On any linux machine that can route to the new Raspberry Pi server IP, run:

uvx usb-remote config add-server <raspberry_pi_ip_address>
uvx usb-remote list

You should see the new server listed without errors.

Troubleshooting#

If the new server shows errors when the client tries to list devices, try the following:

ssh local@<raspberry_pi_ip_address>
# password is "local"

# check the status of the two services
sudo systemctl status usbipd
sudo systemctl status usb-remote

# check their logs for errors
journalctl -u usbipd -e
journalctl -u usb-remote -e