Troubleshooting

If the server will not start, first confirm that the remoterf-server environment is activated and that the configured ports are valid and not OS-reserved.

On the server, open a new terminal and run:

conda activate remoterf-server
serverrf --serve

When the server appears healthy locally but clients or hosts cannot reach it, test connectivity directly with nc.

On the server, open a new terminal and run:

nc -vz 164.67.195.210 61005
nc -vz 164.67.195.210 61006

Then, repeat the same test from a second machine on the same network as the server.

If local tests work but remote tests fail, then check:

• Host firewall rules
• Campus network restrictions
• ISP or upstream firewall rules
• Whether the expected ports actually match the configured server ports

A host only appears in the server shell after hostrf --serve connects to the server, authenticates with its host token, announces its device inventory, and keeps the heartbeat stream alive.

On the host, verify the saved config:

hostrf --config --show
hostrf --host --show
hostrf --device --show

• hostrf --config --show should show REMOTERF_ADDR pointing at the server main gRPC port.
• hostrf --host --show should show the expected HOST_ID and a redacted HOST_TOKEN.
• hostrf --device --show can be empty, but if this host owns devices, they should be listed with the expected global IDs and serials.

Then start the host:

hostrf --serve

In the serverrf --serve shell, inspect the live tunnel:

hosts status
devices list
devices status

If the host repeatedly says it is unable to connect, re-check network reachability to the server. If the server rejects the host, recreate or rotate the host token on the server and save the returned token on the host.

# On the server:
serverrf --host --token-create lab-host-01 --length 8 --force

# On the host:
hostrf --host --set lab-host-01 "TOKEN_FROM_SERVER"
hostrf --config --addr <server_host>:<main_port>

When a host is online but its SDRs do not appear on the server, the host either did not load its local device inventory or the server rejected the announced device IDs.

On the host, confirm local USB access and inventory:

iio_info -s
hostrf --device --show
hostrf --serve

On the server, confirm the live route:

hosts status
devices list
devices status

• For host-attached hardware, the inventory file is ~/.config/remoterf/host/devices.yml.
• Each device_id must be globally unique across the main server and every host. A conflict causes the host inventory to be rejected.
• For the packaged Pluto driver, hostrf --device --add --pluto writes device_type: adalm_pluto. If you edit YAML manually, use the type string registered by the driver.
• After changing host network, token, driver, or device config, stop and restart hostrf --serve.

To move a host Pluto to a different global ID:

hostrf --device --remove <old_id>
hostrf --device --add --pluto <new_id>:<device_name>:<hw_serial>
hostrf --device --show

A Pluto SDR must be visible to the machine it is physically attached to before RemoteRF can load it. Start with the dependency and USB checks on that server or host.

If the IIO tools or Python driver are missing, install them:

conda install -y -c conda-forge libiio pylibiio libusb
sudo apt install -y libiio-utils
python -m pip install pyadi-iio

Then check whether the Pluto appears without elevated privileges:

iio_info -s
sudo iio_info -s

If it only appears under sudo, review the plugdev group membership and udev rules:

sudo groupadd -f plugdev
sudo usermod -aG plugdev "$USER"

sudo tee /etc/udev/rules.d/53-adi-usb.rules >/dev/null <<'EOF'
SUBSYSTEM=="usb", ATTR{idVendor}=="0456", MODE="0660", GROUP="plugdev"
EOF

sudo udevadm control --reload-rules
sudo udevadm trigger

If iio_info -s works but RemoteRF does not list the device as online, check the inventory file on the machine that owns the hardware.

• Server-attached devices are configured in ~/.config/remoterf/devices.yml.
• Host-attached devices are configured in ~/.config/remoterf/host/devices.yml.
• Custom schema files are loaded from ~/.config/remoterf/drivers/, not from the host/ subdirectory.

Check for the common config mistakes:

• device_id is a unique integer across the whole deployment.
• device_type matches the registered driver type. The packaged Pluto schema currently registers adalm_pluto.
• init.serial matches the serial or hardware ID reported by iio_info -s.
• The RemoteRF process was restarted after the YAML or driver file changed.

For host-attached Pluto devices, prefer the CLI so the YAML is written in the current schema:

hostrf --device --add --pluto <device_id>:<device_name>:<hw_serial>
hostrf --device --show
hostrf --serve

For server-attached devices, restart the server:

serverrf --serve

Then inspect runtime status in the server shell:

devices list
devices status

If the server lists a device but a client cannot reserve or initialize it, distinguish device availability from user access and reservation state.

In the server shell, inspect all three layers:

devices list
devices status
hosts status
reservations list
groups list

• If devices status shows the host route as offline, restart the owning hostrf --serve process and recheck hosts status.
• If the device is online but unavailable, check reservations list for an active reservation.
• If only certain students are blocked, check groups list and confirm their group can access the target device ID.
• If the client reports no schema for the token, the token is invalid, the device is offline, or the matching driver schema is not loaded.

If users cannot create accounts or access SDRs, inspect the access-control side of the system:

• groups list to confirm the expected group exists
• codes list to confirm enrollment codes exist and are still valid
• users list to confirm student accounts were created
• groups edit if the device whitelist or reservation policy is wrong

possible causes:

• The user enrolled into the wrong user group somehow.
• The user group does not include the target device ID.
• The enrollment code expired or has been used too many times.