Onboarding Users

Overview

This page is intended for a RemoteRF administrator, i.e., class instructor or research lab administrator. It is not meant to replace the full User Guide. Rather, it is meant to describe exactly what is needed from the administrator to successfully onboard users to a newly deployed RemoteRF server.

A user can install and use the RemoteRF client software on any computer with:

• Windows, macOS, or Linux
• access to the same network as the RemoteRF server
• an installation of Python 3.10+.

Admin Prerequisites

User Environment

Users will connect to the RemoteRF server and reserve its SDRs via their personal computers. They will also use their personal computers to write and run Python scripts that interface with the SDRs.

Users must have Python 3.10+ installed. We recommend using conda to create a new dedicated environment for their RemoteRF client installation.

Assuming they have conda installed, creating a remoterf environment and installing the RemoteRF client can be accomplished via the following.

conda create -n remoterf python
conda activate remoterf
python -m pip install -U pip
python -m pip install remoterf numpy matplotlib

Since most users will also want numpy and matplotlib installed, we have included them above, but they can be excluded if desired.

Users who do not use conda can install the same packages in any supported Python 3 environment. The key point is that remoterf --login and the Python script they run later must use the same environment where remoterf was installed.

Connection Details

Every user must configure the RemoteRF package with the IP address of your deployment. As the administrator, provide the exact command with real values filled in:

remoterf -c -a <server-ip>:<main-port>

For example, if the IP address is 192.168.1.50 and the port is 61005, then the network configuration would be as follows.

remoterf -c -a 192.168.1.50:61005

In order to run the above command, users must be on the same network as the RemoteRF server. For university deployments, this means they must be on the campus Wi-Fi, LAN, or VPN.

Note that you should not give users the certificate port for this command. For example, if the server was configured with main port 61005 and certificate port 61006, the user should use 61005.

Account Access

After installing the RemoteRF client on their personal machines, the next step is for users to create an account. To do so, they will need an enrollment code, which should be provided to them by the RemoteRF administrator. These enrollment codes are created on the server and tied to a particular user group, so that, upon account creation, the user is automatically added to a specific user group. This user group determines the user’s particular permissions, such as which devices they may access, how many reservations they may hold, and the duration of their reservations.

To begin creating an account, users should run the following in their terminal.

remoterf --login

Users should then input r to register the first time. To make an account, they will need to provide the following:

• enrollment code
• username
• password
• email address

After registration, users run remoterf --login and choose l to log in.

As the administrator, it is important to keep track of which enrollment code or set of codes belongs to which class, lab, or research group, so that they can be distributed appropriately. Emails are not currently used for any functional purpose. If a user forgets their password, you may need to issue a new enrollment code so they can create a new account.

After users can register and log in, they still need to confirm that they can see the expected devices, make a reservation, and use the reservation token in Python. The remaining sections cover those final onboarding checks and provide a short handout template you can give to users.

Reserving and Using SDRs

After logging in, users usually reserve a device from the interactive RemoteRF user workflow:

The important output from resdev is the reservation API token. That API token is what the user’s Python code passes into the remote device constructor. API tokens are tied to the user, device, and reservation time. They should be copied carefully because the server does not recover or reprint a lost token.

For a Pluto SDR, the admin-facing concept is:

from remoteRF.drivers.pluto import *

sdr = adi.Pluto(token="reservation-token")

That constructor call is what you should show in assignment starter code or lab notebooks. Replace "reservation-token" with a placeholder that tells users to paste the token they received from resdev.

For a custom schema-backed device, the import path follows the device type in devices.yml. For example, device_type: custom_sdr becomes:

from remoteRF.drivers import ensure_driver

TOKEN = "reservation-token"
ensure_driver(token=TOKEN)

from remoteRF.drivers.dummy_sdr import *

dev = adi.custom_sdr(TOKEN)

TODO: WHAT IF IT’S NOT ADI

In other words, the server schema and device_type determine what generated driver path users import. Users do not manually copy server-side schema files. They install remoterf, configure the server IP address, reserve a device, and let RemoteRF fetch or refresh the generated user wrapper from the server.

Verification

Handout Template

Below is a compact user-facing template you can paste into a course page, email, or handout after replacing the placeholders.

Here are the key steps to setting up RemoteRF.

1. Connect to the required network:
   Wi-Fi / LAN / VPN 

2. Create and activate a Python environment:
   conda create -n remoterf python
   conda activate remoterf

3. Install RemoteRF:
   python -m pip install -U pip
   python -m pip install remoterf numpy matplotlib

4. Point RemoteRF at our server:
   remoterf -c -a <server-ip>:<main-port>

5. Create your account:
   remoterf --login
   Choose r to register.
   Enrollment code: <enrollment-code>

6. Log in and reserve a device:
   remoterf --login
   getdev
   resdev

7. Insert your reservation token into Python:
   from remoteRF.drivers.adalm_pluto import *
   sdr = adi.Pluto(token="paste-your-token-here")

8. Run your Python script in the remoterf environment from a new terminal:
   *open a new terminal window*
   conda activate remoterf
   python my_script.py

For more information on getting started, please refer to this page: 
<insert-link-here>

For the full user-facing walkthrough, refer users to the User Guide.

Next Steps

With the user onboarding process understood, the next step is to walk through server management, which covers creating user groups, generating enrollment codes, setting reservation limits, and more.