Onboarding Students

Students install and run the RemoteRF client (remoterf) on their own laptops (Windows, macOS, or Linux) with Python 3.10+. This page covers the exact information you need to give your students, a quick pre-release check to run before posting your first lab, and copy-ready templates for your student handout and assignment starter code.

What Students Need

To onboard students at the start of the term, include the following items in your Lab 0 handout or course page alongside a link to the Student User Guide:

  1. Enrollment Code (or Standalone Server Address):
    • RemoteRF Global (default): Give each student their enrollment invite (for example, ucla/EE132B or a single-use code ucla/<CODE>) to enter with enroll after registering via remoterf -r. No server IP or VPN configuration is needed.
    • Standalone Local Server: If your deployment is not registered on RemoteRF Global, provide your campus Wi-Fi or VPN instructions, the server address command (remoterf -c -a <server-ip>:<main-port>), and the enrollment code for remoterf -r --local-only.
  2. Device Handles & Starter Script: Which device handles (Pluto_00@ucla, Pluto_09_Loopback@ucla, etc.) are wired in cabled loopback vs. over-the-air, along with the Python driver import for your radios.

Pre-Release Verification

Before announcing RemoteRF to your class, we strongly recommend walking through the student experience once from a personal laptop (testing from the server machine itself does not verify external network reachability):

  1. Create a clean Python environment: Create a fresh Conda or venv environment with Python 3.10+ and run pip install remoterf numpy matplotlib.
  2. Register & enroll a test student account: Run remoterf -r to create a RemoteRF Global account and enroll <deployment>/<code> inside remoterf --login (or run remoterf -c -a <ip:port> and remoterf -r --local-only for a standalone local server).
  3. Check device visibility & slot durations: Run getdev and resdev in remoterf --login (and perms if connected to a local server) to confirm the test student sees the expected radios and slot durations.
  4. Reserve & capture in Python: Reserve a radio with resdev, pass the device handle (e.g., token="Pluto_00@ucla") or issued reservation token into your Lab 1 starter script, and verify IQ samples return cleanly.
  5. Release the test reservation: Run cancelres to free the slot before releasing the handout to your students.

Student Handout Template

Copy and paste the template below into your course website, email, or Lab 0 handout after replacing <deployment>/<your-enrollment-code>:

Getting Started with RemoteRF for [Course Number]
=================================================

1. Create and activate a Python 3.10+ environment:
   conda create -n remoterf python=3.10 numpy scipy matplotlib
   conda activate remoterf

2. Install the RemoteRF client package:
   python -m pip install -U pip remoterf

3. Create your account and enroll in the course (first time only):
   remoterf -r
   - Agree to the Terms of Service, enter your username, password, and email,
     and enter the 6-digit verification code sent to your email.
   - Enroll with your assigned course code:
     enroll <deployment>/<your-enrollment-code>

4. Log in and reserve a radio time slot:
   remoterf --login
   - Type 'getdev' to see available course SDRs
   - Type 'resdev' to reserve a 30-minute slot
   - Type 'myres' to view active reservations or 'cancelres' when done early

5. Connect to your reserved radio in Python (using its handle or token):
   from remoterf.drivers.adalm_pluto import adi
   sdr = adi.Pluto(token="Pluto_00@ucla")

6. Run your Python script from a second terminal window:
   conda activate remoterf
   python lab1.py

Full Student User Guide & Device API Reference:
https://www.remoterf.net/docs/client/

Assignment Starter Code Patterns

When distributing starter Python scripts or Jupyter notebooks to students, include sdr.tx_destroy_buffer() and sdr.rx_destroy_buffer() at the end of the script so that cyclic transmissions (sdr.tx_cyclic_buffer = True) stop cleanly when the experiment finishes.

Single-SDR Starter Template (Loopback or Single-Radio OTA)

import numpy as np
from remoterf.drivers.adalm_pluto import adi

# Device handle (while logged in with `remoterf --login`) or reservation token
TOKEN = "Pluto_00@ucla"
sdr = adi.Pluto(token=TOKEN)

# Configure RF parameters
sdr.sample_rate = int(1e6)
sdr.tx_lo = int(915e6)
sdr.rx_lo = int(915e6)
sdr.tx_hardwaregain_chan0 = -10
sdr.gain_control_mode_chan0 = "manual"
sdr.rx_hardwaregain_chan0 = 20.0
sdr.rx_buffer_size = 4096

# Scale complex baseband waveform to Pluto DAC range [-2^14, +2^14]
tx_waveform_scaled = tx_waveform / np.max(np.abs(tx_waveform)) * (2**14)
sdr.tx_cyclic_buffer = True
sdr.tx(tx_waveform_scaled)

# Capture received IQ samples (returned as a complex NumPy array)
rx_samples = sdr.rx()

# Halt transmission and clear buffers when finished
sdr.tx_destroy_buffer()
sdr.rx_destroy_buffer()

Dual-SDR Starter Template (Cross-Device TX → RX)

For labs where students transmit from one SDR and receive on a second SDR (such as observing Carrier Frequency Offset or implementing timing/frequency synchronization), students reserve two SDRs concurrently and instantiate two adi.Pluto objects with their respective handles or tokens:

from remoterf.drivers.adalm_pluto import adi

sdr_tx = adi.Pluto(token="Pluto_00@ucla")
sdr_rx = adi.Pluto(token="Pluto_01@ucla")

# Configure sdr_tx and sdr_rx, transmit on sdr_tx, and capture on sdr_rx
...

sdr_tx.tx_destroy_buffer()
sdr_tx.rx_destroy_buffer()
sdr_rx.tx_destroy_buffer()
sdr_rx.rx_destroy_buffer()

Next Steps