Installation guide (Raspberry Pi, or a Debian PC)

Four ways to the same result:

• Route A: the ready-made image (easiest). You write one image to the SD card and answer a few questions in Raspberry Pi Imager.
• Route B: the installer pack on top of the official Raspberry Pi OS. Everything is in one folder, including the Python libraries.
• Route C: from the source code (advanced).
• Route D: a Debian 12 or 13 PC instead of a Pi (see section 4b).

Download the files from the latest release.

1. What you need

2. Route A: the ready-made image

The image is Raspberry Pi OS Lite (64-bit, Debian Trixie) with Radio Remote already installed. It contains no password: you set the user, password, hostname and Wi-Fi while writing the card.

1. Open Raspberry Pi Imager 2.x. In its application options choose Content Repository, enter a custom repository and paste: https://github.com/dev-jmatias/YaesuFT991A-Remote/releases/latest/download/os-list.json
2. Choose your Pi, then Radio Remote for Yaesu (Raspberry Pi OS Lite, 64-bit) in the OS list. (Do not use Use custom: that route shows no customisation screens.)
3. Choose the SD card and fill in Imager's screens: hostname (for example radio), your user name and password, Wi-Fi if you do not use a cable, the time zone, and keep SSH enabled. Write the card.
4. Put the card in the Pi, connect the radio, power on and wait about two minutes.
5. Open https://<hostname>.local and continue with section 5 (first run).

Root login stays disabled. The user you create has sudo, like on every Raspberry Pi OS.

If Imager has no Content Repository option (older versions), download image_…-radio-remote.img.xz and first-boot-settings.ps1 from the release, write the image with Choose OS > Use custom (do not unzip it), take the card out and put it back in the PC so the small bootfs volume shows up (before the card has ever booted), then run in PowerShell 7: pwsh -ExecutionPolicy Bypass -File first-boot-settings.ps1. It asks for hostname, user, password and Wi-Fi. More: image/README.md.

3. Route B: the installer pack on Raspberry Pi OS

1. In Raspberry Pi Imager choose Raspberry Pi OS (other) > Raspberry Pi OS Lite (64-bit) (Bookworm or newer: Python 3.11 or newer is needed; Lite avoids PipeWire/PulseAudio grabbing the radio's sound card). In the customisation screens set a hostname, a user and password, Wi-Fi if needed, and enable SSH. Write the card, boot the Pi and wait two minutes.
2. From your PC connect and update the system: bash ssh <user>@<hostname>.local sudo apt update && sudo apt full-upgrade -y && sudo reboot
3. Download radio-remote-installer-….zip from the release and unzip it on your PC. It is a folder (radio-remote-installer) with install-everything.sh, the radio-remote program, a wheels folder with the Python libraries for the Pi (nothing is compiled or fetched from PyPI) and the manual.
4. Copy the folder to the Pi. From a Windows PC (PowerShell, in the folder that holds radio-remote-installer): powershell scp -r radio-remote-installer <user>@<hostname>.local:~
5. On the Pi: bash cd ~/radio-remote-installer sudo bash install-everything.sh Useful options (all optional): --model ft991a (the default; others are in other radios), --hostname radio.local, --with-tailscale (installs Tailscale), --no-caddy, --dry-run (shows every step and changes nothing).
6. It prints the address to open. Continue with section 5.

What it does, in order: installs python3-venv alsa-utils libopus0 curl caddy and friends (needs internet), creates the service user radio-remote, installs the program under /opt/radio-remote, installs the Python libraries from the bundled wheels folder, writes /etc/radio-remote/config.toml (transmitting disabled, listening on the Pi only), installs the udev rule and the service, sets up HTTPS with Caddy (its own local certificate), and waits until the app answers. It never opens a firewall port, never enables transmitting and never talks to the radio.

4. Route C: from the source code

# on the Pi: unpack radio-remote-vX.Y.Z.tar.gz from the release (or clone the repository)
cd radio-remote
sudo bash install.sh --dry-run                    # prints every action, changes nothing
sudo bash install.sh --model ft991a               # real install (downloads the Python libraries; several minutes on a Pi)

Options: --model NAME, --hostname NAME, --no-caddy, --with-hamlib, --with-tailscale, --wheels DIR, --no-rade, --rade-file FILE, --force-arch. install.sh also installs the RADE library (the neural FreeDV mode) by itself; a failure there only prints a hint and the install carries on. Use bash install.sh (not ./install.sh) when the files came from a Windows PC: the executable flag is lost there. A git checkout does not contain the built manual; run python scripts/build_docs.py first if you want it on the Pi.

4b. Route D: a Debian PC (not a Raspberry Pi)

Radio Remote also runs on a normal 64-bit PC (an old laptop or a mini PC next to the radio) with Debian 12 ("bookworm") or Debian 13 ("trixie"). It uses the same installer as route C. This route has been prepared from the Pi installation and checked in test mode on Debian; a real install on a PC is new, so tell us what you meet.

What you need: a 64-bit PC (x86_64), a minimal / server Debian install (no desktop: a desktop's PipeWire or PulseAudio can grab the radio's USB sound card and block the audio), a wired network connection, internet access during the install, and the USB cable to the radio.

# 1. get the program: download radio-remote-vX.Y.Z.tar.gz from the release page (NOT the installer pack zip: its Python libraries are for the Pi)
tar xzf radio-remote-vX.Y.Z.tar.gz && cd radio-remote
# 2. install (the Python libraries are downloaded from PyPI; a few minutes)
sudo bash install.sh --model ft991a --hostname radio.local

Then continue with First run below. Things that differ from a Pi:

• Name on the network: the installer adds avahi-daemon (it announces the PC) and libnss-mdns (so the PC can look up .local names itself), so https://<hostname>.local works from phones and PCs that understand .local names. Important: the name announced on the network is the PC's own hostname. --hostname only sets the name the web server answers to, so the two must match: install with the default name, or with --hostname <the PC's hostname>.local, or rename the PC (sudo hostnamectl set-hostname NAME, then replace the old name by NAME in /etc/hosts, then sudo systemctl restart avahi-daemon). Using the PC's IP address in the browser does not work, because the web server answers only to its name.
• Python: Debian 12 has Python 3.11 and Debian 13 has 3.13; both are fine (3.11 or newer is needed).
• Audio: use plain ALSA. The program picks the radio's USB sound card ("USB Audio CODEC") by itself; on a desktop system that also runs PipeWire/PulseAudio, stop it for that card or use a server install. The service user is added to the audio and dialout groups by the installer.
• RADE (the neural FreeDV mode) is installed by install.sh itself: it downloads the library for your CPU from the release page and checks it (use --no-rade to skip it, --rade-file FILE for a local copy). If that step could not run (no internet, or your release has no file for your CPU), install it later from the web page (Admin > Config > RADE > Install RADE), as long as the release you run offers a library for your CPU (x86_64 and aarch64 are built). It needs nothing else installed. The library is built on Debian 12, so it works on Debian 12 and on Debian 13. Without internet, or if your release has no x86_64 file: download radio-remote-rade-linux-x86_64.tar.xz on another computer and run sudo /opt/radio-remote/current/scripts/install_rade.sh --file <file>, or build it yourself on the PC with sudo apt install git cmake build-essential autoconf automake libtool curl and bash scripts/build_rade.sh (about 5 minutes; it downloads the sources and model weights) and install the resulting librade-rr.so with install_rade.sh --file.
• Updates work the same way: the Update now button, or sudo /opt/radio-remote/current/scripts/self_update.sh.
• Firewall: if the PC runs ufw or nftables, allow TCP port 443 from your network (and 22 for SSH).

If the page does not open (Debian PC or any install)

• Check the server on the PC itself: systemctl is-active caddy radio-remote avahi-daemon (all active), then curl -k -sI --resolve NAME:443:127.0.0.1 https://NAME | head -1 (HTTP/2 200; NAME is the name from --hostname, e.g. radio.local).
• Is the name announced? hostname must be NAME without .local; avahi-resolve-host-name NAME should print the PC's address (sudo apt install avahi-utils if it is missing).
• Windows says "This site can't be reached": run ping NAME in PowerShell. If it answers from a different address than the PC's (the router keeps old records of names from earlier devices, for example an earlier Raspberry Pi called ft991a), Windows asks the router first and never finds the PC. Fix: use a name nobody has used, or tell that PC the address by hand: add PC-ADDRESS NAME to C:\Windows\System32\drivers\etc\hosts (Notepad as administrator), then ipconfig /flushdns. For good, give the PC a fixed address on the router (a DHCP reservation) and delete the old names from the router's list.
• Changing the name later: sudo python3 /opt/radio-remote/current/scripts/rr_admin.py render-caddy --host NEWNAME --out /tmp/Caddyfile.new, then sudo caddy validate --config /tmp/Caddyfile.new --adapter caddyfile, sudo install -m 0644 /tmp/Caddyfile.new /etc/caddy/Caddyfile, sudo systemctl reload caddy.
• Android phones often cannot resolve .local names at all; try a PC first.

5. First run (all routes)

1. Browse to https://<hostname>.local. Your browser warns about the certificate until you trust the Pi's local certificate once per device (security and remote access); listening works regardless, the microphone needs HTTPS.
2. The first visit asks you to create the administrator account: use your callsign as the user name and a password of at least 10 characters. Do this on your home network, not over a forwarded port.
3. Admin > Config: choose the radio model and the serial port (auto finds an FT-991A), Save, restart the service when asked.
4. Check the radio shows online and the frequency follows the VFO knob.
5. Set the radio's own menus for USB audio and CAT: radio connection (FT-991A: CAT rate, USB audio levels, mic source).
6. Transmitting is off. When you are ready (with a dummy load first), sign in as the administrator, open Admin > Config > Transmitting (PTT), choose Enable transmitting… and type your password again. It takes effect at once and is kept after a restart. (Alternatively edit /etc/radio-remote/config.toml, set allow_ptt = true under [safety], then sudo systemctl restart radio-remote.)

6. Remote access with Tailscale

Tailscale gives you a private way to the Pi from anywhere, with no router port opened.

1. Install Tailscale on the Pi (the installer option --with-tailscale, or follow tailscale.com/download) and sign in once: sudo tailscale up.
2. In the Tailscale admin console switch on MagicDNS and HTTPS Certificates.
3. Run sudo /opt/radio-remote/current/scripts/tailscale_setup.sh, then open the https://<pi>.<tailnet>.ts.net address it prints from any device that has Tailscale on. Details and troubleshooting: tailscale.

7. Updating, backup, removal

• Update: administrators are told in the web page when a newer release exists. Then run on the Pi sudo /opt/radio-remote/current/scripts/self_update.sh (downloads and verifies the new release, makes a backup, installs it). Without internet: copy the release's radio-remote-vX.Y.Z.tar.gz to the Pi, unpack it and run sudo ./update.sh in the folder. The old release is kept and the update rolls back by itself if the new one does not start. Details: operations.
• Backup: a daily backup of the settings and accounts runs automatically; Admin > Config > Settings backup downloads the settings as a file. See operations for backup, restore and the configuration file.
• Remove: sudo bash /opt/radio-remote/current/scripts/uninstall.sh (keeps configuration and backups) or --purge (deletes them too).

8. Manual install (without the installer)

sudo apt install python3 python3-venv alsa-utils libopus0
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cp config/radio-remote.example.toml config/radio-remote.toml      # edit model/port
PYTHONPATH=backend .venv/bin/python -m radio_remote --config config/radio-remote.toml

Then see packaging/ for the systemd unit and udev rule to adapt.

9. If something stops

The error message says what failed. The most common causes: no internet (apt cannot download), a 32-bit OS, or Python older than 3.11. Run sudo /opt/radio-remote/current/scripts/doctor.sh and see troubleshooting.

User guide

How to operate the radio from a phone, tablet or computer. For installing the system see the installation guide; for administering it (users, configuration, backups) see operations.

1. First visit

Open the address the installer printed (for example https://radio.local, or your Tailscale address) and sign in. The very first visit asks you to create the administrator account. The administrator then creates a user for everyone else under Admin > Users (roles below).

Tip: add the page to your phone's home screen ("Add to Home Screen" / "Install app") to get a full-screen app. The microphone only works over HTTPS (a secure address). Listening works either way.

2. Who is in control

Many people can watch at once, but only one controls the radio. The top bar shows your state:

• You have control + Release: you are in charge. Press Release when you are done.
• Name has control. You are watching + Request control: ask for it. The holder has 10 s to hand it over or keep it; if they do not answer, control passes to you. Trusted users (set by the admin) take control immediately. An admin can force control (Force), which also un-keys the transmitter.
• Nobody can take control while the radio is transmitting.

3. The screen

Phones and tablets/computers share the same layout idea: a radio panel on top, four tabs at the bottom: Radio, Filters, Audio & Levels and Digital (FreeDV, FT8/FT4 and SSTV, chosen with a switch: a slim row at the top of the tab on a phone, and in the bar beside the radio's name on a tablet or computer).

Top bar: Full (full screen), Help (this manual), Admin (administrators), Account (your password), Sign out, and for administrators Power off. Radio bar: a green dot = the radio answers, the radio name, and the control status. The Help button opens this manual from the Pi itself (no internet needed).

Radio tab

• VFO-A panel. Big frequency (tap a digit to make it the tuning step; on a computer the mouse wheel over a digit tunes by that digit), mode and band, the signal (S) meter, and below it the small power, SWR, ALC and COMP meters. ALC and COMP are shown as 0-100 %, red above 50 %. A TX badge appears while transmitting. Top right: the speaker and microphone switches (see Audio). Next to RX / TX / MEM, small status lights show the radio's receive path: one light for the preamp that names the setting in use (IPO, AMP1 or AMP2), ATT (attenuator), one light for the AGC that names its setting (AGC FAST, AGC MID, AGC SLOW or AGC AUTO; it is dark and reads AGC OFF when the AGC is off) and TUNER (antenna tuner). Green = active, dark = inactive; TUNER blinks amber while a tune runs. They only show what the radio reports (change the settings in Filters & DSP > Receiver and Transmit). On a phone they sit on a row of their own under VFO-A. A radio profile without one of these functions simply does not show that light. For a cleaner header, switch off the lights you do not need in Account > Display (this device only). Account > Look changes the colours of the whole app: Slate (the default), Yaesu (black body, white digits, blue labels, red mode badge, like the radio's own display) or FT-710 (near-black with amber digits). Lines sets how bright the borders around panels, tabs and buttons are (Soft, Normal or Bright). Both are remembered on that device only. SWR warning: while you transmit at or above the SWR limit (default 3:1, set by an administrator in Config > Meters, 0 = off) the SWR bar turns red and a line under the meters says High SWR: 3.4:1 - check the antenna and the cable; it stays for 5 seconds after the transmission. The FT-991A reports only a raw SWR value, so its ratio is an estimate ("about").
• VFO-B is the attached row under VFO-A: its mode, band and frequency. In split operation the transmit VFO gets the red TX badge. A purple MEM 005 badge means the radio is in memory mode.
• Tuning scale. Swipe or drag sideways (a quick flick keeps gliding). The numbers on the scale follow the tuning step; x10 makes every move ten times larger. Double-click the scale to change its look (the app colours, old paper, white, green, amber); the browser remembers it.
• Tuning step (-, list, +), Tune (see 5): the antenna tuner, and Memories (see 4), side by side on one centred row.
• VFO tools: A -> B, B -> A, A <-> B (swap), Split (receive on A, transmit on B), Quick split and Set B (type a frequency in MHz). The rows wrap and are centred, so they fit a small screen.
• FTDX101D / MP (two receivers): the panels are MAIN and SUB. The VFO tools row is MAIN ↔ SUB (swaps the two frequencies) and, for each receiver, its name button (makes the radio's dial and keys operate it, like the radio's MAIN / SUB keys), RX (listen to it, on / off, at least one stays on) and TX (transmit on it). Listen to one and transmit on the other for split. Set MAIN frequency and Set SUB frequency sit side by side in Band select. The audio you hear in the browser is one receiver at a time: with only one receiver listening it follows that one.
• Band select and Set frequency (type MHz, e.g. 14.195, or Hz, e.g. 14195000), Mode buttons.
• PTT (hold to transmit), always at the bottom, with the round Lock PTT button beside it.

Filters, Audio & Levels tabs

• Filters & DSP is grouped in tabs: Filter (width, narrow, IF shift, contour), Noise (manual notch, auto notch, DNR, noise blanker), Receiver (IPO/preamp, attenuator, AGC, RIT/XIT with the clarifier offset bar), Transmit (processor, monitor, tuner). Each row is a button, plus a bar where the function has a value. Double-click the clarifier bar to clear the offset. On the FTDX101D the panel starts with a MAIN | SUB switch (the filter, noise and receiver controls then act on that receiver), Transmit also has the processor level and the AMC output level (the radio's PROC / PITCH knob), and there are two more tabs: Audio (audio out level to the app, audio in level from the app) and CW (keyer speed, pitch, keyer, break-in).
• Levels: RF gain, microphone gain, transmit power; the gain bars show 0-100 %. The FTDX101D also has AF gain and RF gain for MAIN and SUB.
• Audio: volume, meters, device choice, and the raw radio meter values (see 6).

PTT stays at the bottom on every tab so you can adjust a level while transmitting.

4. Memory channels

Squelch (FT-991A, FTDX101D and MP): a Squelch slider appears under the mode buttons in FM, AM and C4FM and on the AIR band (and is always in the Audio & Levels tab); on the FTDX101 there is one for MAIN and one for SUB. 0 is open (no squelch); raise it until the noise just closes. It is the radio's own squelch level (SQ), the same as its SQL knob. On the FTDX101 it is written from the manual and simulator-tested; the FT-991A one was tested on a real radio.

AIR band (FT-991A): the band buttons include AIR (the radio's AIR key, BS14): the radio goes to the airband in AM by itself and the page's tuning step switches to 25 kHz, the airband channel spacing, and goes back to the previous step when you leave the band.

Memories (beside Tune; FT-991A and FTDX101D) lists the channels stored in the radio (001-099): number, name, frequency, mode. Type in the box to filter. Tap a channel to recall it. Back to VFO returns to the VFO. Re-read reads the list again after you changed memories on the radio. Export saves the list as a CSV file (a backup, or to open in a spreadsheet). The list is read in the background a few seconds after the radio connects, so it opens at once; it is read again whenever the radio reconnects.

Adding, editing and deleting a channel (FT-991A, administrators): Add stores a new channel and Edit (beside each row) changes one: name (up to 12 characters), frequency, mode, shift direction (simplex, plus, minus), tone mode (off, CTCSS encode, CTCSS encode + decode, DCS) and the tone frequency (the 50 CTCSS tones) or DCS code. Opening Edit on a channel with a tone reads that channel's own tone from the radio first (the radio is recalled to that channel for a moment and put back), so changing a name does not change its tone. Delete channel empties it. Saving or deleting asks for confirmation and takes 20 to 30 seconds: the program writes the channel and then reads all channels back, and tells you if the radio did not store it exactly as sent. To store a tone the radio's VFO-A is borrowed for a moment (it is set to the channel's frequency, mode, shift and tone, the channel is written, and VFO-A, its own tone settings and the V/M state are put back as they were). If a write or a delete ever changed a channel other than the one you chose, editing switches itself off (until the service is restarted) and the message names the channels, so put them back from your Export file. Export first if the list matters to you. One limit remains: the repeater offset (for example 600 kHz) is a radio menu setting, not stored per channel, so set it in the radio's menus; the page only chooses the direction.

5. Transmitting

Transmitting is disabled until the owner enables it: an administrator opens Admin > Config > Transmitting (PTT), chooses Enable transmitting… and types their password again (or sets allow_ptt = true in the configuration file on the Pi). The button then says Hold to transmit. An administrator can switch it off again at any time, which also stops a transmission in progress. Rules that always apply:

• Hold the button to transmit; let go to stop. The server un-keys on any hiccup: lost connection, lost control, time limit, shutdown.
• Hands-free transmit: tap TX LOCK (the button beside HOLD TO TRANSMIT) once. The radio keeps transmitting, without holding anything; the buttons show a dashed outline, "TRANSMITTING - TAP TO STOP" and "STOP". Tap TX LOCK (or the big button) once more to stop. (This replaces sliding up while holding.) The safeguards still apply: the time limit ends it, and it also ends when the page is hidden (screen locked, another app or tab), when control is lost or the connection drops. Use it only when you are sure of the band, the antenna and your power.
• Only the client with control can transmit; microphone audio reaches the radio only while that client is keyed.
• The microphone button (top right of the frequency panel) does two things at once: it arms your microphone in the browser and sets the radio's input to REAR, so the radio takes its audio from the USB port. On an FT-991A that is menu 106 (SSB MIC SELECT), 045 (AM MIC SELECT), 074 (FM MIC SELECT) and 070 (DATA IN SELECT), all together, so it works in every mode. Switching it off puts 106, 045 and 074 back to MIC (the front microphone), which is what local operation needs; so does the automatic return when the last operator has left (a menu left on REAR by hand is put back too). Menu 070 is left on REAR: it only matters in the DATA modes, and REAR is how digital programs and the FreeDV guide use it. It is locked while the radio is transmitting. If you close the page without switching it off, the Pi puts the radio back on MIC by itself about 15 seconds after the last operator (or administrator) connection has gone; a page reload or a short network drop does not trigger it, and a listen-only account does not keep it on REAR. It is left alone while the radio is transmitting.
• Tune makes the radio transmit a carrier for a few seconds while the antenna tuner matches. Use an antenna or dummy load.
• Lock (the round padlock beside Hold to transmit) locks the whole screen of this device, so nothing can be changed or transmitted by accident: the frequency, the buttons, the tabs and the keyboard shortcuts stop responding, and only the padlock stays live (scrolling still works). It also prevents accidental transmissions: while it is on (amber) the PTT button and Tune cannot be used. A transmission that is already running can still be released, and switching the lock on while holding PTT lets go at once. The choice is remembered in this browser; other devices have their own switch. It is a convenience, not a security setting: the server's own safeguards (permission, control, heartbeat, time limit) work as before.
• A time limit (default 120 s) stops over-long transmissions.

6. Audio

• Speaker icon = Listen (teal = on). Microphone icon = arm the microphone (teal = armed; it transmits only while PTT is held). Each is switched on and off only by you: changing tabs, locking the screen or using another app does not stop them, and the connection re-establishes itself if it drops. (Some phone browsers still suspend a page in the background; keep the screen on with Awake if yours does.)
• Audio tab: Volume; the RX audio, TX audio and Your mic meters; Speaker / output and Microphone / input: pick a Bluetooth headset, car hands-free kit or any other device (remembered per browser; Safari/iPhone cannot choose the output, use the system sound settings there); To radio counts audio frames delivered to the radio while you transmit.
• PTT button (Bluetooth headset or speaker-mic, or a key): press Bind PTT, then press the button on your device; it is remembered in this browser. A key such as Space works as hold to talk. A media button (play/pause, next track and similar) sends one event per press, so it works as press to start, press again to stop; some headsets only send one kind of press (Beats: a double press is "next track"), so press the button the way you will use it while learning. It works with Listen on or off: the page plays a silent sound so the browser keeps the media buttons for it, and after reopening the page the first tap or key press re-arms it. Bluetooth headsets: use the computer's own microphone (or any microphone that is not the headset's) as the Microphone / input and the headset only as the speaker. When the headset's own microphone is in use, Windows switches the headset to its phone-call mode, the button becomes a call button and the browser never receives it (tested with a Beats Studio Pro on Windows Chrome: the double press of the "b" button works with another microphone and not with the headset's). After an update the page can take a moment, or one extra reload, to use the new version. If nothing is received within 15 seconds the page says so; check that the headset is the connected device and close other media players. The screen lock, the PTT permission and the transmit time limit apply to it as to the screen button.
• What Bind PTT can pick up, and devices that do not work. A web page only receives what the browser passes on: ordinary keys (also Android hardware keys that have only a number), headset media buttons (play/pause, next track...), game-controller buttons and, in Chrome or Edge on a computer, Bluetooth serial buttons (see the next point). While you bind, the line Received: shows what arrived, even if it cannot be used.
• Bluetooth speaker-mics and PTT buttons that are not keyboards. Many of them (the kind sold for Zello and similar apps) show up on the computer as a Bluetooth headset for the audio, and send the PTT button over a separate serial connection: the B01 type sends the text +PTT=P when the button goes down and +PTT=R when it goes up. Pair the device with the computer first, then on the Audio tab press Bind PTT, then Add Bluetooth serial device (it appears while binding), pick the device's port in Chrome's list (named after the device, for example B01PTT-F5D0) and press its PTT button within 30 seconds. Once the port has been picked, a plain Bind PTT hears it too. The button then gives true hold to talk, the page reopens the port by itself when it is loaded or the device is switched on again, and a device that disappears while the button is down releases the radio. Needs Chrome or Edge 117 or later (not Safari or Firefox) on Windows or Linux, and only one program can have the port open. On a Mac Chrome cannot open such a port: use the small Radio Remote PTT helper instead: download radio-remote-ptt-mac.zip from the latest release, unzip it, open it once (right-click > Open, allow Bluetooth) and tick Start at login in its menu-bar icon. On Android install radio-remote-ptt-android.apk from the same release, choose the paired device and press Start. Pair the device with the computer or phone first, then press Bind PTT on the Audio tab and the device's button: the page finds the helper by itself (and shows a download link if it cannot). The helper listens on this computer or phone only, and the page reconnects to it by itself. iPhone and iPad cannot do this. If the port is read but the messages are not +PTT=P / +PTT=R, the page shows what it received: send that line to the developer and it can often be added.
• Android PoC radios and some Android speaker-mics send the PTT as a private Android signal that no browser receives, so Nothing received is the answer for them. Things to try: a setting of the device that makes its button act as a standard one (a headset or media button, or a keyboard mode), or on Android an app that remaps a hardware button to a media button.
• Too quiet? Raise the radio's USB output level menu (FT-991A: menu 107 SSB OUT LEVEL, 073 DATA, 046 AM, 075 FM, 054 CW, 099 RTTY) rather than boosting in software; see audio.
• Radio meters (raw) shows the radio's raw 0-255 ALC, COMP, power, SWR and S values and the ALC/COMP peak of the last transmission, which is what to read when calibrating the percentage scales.

Equalizer

The Audio tab has a parametric equalizer for what you hear (Receive) and for what you send (Transmit), like the one in Thetis: 5, 10 or 18 bands, each with its own frequency, gain (-12 to +12 dB) and Q (width, 0.3 to 10). Drag a node on the graph to set its frequency (left/right) and gain (up/down); the mouse wheel over the graph changes the selected band's Q (on a phone use the Q box); double-click a node to zero it; the boxes under the graph give exact values for the selected band. The curve shows the combined response. Bands changes the number of bands (it starts again flat), Preset (Voice, Bass cut, Treble cut, Bass boost, Treble boost, and FreeDV speech: less bass, more presence at 1 to 4 kHz, which makes decoded RADE speech clearer) sets the gains at your band frequencies, Reset zeroes all gains. It is one setting for the whole radio, shared by everyone connected, and it is kept across restarts. Both sides have a Low-cut and a High-cut (24 dB per octave, off until you tick them; defaults 150 Hz and 2800 Hz for Transmit, 200 Hz and 6000 Hz for Receive): tick the box and type a frequency, or drag the dashed L and H markers on the graph. They keep unwanted rumble and hiss out of the signal and out of the radio's own filter edges. The selected band's Freq, Gain and Q are on one line under the graph. Two buttons on the Radio tab, RX EQ and TX EQ (after Memories), switch each equalizer (and the cuts) on and off so you can compare. It adds about 10 ms of delay while on; very narrow bands below about 150 Hz come out a little wider and weaker than drawn. With FreeDV the equalizer works on the speech only: the modem tones are never equalized.

Noise gate (Receive and Transmit)

Each side has a Noise gate under the graph (off until ticked). It turns the audio down by Range dB (default 30) when the level stays under Thresh. (default -50 dB), waits Hold ms (default 150) before it starts to close and closes over Rel. ms (default 250), and opens again at once when the level comes back, so word endings are not chopped. Receive takes the hiss out of the pauses between words (it also works on decoded FreeDV speech); Transmit keeps the microphone's room noise out of the signal and out of the leveler, which would otherwise raise it. A readout shows how many dB the gate is taking off while it is closed. Set Thresh. just above the noise in the pauses and below your quiet words, then listen for chopped word beginnings and lower it if you hear them.

Saved equalizer sets

My sets… (beside Reset) saves the current bands (frequency, gain and Q) and the low-cut and high-cut under a name; Use puts a saved set on the Receive or the Transmit equalizer, and Delete removes it. Your sets also appear in the Preset list under My sets. Up to 20 sets are kept; they are shared by Receive and Transmit and by everyone connected, and kept across restarts.

Transmit leveler and limiter

Under the Transmit graph, two more stages for your voice, after the noise gate (they are shared and kept like the equalizer, and they work on the speech only: a FreeDV signal is made from the leveled speech, and a recording sent with Send is not touched):

• Leveler brings your voice toward a Target level (default -18 dB). It only adds gain, up to Max (default 12 dB), follows a louder voice at once and a quieter one slowly (Decay, default 300 ms), and holds its gain in pauses instead of boosting the room noise. It evens out a voice that moves around the microphone, so the average power is higher for the same peaks. The readout beside it shows the gain it is adding while you transmit.
• Limiter keeps the peaks under a Ceiling (default -3 dB) and lets go with the Rel.(ease) time (default 100 ms); the readout shows how many dB it is reducing. Together with the leveler it is the ALC of a good SSB transmitter: set the radio's own speech processor to off, watch the radio's ALC and the power on a dummy load, and lower the Target or the Ceiling if the ALC goes over its mark.

Both are off until you tick them. Start with the leveler's defaults and the limiter at about -3 dB.

Recorder (REC, Play, Send, Recordings)

A Recorder block under Mode on the Radio tab has four buttons of one size:

• REC records what you hear (the decoded speech when FreeDV is on, otherwise the radio's audio, before the equalizer; nothing is recorded while you transmit), up to two minutes. The button shows the elapsed time; press it again to stop. The Pi keeps the last five clips: a new recording replaces the oldest.
• Play plays the last recording here, in your browser (it is not sent to the radio).
• Send sends the last recording over the air like a voice keyer: PTT is keyed, the clip plays, and PTT is released by itself when it ends. It uses the same safeguards as any transmission (control, heartbeat, time limit, the screen lock) and does not need your microphone. Tap the PTT button or Stop to end it earlier. Use it to give another station an audio report: send only audio you may retransmit, such as their own signal back to them, and give your callsign.
• Recordings opens the last five, each with a player, Download (a WAV file), Send and Delete. When FreeDV is on, each recording also keeps the radio's own audio before decoding (the modem signal, 16 kHz): Download raw radio audio gives that file. It is what to analyse when a station decodes badly (sync, SNR, frequency offset, level, gaps): the speech alone cannot show why.

7. Remote access

• At home: https://<pi-name>.local. Your device must trust the Pi's certificate once (see security and remote access).
• FreeDV digital voice (RADE V1 and RADE V2): the Digital tab, FreeDV switch, switches it on and off and has preset channels; the Pi does the encoding and decoding. See FreeDV.
• FT8 and FT4: the Digital tab, FT8/FT4 switch (on the all-in-one desktop layout the FT8/FT4 button under the title) decodes the band, calls and answers with the standard sequence, keeps an ADIF log and can upload it to QRZ, eQSL and Club Log. See FT8 and FT4.
• CW (Morse): the Digital tab, CW switch, decodes the Morse in the radio's audio into text, with a spectrum, the pitch and the speed it found and sends what you type through the radio's keyer (see cw.md).
• Menu (the last tab): the radio's own menu, every item the CAT manual lists (the FT-991A: 001 to 153), with search, groups, undo, and backup / restore of the whole menu (see menu.md). Items that could cut the link or change the keying are read only.
• JS8 (keyboard messaging): the Digital tab, JS8 switch, call CQ, send heartbeats and talk to the stations heard. The modem is JS8Call, a separate program that an administrator installs with a button (see js8.md).
• RTTY (radio teletype): the Digital tab, RTTY switch, decodes the two tones into text, sends what you type as Baudot audio tones (45.45 baud / 170 Hz by default) and logs contacts (see rtty.md).
• SSTV (slow-scan television): the Digital tab, SSTV switch, receives pictures from the radio's audio line by line and transmits a picture of your own with your callsign printed on it. See SSTV.
• A logbook on another computer (Log4OM and others) can follow and tune the radio over the home network: logbook link.
• Away from home: Tailscale (guide). No port is opened on your router.

8. Administrators

Admin has these tabs: Users (create, roles, trusted, reset password), Clients (connected devices; disconnect one), Config (radio model, serial port, audio devices and gains, meter calibration, SWR warning limit, time limits, the transmit switch and Settings backup: download the settings to a file and restore them later; Updates: whether a newer release exists and how to install it; some changes need a restart), Diagnostics (system, radio link, audio and the recent log) and Audit (who did what). Power off switches the radio to standby; when the radio is off, the offline banner shows Power on radio. Details: operations.

9. If something is wrong

Operations: configuration, services, updating, backup

Where things live (after install.sh)

Configuration

Edit in the web UI (Admin > Config) or in the file. The file is the only place for the settings the UI refuses to change on purpose: server.*, storage.*. The transmit permission (safety.allow_ptt) has its own switch in the same page (Transmitting (PTT)): enabling asks for the administrator's password, applies at once, is written to the file and is audited. Other changes need sudo systemctl restart radio-remote (the log level and audio gains apply live). The UI's "Restart service now" button does the same.

System card (Admin > Config). Two buttons that are always there: Restart the service… (confirmation, then the page reloads by itself when the service is back) and Reboot the system… (needs your password again; refused while the radio transmits; it only appears when the root helper radio-remote-power.path is installed, which install.sh and update.sh do). Like Update now, the page itself cannot reboot anything: it only drops /var/lib/radio-remote/power-request, and a root helper (scripts/power_from_request.sh, started by systemd) reboots the machine after about 3 seconds, and does nothing else. Both actions are written to the audit log.

Services

sudo systemctl status radio-remote           # is it running?
sudo systemctl restart radio-remote          # restart (un-keys the transmitter first)
sudo systemctl stop radio-remote             # stop
sudo systemctl disable --now radio-remote    # stop and do not start at boot
journalctl -u radio-remote -f                # follow the log
journalctl -u radio-remote --since "1 hour ago" --no-pager
systemctl list-timers radio-remote-backup.timer
sudo systemctl status caddy                  # the HTTPS front end

The service restarts itself after a crash (Restart=always) and is restarted by systemd if it hangs (watchdog, 20 s). A switched-off or unplugged radio does not restart the service: it reconnects by itself. Stopping or restarting the service releases PTT before the process exits.

In the UI, Admin > Diagnostics shows version, CPU/RAM/temperature, radio and CAT counters, audio state, clients, the control holder and the recent log. sudo scripts/doctor.sh prints similar information plus USB/serial/audio devices.

Updating

Update notice. Once a day the server asks GitHub whether a newer release exists (one anonymous, read-only request to api.github.com; switch it off in Admin > Config > Updates or with [updates] check = false). When there is one, administrators see a bar at the top of the page ("Radio Remote v1.2.0 is available") with a link to the release notes. Nothing is downloaded or installed by the notice itself.

Update from the page. In Admin > Config > Updates, when a newer version is known, press Update now…, type your password and confirm. The page only drops a request file; a small root helper that systemd starts for it (radio-remote-update.path / .service, installed by install.sh and update.sh) runs self_update.sh (download, SHA-256 check, backup, install, health check, automatic rollback). The service restarts, so Radio Remote is unavailable for about a minute (a transmission in progress is stopped); the Updates card shows the log and the page reloads by itself when it is done. The result is also in /var/lib/radio-remote/update.log, and the request and the outcome are in the audit log. A Pi that was installed before the helper existed gets it with its next update from the command line.

Update from the Pi (needs internet on the Pi):

sudo /opt/radio-remote/current/scripts/self_update.sh --check     # is there a newer release? (no root needed)
sudo /opt/radio-remote/current/scripts/self_update.sh             # download, verify the checksum, install

It downloads the release's update package (radio-remote-vX.Y.Z.tar.gz) and its SHA256SUMS, refuses the package if the checksum differs or it holds anything unexpected, then runs the package's own update.sh. --force reinstalls the newest release even if it is not newer.

Without internet on the Pi, or from the source code:

# on a computer with internet: download radio-remote-vX.Y.Z.tar.gz from the Releases page, copy it to the Pi, then
tar xzf radio-remote-vX.Y.Z.tar.gz && cd radio-remote
sudo ./update.sh --dry-run        # optional preview
sudo ./update.sh

(From a git checkout: git pull, then sudo ./update.sh; build the manual first with python scripts/build_docs.py if you want it on the Pi.)

update.sh: backs up config and users, installs the new version beside the old one (including Python packages, before anything is switched), switches, restarts, and checks health. If the new version is not healthy it switches back to the previous release automatically and keeps the failed one for inspection. The three newest releases are kept. Config and the user database are never modified by an update.

Manual rollback: sudo ln -sfn /opt/radio-remote/releases/<older> /opt/radio-remote/current && sudo systemctl restart radio-remote. (If the newer release changed Python dependencies, the older code normally still runs; if not, re-run /opt/radio-remote/venv/bin/pip install -r /opt/radio-remote/releases/<older>/requirements.txt.)

Backup and restore

A timer runs a backup daily (14 kept). Manual:

sudo scripts/backup.sh                                   # -> /var/backups/radio-remote/radio-remote-<time>.tar.gz
sudo scripts/restore.sh /var/backups/radio-remote/radio-remote-20261001-030000.tar.gz

What is backed up: /etc/radio-remote/config.toml and /var/lib/radio-remote/radio-remote.db (a consistent snapshot even while running). That is everything worth keeping; the program itself is reproducible from git. Restore stops the service, keeps the replaced files as *.before-restore, restores, restarts and checks health. Copy backups off the Pi occasionally: they are on the same SD card.

Settings only, from the web page. Admin > Config > Settings backup has Download settings (a small .toml file with the radio, audio, meter and limit settings: no accounts, no passwords) and Restore from file…. A restore takes only the settings the web page may change; the listener address, the storage folder and the transmit permission (server.*, storage.*, safety.allow_ptt) are never taken from a file, so an old backup or a file from another Pi cannot lock you out or switch transmitting on. The replaced config is kept as config.toml.bak, the change is audited (config_backup, config_restored) and a restart applies it. Use the daily archive above (or restore.sh) when you also need the user accounts.

Forgot the admin password

On the Pi: sudo -u radio-remote /opt/radio-remote/venv/bin/python -m radio_remote.cli --config /etc/radio-remote/config.toml reset-password <name> (with PYTHONPATH=/opt/radio-remote/current/backend). It prompts for the new password and signs that user out everywhere.

The manual on the Pi

The manual is installed with the program and served at https://<pi>/docs/ (the Help button in the app). It is built from docs/*.md by python scripts/build_docs.py --pdf (HTML + a PDF) and travels inside every release as docs-html/.

Connecting the radio

FT-991A: complete and tested on a real radio. FTDX10, FTDX101D, FTDX101MP and FT-710 have experimental profiles (written from their CAT manuals, tested only against a simulator): other radios. A built-in simulator ("mock") lets you try everything without a radio. What each radio supports: capability matrix.

USB cable

Connect the radio's rear USB jack straight to the Pi (a short, good-quality cable; avoid unpowered hubs). Switch the radio on.

lsusb                       # expect a "Silicon Labs CP210x" entry (CAT) and a "USB Audio CODEC"-style entry
ls /dev/serial/by-id/       # the FT-991A's USB bridge presents TWO serial ports (CAT and a second one)
arecord -l ; aplay -l       # the radio's sound card, e.g. "card 1: CODEC [USB Audio CODEC]"

The app finds the CAT port itself: it probes only Silicon Labs USB serial ports, sending the read-only ID; and accepting the one that answers ID0670; (FT-991A). You can also set radio.serial_port explicitly (Admin > Config). The service user must be in group dialout (the installer does this). Only one program may use the port: close any other CAT software. If the radio is switched off or unplugged the page shows it as offline and reconnects by itself.

Radio menu settings (FT-991A)

You set these once on the radio. The only menus the program changes by itself are the microphone source ones (below), when you press the microphone button or the last operator leaves. Menu numbers are from the official CAT manual (1711-D).

Basics (every use)

Microphone source: managed by the app (0 = MIC, 1 = REAR)

Where the audio comes in and goes out: USB (bench-found on a real FT-991A after a reset: the app keyed the radio but no RF came out, because the port menus were on DATA)

If PTT from the app keys the radio but an external power meter shows nothing (in SSB, no audio means no RF), check these first.

Receive level sent to the Pi (0-100, default 50): 107 SSB OUT LEVEL in USB/LSB, 073 DATA OUT LEVEL in the DATA modes (and 046 AM, 075 FM, 054 CW, 099 RTTY). If the browser audio is too quiet, raise it (90 was right on one tested radio, 50 on another) before using audio.rx_gain_db.

FreeDV in the DATA modes (the FreeDV guide's setup; switch on the FreeDV tab's DATA option after setting them)

Not set for FreeDV, but worth knowing: 110 SSB TX BPF narrows the SSB transmit audio (it matters only if you use plain USB/LSB for FreeDV, which is why the DATA modes are recommended), and the speech processor must be off.

Other menus that decide where transmit audio comes from and where receive audio goes (109 SSB PORT SELECT and the AM/FM equivalents) are listed in the manual but without a ready recipe: if your audio does not flow, follow the steps in audio and change one menu at a time.

Powering the radio on and off

Power off is an administrator button in the page (PS0;). Power on radio appears in the offline banner when the radio is in standby (the server sends dummy data, waits 1.4 s, then PS1;, as the manual requires). Both work over USB on the FT-991A, because its USB serial port stays available in standby while the DC supply is on.

Config keys involved

[radio]
model = "ft991a"
serial_port = "auto"        # or "/dev/ttyUSB0"; stable names are under /dev/serial/by-id/
baud = 38400

[audio]
backend = "auto"            # real radio -> alsa
input_device = ""           # radio -> Pi, e.g. "plughw:CARD=CODEC,DEV=0"; empty = auto when exactly one USB audio CODEC exists
output_device = ""          # Pi -> radio

A device name is an ALSA name such as plughw:CARD=CODEC,DEV=0, not a bare number (a number like 0 is refused). Leave both empty unless auto-detection fails.

Remote audio

RX:  radio USB codec -> arecord -> gain -> shared track -> MediaRelay -> Opus (per listener) -> browser
TX:  browser mic -> Opus -> decode -> mono 48 kHz -> [SERVER GATE] -> gain + limiter -> aplay -> radio USB codec

Internal format: mono, s16, 48 kHz, 20 ms frames. Opus runs at 32 kbps (aiortc defaults to 96 kbps stereo); configurable with audio.opus_bitrate. The audio runs in the same process as the rest of the server (a separate process was considered; the measured CPU cost on a Pi 4 makes it unnecessary).

Using it

• Speaker icon = Listen, microphone icon = arm the microphone. Each is switched on and off only by you. The microphone needs HTTPS (browsers refuse it on plain http://): the installer sets that up, and your device must trust the Pi's certificate once (security) or use the Tailscale name (tailscale).
• The mic transmits only while you hold PTT and hold control. Set the radio to take its audio from the USB port: menu 106 = REAR (the REAR / MIC buttons in the app do this), see radio connection.
• The audio session (one WebRTC connection) exists while Listen is on or the microphone is armed. Arming the mic alone connects with the radio audio muted; Listen only unmutes it; both off ends the session. The mic is never armed from an earlier visit.
• Several browsers can listen at once (audio.max_peers, default 3). Any operator may attach a microphone, but the server passes audio only from the connection that owns PTT.
• A Bluetooth headset can be chosen as the device on the Audio tab. Listening continues with the app in the background on phones.

Safety design

• Mic audio is dropped on the server unless the PTT guard says this exact WebSocket connection owns an active transmission (guard.keyed and guard.owner == conn_id). The browser also mutes its mic track outside PTT, but that is a convenience, not the protection.
• Gate closing clears the jitter queue, so stale audio is never sent at the next PTT.
• A soft limiter (ceiling about -1 dBFS) always follows TX gain.
• Viewers can listen but never transmit audio; only one mic stream is accepted at a time.
• When no mic stream is connected the playback device is closed entirely; when one is connected, silence is fed to the radio between transmissions to keep its codec stable.
• Closing a WebSocket closes that connection's audio session. Audio sessions are tied to the logged-in user: /api/audio/offer rejects a conn that belongs to someone else.

What has been verified

On a real FT-991A with a Raspberry Pi 4:

• receive audio in the browser, with the meter moving; the radio appears as one USB audio CODEC and is detected automatically;
• transmit audio into a dummy load, with ALC and COMP readings (the TX gain and the radio's data-out level set the ALC);
• background listening on a phone, and choosing a Bluetooth output and input;
• CPU cost measured with tools/audio_spike.py on a Pi 4 (aarch64, Python 3.13): Opus encode 3-4 % of one core per stream, decode below 1 %, one loopback listener about 21 % and three about 56 % of one core with both ends in one process (the real server-side cost is lower). A Pi 4 has ample headroom for the default audio.max_peers = 3; a Pi 3B+ is expected to be 2-3 times slower per core: use 1-2.

Automated tests (no radio) cover real WebRTC sessions in-process: RX audio and level meter, mic audio reaching the sink only while the gate is open, wrong connection, viewer role, peer limit, device loss and recovery.

Not measured yet: the latency of either transport (WebSocket audio, receive and transmit, and the automatic fallback with UDP blocked were verified on a real FT-991A with a Raspberry Pi 4), figure (budget: capture 20-80 ms + Opus 20 ms + network + the browser's jitter buffer).

When WebRTC cannot connect: WebSocket audio

WebRTC sends the audio as UDP packets. Some networks block that (hotel, office or school Wi-Fi, some mobile carriers, strict firewalls). The page then works but the audio does not connect. For that case the same Opus audio can travel over the page's own HTTPS/WebSocket connection (TCP).

• Audio tab > Connection has three choices. Automatic (the default) tries WebRTC and, if it has not connected after about 9 seconds or fails, switches to WebSocket audio and remembers that for 6 hours (so the next start is quick). WebRTC (UDP) and WebSocket (TCP) force one.
• The status line says "(WebSocket)" when it is in use. Listening, the microphone and PTT behave the same. The server-side gate is identical: microphone audio is only passed while that connection owns PTT, and nothing is sent from the browser unless PTT is held.
• It needs a browser with WebCodecs (AudioDecoder/AudioEncoder: current Chrome, Edge, Firefox and Safari 17 or newer) and, for the microphone, AudioWorklet and HTTPS. Otherwise the page says so and WebRTC stays in use.
• Trade-off: TCP resends lost packets, so on a poor connection the audio can lag or stutter more than WebRTC. Prefer WebRTC when it works.
• Server side: the Opus codec comes from PyAV (already installed for WebRTC). audio.max_peers counts both kinds of listener.

Pi setup notes

sudo apt install alsa-utils libopus0          # the installer does this
sudo usermod -aG audio radio-remote           # service user needs the audio group (the installer does this)
arecord -l ; aplay -l                          # note the CARD=<id> of the USB Audio CODEC

Use Raspberry Pi OS Lite (no PipeWire/PulseAudio grabbing the device). Set audio.input_device / audio.output_device to plughw:CARD=<id>,DEV=0 (a full ALSA name, never a bare number) only if auto-detection finds zero or several codecs. The admin-only GET /api/audio/devices shows what the server sees.

If there is no audio

1. arecord -l / aplay -l: confirm the codec appears when the radio is on, and what its card ID is.
2. arecord -D plughw:CARD=<id>,DEV=0 -f S16_LE -r 48000 -c 1 -d 5 /tmp/rx.wav with a signal on the radio: play it back. If that is silent the problem is on the radio side (menus, USB level), not in the app.
3. In the app: Listen. Check the RX meter and what you hear. Adjust audio.rx_gain_db.
4. For transmit, test with a dummy load: enable Mic, speak, watch "Your mic" move; then hold PTT and watch "TX audio". Tune audio.tx_gain_db and the radio's data-out level until the ALC is just touching.
5. The connection can drop and come back for a second when the browser renegotiates (reloading the page, toggling Listen, a network change): that is normal.

Receive volume too low

Three places, in this order: 1. Browser Volume slider (Audio tab) at 100 %. 2. The radio's own USB output level menus (0-100, default 50): 107 SSB OUT LEVEL, 073 DATA OUT LEVEL, 046 AM OUT LEVEL, 075 FM OUT LEVEL, 054 CW OUT LEVEL, 099 RTTY OUT LEVEL (CAT manual p.9). This is the cleanest fix because it improves the signal-to-noise ratio instead of just amplifying. (On the tested FT-991A, menu 107 = 90 fixed a quiet receive level.) 3. Admin > Config > Audio > rx_gain_db: boost in dB (-30..30, live, no restart). +6 dB doubles the amplitude, +12 dB is four times. A boost above 0 dB runs through the same soft limiter as the transmit path, so loud signals do not clip hard.

The radio's AF gain knob is believed not to affect the USB audio (not verified separately); the app therefore does not offer an AF gain slider.

FreeDV digital voice

FreeDV sends speech as modem tones in an ordinary SSB channel. Radio Remote does the FreeDV work on the Pi, so you only need the browser:

• Receive: the Pi turns the radio's modem tones back into speech and plays that to every listener.
• Transmit: your voice (browser microphone) is turned into modem tones by the Pi and sent to the radio, while you hold PTT.

Modes: RADE V1 (the neural mode most stations use today) and RADE V2 (see below). Both come from one optional library, the same one that has always held RADE. The older codec2 modes (1600, 700D, 700E) were removed from the program; a configuration file that still names one of them is read as RADE V1.

Status: the modem round trip (voice to tones to voice, noise rejected) is covered by automated tests. How well it works over the air with your radio, antenna and band has to be found out by trying it: start with receive, then transmit into a dummy load.

What you need

• The RADE library (see below). It is installed by the installer; without it the FreeDV tab says so and offers no mode.
• Remote audio working (audio): FreeDV only decodes while someone is listening (speaker icon) and only transmits while the microphone is armed and you hold PTT.

Using it

1. Open the Digital tab and choose FreeDV in its switch (on the all-in-one desktop layout it is the card under Levels and Audio). Switch FreeDV on starts it; if the radio is not in USB or LSB it puts it in USB (LSB below 10 MHz), which is the FreeDV convention. The same button switches it off. The Radio mode box next to the FreeDV mode chooses the mode the radio is put in: Automatic (the default: LSB below 10 MHz, USB above, the FreeDV convention) or one of USB, LSB, DATA-U, DATA-L, FM, as on the other digital screens. It is remembered in this browser; picking a channel and the Tune buttons of the FreeDV Reporter list use it, and choosing it changes the radio's mode at once. Other stations are on USB/LSB: with a DATA mode or FM your signal may sit somewhere else in the audio than theirs (see the DATA mode section below), so keep Automatic unless you know why you want another.
2. The tab shows the status (whether the modem is locked on a signal and its signal-to-noise ratio) and has the preset channels: one tap sets LSB or USB, the frequency and the FreeDV mode, and switches FreeDV on.
3. Switch Listen on (speaker icon). When a FreeDV signal is locked you hear the decoded speech. Without a signal you hear nothing: the Pi passes no noise on. Tune carefully (the modem finds the signal within about 100 Hz); watch the status.
4. Transmit: arm the microphone (microphone button, which also sets the radio's input to REAR), hold PTT (or tap TX LOCK to transmit hands-free and tap it again to stop) and talk. The Pi encodes your voice for as long as you hold PTT.

Switching FreeDV off passes the radio's audio through as before (it does not change the radio's mode back).

The tuning aid: the Pi finds the tuning for you

A FreeDV modem only locks when the signal is close to where it expects it, and a radio dial cannot be set that finely by hand. Measured with ideal signals: RADE V1 locks only within about ±50 Hz, so the Pi does the fine tuning in software (RADE V2 locked across the whole ±300 Hz tried, so for V2 the search is rarely needed):

• While nothing is locked it shifts the received audio, step by step, within ±450 Hz around the dial frequency, until the modem locks, and then holds that shift. The strongest-looking spot in the spectrum is tried first. A short fade-out does not make it start again (it waits a few seconds).
• The FreeDV tab shows the spectrum of the received audio (0 to 4 kHz) with the band where the modem expects its signal shaded (it moves with the correction), a yellow line where the spectrum thinks the signal is, and a text line: the audio level (it warns when it clips or is very low), and either Locked: the signal is 120 Hz above its normal place; the Pi is correcting it by itself or No signal locked yet: searching.
• Centre the dial (shown when the Pi is correcting 30 Hz or more) moves the radio's dial by exactly that offset, so the signal sits where the modem expects it. The dial buttons (−100, −10, +10, +100 Hz) are for fine steps. If you move the dial while locked, the Pi adjusts its correction by the same amount and keeps the lock. Search again forgets the tuning found so far.
• The Pi only analyses the audio while someone is listening (speaker icon). If nothing locks: check that the level line says "fine", that the radio's DSP (noise reduction, notch, contour, narrow filter) is off, that the sideband is right (LSB below 10 MHz) and that a FreeDV station is really on the air.

Radio settings that matter for FreeDV

FT-991A: use plain USB/LSB, like the other stations (recommended, and the default). Below 10 MHz FreeDV uses LSB, above it USB, with the same dial frequencies as the channel list and the FreeDV Reporter. Every station you meet is on its radio's ordinary SSB mode, and a DATA mode can put your signal somewhere else (see below). In USB/LSB the radio's filter is 2400 Hz, which carries RADE V1 (audio 750 to 2250 Hz) and V2 (about 1000 to 1900 Hz), and the radio's own SSB transmit filter (menu 110, for example 400-2600 Hz) trims the edges of the signal. What the radio must not do is process the audio:

Set the transmit level with the Level test (see below): the radio's ALC must stay under its mark and the power should be close to what you set; a compressed RADE signal cannot be decoded.

Alternative: the radio's DATA mode (the way the FreeDV guide for the FT-991A does it). The DATA modes bypass the radio's microphone chain, but they have traps of their own: the receive filter starts at 500 Hz (see the filter width below), the transmit band is not trimmed by menu 110, and the OTHER DISP / OTHER SHIFT menus (064, 065) change the relation between the displayed frequency and the carrier, so at the same displayed frequency your signal may sit up to 1500 Hz away from where a USB/LSB station expects it (V1 only locks within about 50 Hz: nothing would decode). Use it only if you have checked all three. FreeDV's own guide sets these menus once on the radio:

Then switch on Use the radio's DATA-USB / DATA-LSB mode in the FreeDV tab (administrators): FreeDV then puts the radio in DATA-USB (DATA-LSB below 10 MHz) instead of USB (LSB). It is off by default because it needs the menus above. The receive level that goes to the Pi is then menu 073 DATA OUT LEVEL (in USB/LSB it is 107 SSB OUT LEVEL).

The radio's filter width: RADE V1 needs about 1500 Hz of the audio, and the DATA modes start too narrow (BENCH-FOUND). RADE V1 occupies about 1500 Hz: the audio from about 750 to 2250 Hz (V2 about 900 Hz, around 1000 to 1900 Hz). An FT-991A in a DATA mode starts with a 500 Hz receive filter (width code 10 in the radio's table): a recording of the noise in DATA-L spanned exactly 1225 to 1750 Hz, and the reference RADE decoder found nothing in it, because only a third of the carriers get through. The DATA filter is centred on 1500 Hz, so 1700 Hz is the least that carries V1 and about 2000 Hz is comfortable; in USB/LSB the passband starts near 300 Hz, so about 2100 Hz is needed and the default 2400 Hz is fine. More than that only lets in more noise and neighbouring stations (it does not help RADE). The width is kept per mode (USB and DATA-L have their own), and the DATA modes have no width key on the radio's front panel, so the Filters tab shows a Width list for DATA-U and DATA-L as well, and the FreeDV tab shows a warning with a Widen button when the filter is too narrow while FreeDV is on. With Open the radio's filter automatically ticked (the default; administrators can change it), the app opens a too-narrow filter by itself a moment after FreeDV is switched on or the mode changes, to the narrowest value from 2000 Hz (DATA) or 2400 Hz (USB/LSB) up. Check it with a recording of the noise (REC on the Radio tab, then Download raw radio audio): it should span roughly 750 to 2250 Hz or more.

Always: speech processor off, no equaliser tricks (the radio must pass the modem tones unchanged).

• Set the transmit level so that the ALC barely moves: the tones are a continuous signal with high peaks, and an overdriven signal is worse than a weak one. Use the Transmit level of the modem tones slider on the FreeDV tab (administrators; default -6 dB) together with the radio's data-in level. Watch the power meter as well: a level so low that the radio makes only a few watts reaches fewer stations.
• The receive level that goes to the Pi is the radio's menu 107 SSB OUT LEVEL in USB/LSB, 073 DATA OUT LEVEL in the DATA modes (radio connection): the modem tones should be clearly present but never clipping.

RADE (the neural modes)

RADE V1

RADE V1 sends speech as an OFDM signal that is about 2.1 kHz wide and decodes at lower signal-to-noise ratios than 700D/700E (it still locks at about 0 dB on a fading path). It is the mode most FreeDV activity uses. It comes from a separate library of about 24 MB.

A new installation already has it, you do not need to do anything: the ready-made image and the installer pack contain the RADE library, and install.sh (Raspberry Pi or Debian PC) downloads and installs it as part of the install (--no-rade skips it). Ordinary updates do not carry it, so they stay small, and a library that is already installed is kept.

If it is missing, for example because the install had no internet: an administrator presses Install RADE in Admin > Config > RADE (or in the FreeDV tab, which shows the same button; once RADE is installed it says Reinstall RADE). The Pi downloads the library from the project's release page, checks its SHA-256, puts it in /var/lib/radio-remote/lib and starts using it at once, with no restart. It works on 64-bit Linux: a Raspberry Pi with the 64-bit OS, or Debian 12/13 on a 64-bit PC (see installation, route D). The library is built on Debian 12 and runs on Debian 12 and newer. From the command line:

sudo /opt/radio-remote/current/scripts/install_rade.sh            # downloads the matching release file, checks its SHA-256, installs it, restarts the service
sudo /opt/radio-remote/current/scripts/install_rade.sh --file F.tar.xz   # from a file you copied to the Pi (no internet)
sudo /opt/radio-remote/current/scripts/install_rade.sh --remove

Then choose RADE in the mode list of the FreeDV tab (or in a channel). Until it is installed the tab says so and offers only the codec2 modes.

• The library is built from the open-source rade_c C port (BSD licence, with the Opus sources it uses); the release includes the licence files. It runs in the same program as the rest of the server (about 3% of one fast PC core to decode, less to encode; expect roughly a quarter to a third of one Pi 4 core while receiving: not yet measured on your Pi).
• RADE V1 has no automatic level control on receive: if it does not lock on a signal you can hear clearly, try the radio's menu 107 or Admin > Config > Audio > RX gain. For transmit use the same modem level slider as the other modes and keep the ALC barely moving.
• The speech it plays is the neural vocoder's voice (clean, but not your exact voice). A few hundred milliseconds of delay is normal.

Your callsign in the transmission (RADE V1)

At the end of every RADE V1 transmission the Pi sends your callsign inside the signal (in the end-of-over frame), the way the FreeDV program does, so other stations' programs can show who was calling.

• Set it (administrators): FreeDV tab > FreeDV Reporter settings > Callsign sent with every transmission. Up to 8 letters, digits or /. Left empty, the Callsign of the Reporter settings is used (its first 8 characters). The configuration key is [freedv] callsign.
• Needs the RADE library of 1.1.36 or later. An older one sends no callsign; the RADE line on the FreeDV tab then says so, and Reinstall RADE fixes it.
• What you see: when a received over ends with a callsign, Last heard: CALLSIGN (time) appears under the FreeDV status line. It is read from the end-of-over frame only, so it appears after the over, and not at all if the signal was too weak for the error correction to recover it (the speech may still have been readable).
• RADE V2 has no such text channel here: it sends and shows nothing.

RADE V2

Choose RADE V2 in the mode list. It is a newer version of the same idea with a narrower signal (about 1.1 to 1.9 kHz), its own level control on receive, and it follows a mistuned signal by itself. A V1 station cannot decode a V2 station and the other way round, so use the version the other station uses; most stations are on V1 today.

• It needs a library built with V2 support (the one that comes with this version). If you updated the program but kept an older RADE library, V1 still works and the tab says that V2 needs the library to be reinstalled: Admin > Config > RADE > Reinstall RADE.
• The FreeDV Reporter lists V2 stations as "RADE V2"; the site's mode name for V2 is RADEV2 (as other open-source clients report it).

When your transmission is unreadable at the other station

First check that you and the other station use the same RADE version. V1 and V2 are different waveforms and do not decode each other at all (the reference decoder gave 0 % lock on a V2 recording with V1 and the other way round). Many stations on the air use V2 now (about 900 Hz wide, around 1000 to 1900 Hz of the audio) while others use V1 (about 1500 Hz, 750 to 2250 Hz). Ask the station, look at the mode on the FreeDV Reporter list, and set the same one on the FreeDV tab; a station that "cannot understand anything" is very often on the other version.

Check that the transmitted signal stays in its band. The V1 modem's output is made of OFDM carriers with sharp edges; without a band-pass filter about 7 % of its power falls outside 700 to 2300 Hz (skirts down to the audio floor and up past 3 kHz), so on someone's waterfall it looks wider than it should and the radio's ALC and filters see it. RADE V2 has its filter on by default; for V1 the library has it but leaves it off. Libraries installed from 1.1.30 on have it switched on (1.6 % outside the band, a lower peak-to-average ratio): if the FreeDV tab says the installed RADE library is older, press Reinstall RADE.

RADE needs a continuous stream of tones, with no holes in it. The Pi therefore keeps a small cushion (about 0.2 s) of modem tones queued before it starts sending them to the radio, so an uneven network (Wi-Fi, a remote connection) cannot put gaps into the signal; when you release PTT the Pi first sends the last modem frame (silence completes it) and lets the queued tones reach the radio, so the end of the over is not cut off; the radio is unkeyed about half a second after you let go. After every over the service log says whether the tones went out whole:

journalctl -u radio-remote --since "10 min ago" | grep "FreeDV transmit"

no holes is good. the tones had N hole(s) means the audio reached the server unevenly or the PC is too slow: use a wired connection, close other programs, and send the line to the developers. Admin > Diagnostics (and /api/diagnostics) also shows the slowest processing step, which should stay well under 20 ms on the receive side. A PC that regularly needs longer than that for one 20 ms frame will stutter.

FreeDV Reporter: be listed, and see who is on the air

qso.freedv.org is the live list of FreeDV stations: callsign, grid square, frequency, mode, whether the station is transmitting right now, and a short message. Radio Remote can join it. It is off by default.

• Switch it on (administrators): FreeDV tab > FreeDV Reporter settings. Tick Switch the link to FreeDV Reporter on, and enter your callsign and grid square (for example IO91wm) to be listed, plus an optional short message. Choose whether to announce this station, to show who is on the air, or both. Apply.
• What is sent, and when: the Pi connects to qso.freedv.org only while FreeDV is switched on and disconnects when you switch it off. It sends your callsign, grid square and the program name ("Radio Remote 1.x") once, then your dial frequency whenever it changes, your FreeDV mode, whether you are transmitting (it flips when you hold PTT with FreeDV on, and back when you let go) and your message. Your callsign and grid square are public on that site. Nothing else is sent: no audio, no accounts, no settings.
• Who is on the air: the FreeDV tab lists the stations the site reports, those within 5 kHz of your frequency first (shaded), stations that are transmitting marked TX. Tune moves your radio to that station (sideband, frequency and FreeDV mode) and switches FreeDV on. Stations in a mode this program cannot decode (for example the old 700D) have no Tune button.
• Limits: with RADE V1 your callsign is also sent inside the signal (see Your callsign in the transmission above); say it by voice as usual anyway. Reports of the stations you hear (their callsign and SNR) are not sent yet. The site's protocol was taken from open-source clients, not from official documentation, so if the site changes, the link simply shows "cannot reach FreeDV Reporter" and everything else keeps working.
• The settings are in the configuration under [reporter] (enabled, announce, watch, callsign, grid_square, message).

The channels

The list on the FreeDV tab comes from the configuration (freedv.channels). The defaults are the usual FreeDV calling frequencies (160 m 1.997, 80 m 3.625 and 3.643, 40 m 7.177 and 7.197, 20 m 14.236 and 14.240, 17 m 18.118, 15 m 21.313, 12 m 24.933, 10 m 28.330 and 28.720 MHz, all in kHz as dial frequencies). Check the current activity frequencies on the FreeDV website before relying on them. Administrators can change the list in the tab (Edit the channel list): name, frequency in MHz, mode.

Settings (Admin > Config or the tab): freedv.mode (the mode used when FreeDV is switched on without choosing one), freedv.tx_level_db (-40..+3), freedv.channels.

Setting the transmit level (the level test)

RADE's transmit signal has an almost constant amplitude (the paper reports a peak-to-average ratio under 1 dB before the radio). It is meant to be sent at close to the radio's full rated power, and "more is not better" only applies beyond that: an overdriven signal is distorted and decodes badly, but an underdriven one is simply weak at the other station. A radio whose ALC barely moves (one or two bars at every setting) is underdriven.

1. Switch FreeDV on, put the radio in its FreeDV mode (DATA-U / DATA-L, or USB / LSB), and connect a dummy load (or use a free frequency). Set the radio's power to the level you want to use.
2. On the FreeDV tab tick Level test. The PTT button now sends a steady 1500 Hz tone at the modem level (it stops by itself after 15 seconds; hold again for more).
3. Hold PTT and raise Transmit level until the ALC just starts to move, then go down one step. The PO meter should be close to the radio's set power (the tone reads about 2 dB higher than the voice signal, because a steady tone has less peak than the modem's signal for the same power).
4. Untick Level test. Do not leave it on: the PTT button would keep sending the tone.

A measured example (FT-991A in DATA-USB, set to 50 W, an external power meter, the test tone): -6 dB gave 32 W and the ALC barely moved; 0 dB gave 41 W with the ALC just below its limit; +3 dB gave 42 W with the ALC at its limit. So 0 dB was the right level for that radio: the last 3 dB bought 1 W and started the overdrive. The default for a new installation is -3 dB, a safe starting point; every radio and cable is different, so run the level test. Read the external meter if you have one: the app's PO bar saturates at the set power.

The level can go up to +3 dB. If the ALC is still not moving at +3 dB, raise the radio's own input level for the USB audio instead (on an FT-991A the sound-card playback volume on the computer, or the radio's DATA/USB input gain menus) rather than turning up the level beyond that.

Notes and limits

• One FreeDV setting for the whole radio: it applies to every listener, and changing it needs control of the radio, like changing the mode.
• It is refused while the radio is transmitting.
• Voice goes through the same server-side safeguards as ever (transmit permission, control, PTT heartbeat, time limit, lock). FreeDV changes what is sent to the radio, not who may transmit.
• Operating rules: FreeDV is plain unencrypted amateur digital voice; use it only where your licence and the band plan allow it.

How much CPU does it need?

Small PCs (an Intel Atom mini PC, for example): RADE V1 receive needs about 40% of one core and the decoder has single steps of 60 to 100 ms. Such a PC also changes its CPU clock all the time (down to 480 MHz when it looks idle), and RADE's short bursts of work then run slowly. Keep the clock up with the "performance" governor, permanently:

sudo tee /etc/systemd/system/radio-remote-cpu-performance.service >/dev/null <<'EOF'
[Unit]
Description=Radio Remote: CPU governor performance
After=sysinit.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/bin/sh -c "for g in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do echo performance > $g; done"

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now radio-remote-cpu-performance.service

(undo: sudo systemctl disable --now radio-remote-cpu-performance.service). On the Atom tested the clock still swung between 1.0 and 1.9 GHz (its power limit), but the worst decoder step fell from 107 to 68 ms. RADE V2 is lighter for the decoder on such a PC (about 30% of a core, worst step 19 ms). Admin > Diagnostics shows the receive timing: the time per 20 ms frame in total and the time inside the decoder; the total must stay under 20 ms on average.

python3 scripts/freedv_probe.py (on the Pi: /opt/radio-remote/venv/bin/python /opt/radio-remote/current/scripts/freedv_probe.py) runs every installed mode as a transmit-to-receive loopback and prints the share of one CPU core each needs and its slowest single step. On a PC RADE needs about 1% to transmit and 5% to receive; on a small Intel Atom PC receive was measured at about 40% of one core.

If it does not work

SSTV (slow-scan television)

The SSTV screen (the Digital tab, then SSTV in its switch; on the all-in-one desktop layout the SSTV button in the bar under the title) receives pictures from the radio's audio and transmits a picture of your own. The Pi does the decoding and the encoding; the page only shows the picture as it arrives and prepares the one to send.

SSTV sends a still picture as a sound: the pitch of the tone is the brightness of the picture (1500 Hz black, 2300 Hz white, 1200 Hz the sync at the start of each line). A transmission starts with a short calibration header that names the mode, so the receiver knows by itself what is coming. The software is written from the published mode descriptions; nothing from other SSTV programs is used.

Modes

Robot 36 and Robot 72, Martin M1 and M2, Scottie S1, S2 and DX, PD50, PD90, PD120, PD160, PD180 and PD240, for receiving and for sending. Checked against two independent SSTV programs in both directions (their pictures decode here, and ours decode there). The time a mode takes is shown in the mode list; the usual ones are Robot 36 (37 s), Martin M1 (115 s), Scottie S1 (111 s) and PD120 (127 s).

Receiving

1. Open the screen. The radio is put on the frequency and mode of your last visit (the first time, 20 m 14.230 in data-USB) and reception is switched on. Choose a preset from the Band list or tune freely (see Tuning below). The presets are the usual calling frequencies: 80 m 3.845 LSB, 40 m 7.171 LSB, 20 m 14.230, 15 m 21.340, 10 m 28.680 USB, and the ISS SSTV events on 2 m 145.800 FM and 70 cm 437.550 FM.
2. When a header is heard the picture area starts and fills line by line, with the mode, the line count and the time left. A finished picture is saved on the Pi and appears under Received pictures: tap it to see it large, download it as a PNG, or delete it. A picture that is cut short is kept as partial when it got at least 10 % of the way.
3. Leaving the screen switches reception off and puts the radio back on the mode and frequency it had; Clear only empties the picture area. The next visit returns to the frequency, mode and step you used last.

The receiver follows the transmitter's timing line by line, so a sound card that runs a little fast or slow does no harm, and a picture right behind another one is picked up too. Signals down to about 12 dB signal-to-noise ratio (in 3 kHz) give a picture (noisy at that level); weaker ones are not recognised. The radio's filter must pass 1100 to 2300 Hz: if it is narrower, the Pi opens it (the same automatic widening as FreeDV, freedv.auto_width).

Tuning

Under the frequency display there is a Frequency box (type 437.550 for MHz, 437550 for kHz or 437550000 for Hz, then Set or Enter), - and + buttons with a step (100 Hz, 500 Hz, 1, 2.5, 5 or 10 kHz) and a Mode list (USB, LSB, FM, FM-N, AM, AM-N and the data modes the radio has). The buttons use the same tuner as the Radio tab: taps in a row add up while the radio catches up, and the arrow keys of the keyboard tune by the same step. A Squelch slider appears in the FM modes. SSTV is received in any of these modes: the presets use a data mode on the HF bands (it also skips the microphone processing when you send) and plain FM for the ISS, but nothing forces that: if you change the mode on the radio, SSTV keeps decoding.

The ISS SSTV events (437.550 MHz FM)

The ISS signal is Doppler shifted by up to about 10 kHz during a pass: it arrives high at the start (about 437.560), at 437.550 at the closest point and low at the end (about 437.540). The program does not calculate the shift: you follow it: choose the 70cm ISS preset (FM), set the step to 2.5 or 5 kHz and tap - as the pass goes on, watching the picture. Before the pass: use the wide FM mode, open the squelch (slider at open), and check that the radio sends FM audio over USB (menu 077 FM PORT SELECT = USB, see Radio connection). The Robot 36 / PD120 pictures of such events are received only: do not transmit.

Sending

1. Press Choose a picture and pick a photo or drawing from the device (any format the browser can read). Choose the mode; the preview shows exactly what will be sent, at the mode's size. Fit decides whether the picture fills the frame (and is cropped) or is shown whole with bars.
2. My callsign prints your callsign on the picture (the callsign set under FT settings in the FT8/FT4 screen), and Message adds a line of text (a report, your name, "CQ SSTV"). Text at puts them at the bottom or the top.
3. Send picture asks for confirmation and sends the picture to the Pi, which transmits it. A bar shows the progress; Halt TX stops it at once.

Sending goes through the same protection as every transmission: the transmit permission in the administration page, the control of the radio (only the page that has control can send), the heartbeat (the Pi stops at once if the page disconnects) and the transmit time limit. A mode that takes longer than the time limit is refused before anything is keyed, and the page says so (an administrator can raise safety.tx_timeout_s in Admin > Config: the default of 120 s allows Robot, Martin and Scottie S1/S2 and PD50/PD90, but not PD120 and the longer ones). The radio's ALC must stay at zero: the tones are sent at the TX level under SSTV settings (default -6 dB), and the radio's speech processor must be off. SSTV and FreeDV cannot share the radio: opening the SSTV screen switches FreeDV off.

Sound

This device's sound is off while the screen is open (the decoder works on the Pi's own audio and the tones are not nice to listen to); SSTV settings > Sound here can make it Low instead. It comes back when you leave the screen if it was on.

If no picture appears

• The radio is not on an SSTV signal, or its USB audio level is far too low or high (see Radio connection).
• The signal is too weak or has fading deep enough to lose the header; the header is the one part that must be heard cleanly.
• A header for a mode this program does not know shows a short message with its code.
• A picture is kept only if the Pi's storage works: data/sstv on the Pi holds the pictures (the last 60 by default, sstv.keep).

CW (Morse)

The CW switch on the Digital tab decodes Morse from the radio's audio into text. It also sends what you type, through the radio's own keyer.

Using it

1. Open Digital and press CW. The radio is put in a CW mode (CW-U, or the last CW mode and frequency you used on this screen) and decoding starts.
2. Pick a band, type a frequency (MHz, kHz or Hz), or step with - and +. Use the radio's own CW filter (narrow, 250-500 Hz) for the best result.
3. The decoded text appears in the Received box. Copy copies it; Clear empties it for everyone on this radio.

Leaving the screen switches decoding off and puts back the mode and frequency the radio had.

What you see

• The spectrum shows the audio between 300 and 1100 Hz; the yellow line is the pitch the decoder is following. Click the spectrum to fix the pitch there.
• Pitch and Speed are found by themselves (Auto). Untick Auto to fix either one: a fixed speed helps with very weak or irregular signals. The chip at the top right shows the speed (WPM) while a steady tone is heard.
• Sound here (under CW settings) chooses what this device plays: Off, Low or Normal. The decoder works on the Pi's own audio, so it does not need any sound here.

Sending

Under the received text is the Send box (it appears when the radio can send CW this way, as the FT-991A can). Type text and press Send (or Enter). The buttons CQ, My call, 599 and 73 send the usual short messages with your callsign (set in the FT settings of the FT8/FT4 screen). Halt TX stops at once and drops what is still waiting.

Before sending:

• The radio must be in CW-U or CW-L (the Mode box). The screen says so if it is not.
• Break-in must be on (tick it on the screen), or the radio will not transmit when it plays the text.
• You must have control of the radio, and transmitting must be allowed (safety.allow_ptt), as for any transmission. The usual transmit time limit applies to every piece.

How it works, and its limits: the FT-991A's CAT cannot send free text to its keyer, it can only play its stored keyer memories. So your text is cut into pieces (at most 24 characters, at word boundaries), each piece is written into keyer memory 5 and played, and the next piece follows when the estimated sending time is over. The text that was in that memory is read first and put back at the end. The keyer speed (the box on the screen, in WPM) is the radio's own keyer speed. This is not live typing: text is sent when you press Send. Only letters, digits and . , ? / = + - ' can be sent; other characters are dropped (the screen tells you which). The sending time is worked out from the speed, so if you turn the speed knob during a long text the pieces may overlap or have gaps: stop and send again.

An administrator can change which memory is used (cw.keyer_slot, 1 to 5) and the piece length (cw.chunk_chars, 10 to 50) in Admin > Config. This sending method has not yet been checked on a real radio: try it first into a dummy load. The same commands are used for the FTDX10, FTDX101D/MP and FT-710 profiles (their keyer commands are the same in the manuals that were read); none of them has been tried on a real radio yet.

Logging contacts

Under the text is Log a contact: callsign, the reports (599 by default), name and a comment; double-click a callsign in the received text to fill the Call box. The date, UTC time, band and frequency come from the radio. The contact goes into the same log as FT8/FT4 and RTTY, which can be exported as one ADIF file (mode CW) and uploaded to QRZ and eQSL with the buttons under Log.

How good is it?

The decoder follows any speed from about 5 to 50 WPM by itself, copes with some noise and with sending that is not perfectly even, and prints nothing when there is only noise. Like every automatic decoder it makes mistakes on weak, fading or badly timed signals (a ? marks a letter it could not read), and it cannot read two stations at once. Your ears are still better, so use Sound here when it matters.

Written from the Morse timing rules; no code from any other program is used.

The radio's menu

The Menu tab shows the radio's own menu and lets you change it from the browser: every item the radio's CAT manual lists. It is the menu you reach with the MENU key on the radio, with the same names. The FT-991A has 153 items numbered 001 to 153 as on the radio; the FTDX10 (196 items), FTDX101D and FTDX101MP (192) and FT-710 (290) have sections, groups and items, shown as numbers like 01-01-04 (section, group, item) and chosen in the Group list by section.

Using it

• Pick a group (AGC, Display, Keyer, CW mode, SSB mode, Equalizers, ...) or type in Search a name or number (beep, 026, ssb). The values are read from the radio when you open a group or search: it takes a moment. Read all reads the whole menu (about 10 seconds).
• Each item has an editor that fits it: a drop-down for choices, a slider and a number box for ranges. Pressing or releasing the control writes the value to the radio, reads it back and checks it. If the radio does not take it you are told.
• Items you change are marked changed, with an Undo button that puts back the value this page first read.
• You need control of the radio to change anything (the same as for the other controls). Everybody can look.
• Some items affect the radio's menu only; others change how the radio sounds or behaves (the audio levels, the transmit power limits, the VOX). The ones that need care show a note under the name.

Items that cannot be changed here

A few items are shown but read only, because changing them could cut the app's link with the radio or change how the radio is keyed, which the app relies on:

• the CAT and serial-socket speed, time-out and flow control;
• the PTT, keying and port selection items (PTT SELECT, RPTT SELECT, PC KEYING, REAR SELECT, port select);
• the radio ID, the time zone, text items (MY CALL, preset names) and the RTTY mark frequency, whose format the manual does not describe reliably, and any item the program does not understand well enough.

On the FT-991A these are 027 to 033, 047, 048, 060, 071, 072, 076, 077, 087, 096, 101, 108 and 109.

If you really need one of them, change it on the radio itself.

Backup and restore

Back up menu reads the whole menu and saves it as a file (menu-ft991a-DATE.json). Restore... (administrators) writes such a file back: only the items that differ are written, the items that cannot be changed here are skipped, and a report lists what was changed. Keep a backup before trying new settings: the radio itself can only do this with an SD card.

Every change, backup and restore is written to the audit log (Admin) with the old and new value and who made it. Changes are refused while the radio is transmitting.

About the table

The item numbers, names and allowed values come from the radio's CAT Operation Reference Book (the EX MENU table). The groups are ours. Where the manual has a mistake (for example the RTTY shift codes, or the digit counts of 068 and 069) the table follows what the radio does; if the radio ever answers with something the table does not expect, the item shows the raw answer with a ? and is not edited. This is new: it has been tested against a simulated radio, not yet on a real one.

The tables of the FTDX10, FTDX101D/MP and FT-710 were built the same way from their CAT manuals (the FTDX101MP uses the FTDX101D's table). The addresses of the items the app already uses (the mic source, the rear port select, the out levels) agree with what was read on a real FTDX101D. None of these four radios has been tried with the Menu tab yet.

JS8

The JS8 switch on the Digital tab is keyboard-to-keyboard messaging with JS8 (JS8Call's weak-signal mode, an FT8-style signal that carries free text): call CQ, send a heartbeat, talk to stations you hear, ask for signal reports, all from the browser. It receives and transmits.

How it works (and why it needs an install)

JS8's message coding (a word dictionary and error-correcting tables) cannot be written into this MIT-licensed program, so the JS8 modem is JS8Call-improved, a separate free program (GPL-3.0, from https://github.com/JS8Call-improved/JS8Call-improved). It is not part of Radio Remote: an administrator downloads it from its own release page with a button. It then runs on the Pi without a screen, in its own service, and Radio Remote only talks to it through its documented network interface (on the Pi itself, localhost) and connects its audio to the radio:

• Receive: the radio's audio goes into a virtual sound card (the ALSA "loopback") that JS8Call listens to.
• Transmit: JS8Call's audio comes out of the other end of the loopback and is sent to the radio through the usual transmit protection (see below).
• JS8Call never touches the radio: it has no radio control, no PTT, and its own internet reporting (PSK Reporter, APRS) is switched off.

First time (administrator)

1. Open Digital, then JS8. A box says what is missing.
2. Prepare the system (once): installs a few packages (the libraries JS8Call's toolkit needs even without a screen, and PulseAudio, started only privately for JS8Call) and loads the loopback sound card at every boot. It runs as root through a small helper, takes a few minutes, and its output is shown in the box.
3. Install JS8Call (once): downloads it (about 60 MB) from its release page and unpacks it into the Pi's data folder.
4. Set your callsign and grid in the FT settings of the FT8/FT4 screen (JS8 uses the same ones).

Supported: a Raspberry Pi 4 or newer, or a 64-bit Linux PC. The Pi uses about a quarter of one core while JS8 is on.

Using it

• Entering the screen puts the radio on the last JS8 frequency (14.078 MHz the first time) in DATA-U and switches JS8 on when everything is ready; leaving switches it off and puts the radio back as it was. Pick a band from the list (the usual JS8 frequencies), type a frequency, or step with - and +.
• Speed: Slow (30 s), Normal (15 s), Fast (10 s), Turbo (6 s) and JS8 60 (4 s, experimental). Everybody on a frequency must use the same speed; Normal is the usual one.
• TX offset: where your signal sits in the radio's audio (300 to 2900 Hz). Pick a place where nobody else is: the Band activity list shows the offset of everything decoded.
• Band activity lists everything decoded; Messages lists the messages directed at someone (yours are highlighted); heard stations are buttons: tap one to talk to it (its callsign goes into To and into the log form).
• Send: type a message, with a station in To or not, and press Send. Buttons: CQ, Heartbeat (tells the stations listening that you are here), and for the selected station SNR?, HW CPY? and 73. A message waits for the next time slot and long ones go out in several frames. Halt TX stops at once.
• Log a contact works like on the CW and RTTY screens (same log, ADIF mode MFSK with submode JS8).

Transmit protection

JS8Call only transmits what you ask for: when JS8Call reports that it wants to key the radio, Radio Remote keys it only if you pressed Send a moment ago from a page that is still connected. Anything else (for example JS8Call answering by itself) is stopped at once and reported. As for every transmission you need control of the radio, transmitting must be allowed (safety.allow_ptt), and the transmit time limit, the heartbeat and the release when your page goes away all apply. The radio must be in USB, LSB or a data mode. FreeDV, SSTV, CW and RTTY cannot be used at the same time.

TX level, dB (JS8 settings, administrators) sets the level of JS8Call's audio sent to the radio; its output is at full scale, so the default is -14 dB. Keep the radio's ALC at zero.

Limits

• Messages are the ones JS8Call can send (letters, digits, punctuation); automatic replies, heartbeat networking and relaying of other stations' messages are not used.
• JS8Call-improved version 3.0.3 is the one this was built and tested with. It needs glibc 2.38 or newer (Debian 13, Ubuntu 24.04); on older systems such as Debian 12 the Install button fetches version 3.0.2, which has the same network interface.
• New: tested with a simulated radio and with JS8Call's own audio through the loopback, not yet over the air.

RTTY (radio teletype)

The RTTY switch on the Digital tab decodes radio teletype into text and sends what you type. RTTY is two audio tones (mark and space) a fixed shift apart, sending 5-bit Baudot characters at a fixed baud rate. The usual amateur setting is 45.45 baud and 170 Hz shift, which is what the screen starts with. It is sent and heard as audio in a USB (or data) mode, not with the radio's own RTTY modes.

Using it

1. Open Digital and press RTTY. The radio is put in USB (or the mode and frequency you last used on this screen) and decoding starts. Leaving puts back what the radio had.
2. Pick a band (the usual calling frequencies), type a frequency, or step with - and +.
3. The spectrum shows the audio from 300 to 3000 Hz. The decoder looks for two steady tones one shift apart: the green line is the mark tone and the red line the space tone. Auto keeps them tuned by itself; untick it to type the lower tone in Hz, or click the spectrum to put the lower tone there.
4. The decoded text is in the Received box. Double-click a callsign in the text to fill the Call box of the log below.

Settings on the screen: Baud (45.45, 50, 75, 100) and Shift (170, 200, 425, 850 Hz) must match the other station. Reverse swaps mark and space (needed in lower sideband, or when the other station sends the other way round). USOS (unshift on space) is what most stations use: after a space the letters shift is assumed.

Sending

Type in the Send box and press Send (or Enter). The buttons CQ, My call, RST and 73 send the usual short texts with your callsign (set in the FT settings of the FT8/FT4 screen). Halt TX stops at once and drops what is waiting.

• The text is made into Baudot tones at the lower tone shown and transmitted like the FT8/FT4 and SSTV tones: you need control of the radio, transmitting must be allowed, and the usual time limit applies (a long text is cut into pieces at word boundaries, sent one after the other).
• The radio must be in USB, LSB or a data mode (DATA-U). Keep the radio's ALC at zero: set the TX level, dB under RTTY settings (administrators) so that the radio does not compress the tones.
• Only letters, digits and the usual teleprinter punctuation can be sent; other characters are dropped (the screen says which).
• The shift character is sent again after every space, so that stations with and without USOS both read the text correctly.

Logging contacts

Under the text is Log a contact: callsign, the reports (599 by default), name and a comment. The date, UTC time, band and frequency come from the radio. The contact goes into the same log as FT8/FT4 and CW, which can be exported as one ADIF file and uploaded to QRZ and eQSL with the buttons under Log (set the accounts up on the FT8/FT4 screen). The same contact logged twice within a few minutes is kept once.

How good is it?

It reads clean and moderately noisy signals at the usual speeds, follows a transmitter that is a little fast or slow, and prints nothing when there is only noise. Like any automatic decoder it makes mistakes on weak or fading signals, and it cannot read two stations at once. The first characters after tuning to a signal can be lost while the tones are being found.

Written from the published mode (ITA2 Baudot, 5 data bits, 1.5 stop bits); no code from any other program is used.

FT8 and FT4

The FT8/FT4 screen (the Digital tab, then FT8/FT4 in its switch; on the all-in-one desktop layout the FT8/FT4 button in the bar under the title) lets you listen to, call and work FT8 and FT4 stations from the browser. The Pi decodes the radio's audio in the UTC time slots (15 s for FT8, 7.5 s for FT4) and makes the transmit tones; the page shows the stations, follows the standard QSO sequence, keeps a log and can upload it.

The codec is ft8_lib (MIT licence). FT2 is not supported.

Time

Every FT8/FT4 slot starts on the UTC second, so the clock is the most important setting of all. The top bar of the tab shows the UTC time of the Pi and two indicators (hover over them for the explanation):

• NTP: whether the Pi's clock is synchronised by a time server and how far it is from it. Green = within 100 ms, yellow = more than that, red = not synchronised or more than half a second off. A Raspberry Pi with internet access does this by itself (systemd-timesyncd). Without internet access, or if the service is off, the clock drifts: sudo timedatectl set-ntp true, or install chrony.
• DT: the median time offset of the stations just decoded, that is how far they are from the start of your slot. It should stay within +-0.5 s (green); up to 1 s is yellow, more is red. It is the check that matters most: every other station's clock has been set by a time server too, so a steady DT away from zero means this Pi's clock, or the delay of the audio between the radio and the Pi, is wrong, and your own signal arrives just as early or late at the other end. The Pi's journal logs the median DT of every slot (journalctl -u radio-remote | grep "median DT").

Before the first use

1. The Pi's clock must be right. FT8 and FT4 are timed to the second: a clock that is more than about a second off decodes nothing and transmits in the wrong place. A Pi with internet access keeps its clock by itself; the tab shows Clock not synchronised when the Pi says it does not.
2. Set your callsign and grid square (FT settings at the bottom of the tab; administrators only).
3. The radio must be in a data mode (DATA-USB: DATA-U on the FT-991A). Choosing a band in the tab sets it. The radio's USB audio and data-port menus must be set as described in Radio connection (an FT-991A needs the data port menus on USB).
4. Switch the speech processor off and keep the radio's ALC at zero when you transmit: FT8 is a constant-envelope signal and compression only spreads it.

The screen

• Top bar: the radio's dial frequency, the mode (FT8 or FT4), the band and its usual FT8/FT4 frequency (choosing one sets data-USB and the frequency, and switches reception on) and RX on/off. The bar below it shows where you are in the slot (even or odd, seconds).
• All decodes: every message decoded, newest at the bottom, with the signal-to-noise ratio (an estimate in the 2500 Hz convention, good to a few dB), the time offset (DT, seconds from the nominal start) and the audio frequency. Green = a CQ call, orange = a message to you. CQ only hides the rest. Double-click a CQ to answer it (message 1 is sent in the other slot, on that station's frequency unless Hold TX frequency is ticked); double-click a message to you to continue the contact.
• Moving between screens: opening this tab sets data-USB and the last frequency used for the mode (the current band if it is an FT8/FT4 band the first time, otherwise 20 m) and switches reception on. Switching FT8/FT4 goes to the same band on the other mode's frequency. Leaving the tab switches reception off and puts back the mode and frequency the radio had before. It happens only in the page that has control of the radio. The FreeDV tab remembers the mode and frequency on entry but leaves FreeDV switched on when you leave it (switch it off yourself); once it is off, leaving the tab puts the radio back as it was.
• FreeDV: FreeDV and FT8/FT4 cannot share the radio (the FT8 tones would go through the FreeDV modem), so opening this tab switches FreeDV off if it is on, and the Pi refuses to transmit FT8/FT4 while FreeDV is on.
• Sound: this device's sound is off while the tab is open and returns afterwards if it was on; FT settings > Sound here can set it to Low instead. Other devices are not affected.
• Country: on tablets and large screens each decode also shows the country of the station that sent it, taken from the callsign with AD1C's country files (a few long names are shortened). It is a table of prefixes, so a special-event or unusual call can show the wrong or no country. Refresh the table with python scripts/build_cty.py cty.dat when a new country file is out (country-files.com).
• Directed to me / worked: the messages to you, what you transmit (red) and the contacts logged.
• Waterfall: the received audio, 0 to 3000 Hz, with the callsigns of the last two slots marked. The orange bar is your transmit frequency: click the waterfall to move it, or type it in TX ... Hz.
• Comment: every logged contact carries a comment, by default the mode and the reports as exchanged (FT8 Sent: +06 Rcvd: +01). Type your own in the Comment box (next to Erase) before the contact is logged and it replaces the automatic one in the log, the ADIF file and the QRZ / eQSL uploads; the box empties after each logged contact.
• QRZ Lookup: the button next to Reset QSO opens the QRZ.com page of the DX station (new tab; nothing is sent to QRZ before you click). On the FreeDV tab the callsigns in the station list work the same way.
• QSO messages: the six standard messages for the current DX station, editable, each with a Send button.

Calling and answering

Each slot is decoded twice: an early pass about 1.5 s before the slot ends, so the CQ calls appear while you can still answer them in the next slot, and a final pass that adds the late and weak ones (shown as "more decoded"). Double-click a CQ and message 1 goes out in the next slot of the other parity, or still in the current one if you were quick enough (up to about 1.3 s after it started: the signal is then that much late, which receivers accept). Later than that it waits for the next slot of that parity, which for FT8 can be 30 s away; the line under the controls says how many seconds are left.

1. Press Enable TX. Nothing is transmitted until it is on, and it switches itself off when the page is reloaded.
2. Call CQ sends CQ <callsign> <grid> in the slots you choose (TX even or odd) and repeats it. When a station answers, the page follows the standard sequence by itself:

3. The contact is logged when it is complete for you (you send RR73 or 73, or the last message arrives). Halt TX stops everything at once and switches Enable TX off.

The Pi repeats the current message in every slot of the chosen parity until the next one replaces it, the contact ends, you press Halt, or it has been sent Repeats times (default 6) without progress. Log QSO logs the current DX station by hand and Erase forgets it.

Transmit safety

Transmitting goes through the same protection as the PTT button: the transmit permission in the administration page, the control of the radio (only the operator who has control can transmit), the owner heartbeat (the Pi stops transmitting at once if that page disconnects) and the transmit time limit. The tones are sent at the TX level of the settings (default -6 dB); the radio's ALC must stay at zero.

The log, ADIF and uploading

Every logged contact is kept on the Pi (ftx_log.jsonl in the data folder). Export ADIF downloads all of it as a standard .adi file that any logging program imports (FT8 is its own ADIF mode; FT4 is the submode FT4 of MFSK). Under Log each contact shows what has been uploaded; Upload to QRZ / eQSL sends everything not yet sent to that service, one contact at a time. Tick Upload ... as soon as a contact is logged to do it automatically. There is no LoTW upload (it needs your signing certificate: export the ADIF and sign it with TQSL).

The accounts are entered under FT settings by an administrator and stay in the Pi's configuration file; they are never sent back to the page, and the settings backup never contains them.

These uploads were written from the services' published interfaces and tested only against stand-ins, not against the live services: the first real upload may need a small correction, so look at the message the page shows.

What it does not do (yet)

• FT2, JS8 and other modes. No DXCC or "new one" marks, no multi-pass signal subtraction (a signal hidden under a stronger one may not be decoded) and no a-priori decoding: the decoder reads down to about -19 dB signal-to-noise ratio in white noise, about 2 dB less than WSJT-X.
• One signal at a time on the transmit side, and one audio frequency per transmission.

If nothing is decoded

• Clock not synchronised or a DT far from zero on every station: the Pi's time is wrong.
• The radio is not in data-USB, or the USB audio level is far too low or too high (the waterfall shows noise but no signal columns). Set the radio's USB audio output level so that the waterfall shows the band clearly without turning white.
• Nobody is on the frequency: use a busy band (20 m, 40 m) and the standard frequency from the list.

Logbook link (Hamlib rigctl)

Radio Remote can let a logbook program on another computer follow the radio: the logbook shows the frequency and mode, and fills them into a new contact automatically. It can also change the frequency and mode when you click a spot or a bandmap entry.

It speaks Hamlib's "NET rigctl" protocol on TCP port 4532, which Log4OM, N1MM+, CQRLOG, HamRS, Ham Radio Deluxe and many others understand. The program on the other computer does not need a COM port or a USB cable: it connects to the Pi over the network.

What it can and cannot do

This is a deliberate limit: the link has no password (the protocol has none), so it can only do harmless things. WSJT-X and other programs that need to transmit through the radio are not supported by this link.

Switch it on

1. Sign in as an administrator, Admin > Config > Logbook link.
2. Tick Switch the logbook link on and press Apply. It starts at once (no restart).
3. The card now says Listening on port 4532 and shows which computers are connected.

Settings in the card:

• Let the logbook change frequency and mode: untick it for a read-only link.
• Port: 4532 is the usual one. Change it only if something else uses it.
• Allowed addresses: private (the default) means this Pi and the usual home-network ranges (192.168.x.x, 10.x.x.x, 172.16-31.x.x). Computers anywhere else are dropped without an answer. To allow one computer or a Tailscale address use a list, for example 192.168.1.40, 100.64.0.0/10.

Never forward port 4532 on your router. Anyone who could reach it could retune the radio. Keep it for the home network (or Tailscale).

Log4OM

1. In Log4OM open Settings > Program Configuration > Hardware Configuration and add a new radio / CAT interface.
2. Choose Hamlib as the interface and, as the radio model, NET rigctl (Hamlib model 2, sometimes listed as "Hamlib NET rigctl").
3. As the port / address enter the Pi's name or address and the port: ft991a.local:4532 or 192.168.1.50:4532. (Use the name shown in your browser's address bar. If .local names do not work on that computer, use the Pi's IP address.)
4. Save, then connect. The frequency and mode in Log4OM should now follow the radio; clicking a spot should retune it.

The wording of the Log4OM menus changes between versions. What matters: Hamlib, model NET rigctl, address host:4532. Other logbooks use the same three settings, sometimes under the name "rigctld" or "Hamlib NET rigctl".

From the command line (to check it)

With Hamlib installed on any computer:

rigctl -m 2 -r ft991a.local:4532 f        # prints the frequency
rigctl -m 2 -r ft991a.local:4532 m        # mode and passband
rigctl -m 2 -r ft991a.local:4532 F 7074000

If it does not work

Every frequency or mode change made through the link is written to the audit log (Admin > Audit) with the computer's address.

Remote access with Tailscale

Tailscale gives your devices a private network to the Pi without opening any port to the Internet. It is the recommended way to operate away from home. The app's own logins stay on: Tailscale is the outer wall, not a replacement.

Never port-forward the Pi. Never bind the app to 0.0.0.0.

Setup

1. Install Tailscale on the Pi (the installer can do it: --with-tailscale; or follow tailscale.com/download), then sign in once: sudo tailscale up (it prints a link to open in a browser). The Pi now appears in your Tailscale account.
2. Install Tailscale on your phone/tablet/PC and sign in to the same account.
3. In the Tailscale admin console (login.tailscale.com/admin/dns) switch on MagicDNS and HTTPS Certificates.
4. On the Pi run the setup script:

bash sudo /opt/radio-remote/current/scripts/tailscale_setup.sh

It finds the Pi's Tailscale name (<pi>.<tailnet>.ts.net), lets the HTTPS front end (Caddy) fetch a real certificate for it from Tailscale, adds the name to Caddy, checks the new configuration before using it, and tests the address. The first request can take up to a minute while the certificate is issued. --dry-run shows what it would do; --remove goes back to the LAN name only. The name is remembered in /etc/radio-remote/caddy-extra-hosts, so updates and reboots keep it. 5. Open https://<pi>.<tailnet>.ts.net from any device that has Tailscale switched on.

Why https://<pi>.local:8443, the 100.x.y.z address or a port number did not work: the HTTPS front end answers only to the names it is configured for (by default <hostname>.local) on the standard HTTPS port 443. Under any other name it has no site and gives no answer. Step 4 adds the Tailscale name. The 100.x.y.z address cannot get a certificate: use the .ts.net name.

tailscale serve is not used here: the script above (Caddy) is the tested way, and Caddy forwards X-Forwarded-Proto: https, which the session cookie's Secure flag depends on.

If the script stops with a message: "not signed in" means run sudo tailscale up; "MagicDNS" or "HTTPS Certificates" means switch them on in the admin console and run the script again; a timeout at the end means the certificate could not be issued yet: wait a minute and run it again, and look at sudo journalctl -u caddy -n 30.

Audio over Tailscale

WebRTC audio uses UDP. On a direct tailnet path it works like the LAN. On a relayed (DERP) path expect extra delay or failure. Check with tailscale ping <pi> (it says "direct" or "via DERP"). If WebRTC cannot connect, the page switches to WebSocket audio by itself (Audio tab > Connection; see audio).

Hardening checklist

• Tailscale ACLs: allow only your own devices/users to reach the Pi on port 443.
• Keep the Pi's firewall rules from 06-security-remote.md.
• Use strong, unique passwords; give family/guests viewer accounts.
• Optional: Tailscale "key expiry" and device approval so a lost phone can be cut off.

Security and remote operation (Phase 8)

The system can transmit RF on your licence, so security has two jobs: keep strangers out, and make sure a bug, a flaky network or a second user can never leave the transmitter keyed or in the wrong hands.

Who can do what

Control lease (many watch, one controls)

• Only the connection that holds the lease may change the radio, key PTT, or have its mic audio reach the radio. Everything else is rejected on the server, whatever the browser does.
• The first operator/admin to connect to a free lease gets it. Others see who has control and can Request control.
• Different user asks: the holder gets a Hand over / Keep control prompt. No answer within safety.control_request_timeout_s (default 10 s, 3-120): control passes automatically, so an unattended session never blocks anyone.
• Trusted users (set by an admin in Admin > Users, "Trusted"): their request is granted immediately, with no prompt. The previous holder is told who took over. Trust applies to operators/admins only (a viewer can never hold control), it takes effect on the user's next request without a reconnect, and revoking it is equally immediate. Changing the flag does not sign the user out.
• Same user on another device: immediate hand-over.
• Never during transmission. A request while the transmitter is keyed is refused (an unanswered request waits until PTT is released). When control moves for any reason, the previous holder is un-keyed first.
• Admin Force takes control at once and un-keys first.
• A disconnect frees the lease and un-keys.

What is enforced where

Not done, deliberately or for now:

• No per-session IP binding, no 2FA, no password-expiry or complexity rules beyond length.
• No WebSocket one-time ticket: SameSite=Strict plus the Origin check cover cross-site hijacking.
• The audit log is not tamper-evident (an admin can read it; someone with file access can edit it).
• TLS is not terminated by the app. Use the proxy below.

Network layout

Internet  X  (never port-forward this)
LAN / Tailscale ---> Caddy :443 (TLS) ---> app 127.0.0.1:8080 ---> radio (USB)

• Keep server.host = "127.0.0.1". The app trusts X-Forwarded-* headers only from a loopback peer; binding it to 0.0.0.0 behind a proxy would let anyone on the LAN spoof their address and "Secure" status.
• Why HTTPS matters: browsers only expose the microphone on HTTPS (or localhost). Without it you can listen but not transmit audio.

Recipe A - LAN with Caddy's internal CA

1. sudo apt install caddy, copy config/Caddyfile.example to /etc/caddy/Caddyfile (Option A), sudo systemctl reload caddy.
2. Each phone/tablet/PC must trust Caddy's root certificate once. The root is at /var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt on the Pi (the path can differ between Caddy installs; the installer pack and the image also publish it for download). iOS additionally needs it enabled under Settings > General > About > Certificate Trust Settings.
3. Browse to https://raspberrypi.local.

Recipe B - Tailscale (preferred for remote use)

1. Install Tailscale on the Pi and on your devices, sudo tailscale up. Enable MagicDNS and HTTPS certificates in the admin console.
2. Run sudo /opt/radio-remote/current/scripts/tailscale_setup.sh: it adds the Tailscale name to Caddy (verified on a real Pi). Step by step in tailscale. tailscale serve is not used: Caddy forwards X-Forwarded-Proto: https, which the session cookie's Secure flag needs.
3. Keep application logins on. Tailscale is the outer wall, not a replacement for accounts.
4. WebRTC audio uses UDP; over a direct tailnet path it is fine, over a relayed (DERP) path latency rises. The UI will tell you if audio cannot connect; a WebSocket-audio fallback is not built yet.

Firewall (optional, recommended)

sudo ufw default deny incoming
sudo ufw allow in on tailscale0
sudo ufw allow from 192.168.0.0/16 to any port 443 proto tcp   # your LAN range
sudo ufw allow from 192.168.0.0/16 to any port 22 proto tcp
sudo ufw allow from 192.168.0.0/16 to any port 4532 proto tcp  # only if you use the logbook link (docs/logbook.md)
sudo ufw enable

WebRTC audio selects ports dynamically; with deny incoming allow UDP from your LAN/tailnet interfaces as well (not verified against a real firewall yet).

Operating notes

• First run: the first visit creates the administrator. Do this on the LAN, not over a forwarded port.
• Enable PTT: Admin > Config > Transmitting (PTT) (administrator password required), or set safety.allow_ptt = true in the config file and restart. It is off by default and every change is in the audit log.
• Lost admin password: python -m radio_remote.cli reset-password <user> on the Pi.
• Backup: the config file and data/radio-remote.db (users, sessions, audit).
• Radio-side backstop: set the radio's own TX time-out (menu 036 on the FT-991A) as the last line of defence.

What has been tested

Automated (222 tests, mock radio and simulated CAT): lease transfer / deny / timeout / force / refusal while keyed, heartbeat and disconnect un-keying, role enforcement, rate limiting, user management and last-admin protection, session revocation, config allow-list and validation, audit contents, secret scrubbing, HSTS / cookie flags, recovery CLI. In a real browser: admin sheet (users, clients, config, diagnostics, audit, account), request dialog and hand-over between two users, watching-mode lock-out of dial and PTT.

Not tested: TLS in front of the app (Caddy / Tailscale), real phones/tablets, behaviour behind a real firewall, several simultaneous audio listeners on a Pi.

Troubleshooting

First step for almost everything: sudo /opt/radio-remote/current/scripts/doctor.sh (or Admin > Diagnostics), then journalctl -u radio-remote -n 100 --no-pager. Paste the doctor output when asking for help; it contains no passwords.

Radio not detected ("radio offline", "no FT-991A found on any USB serial port")

1. lsusb: is there a Silicon Labs CP210x entry? No: cable, radio power, try another Pi USB port, avoid unpowered hubs.
2. ls /dev/serial/by-id/: do ports exist? No: kernel did not create them (check dmesg | tail).
3. Is the radio on (not standby)? CAT does not answer in standby.
4. radio.model must be ft991a, not mock (Admin > Config).
5. Detection tries 4800/9600/19200/38400. If it still fails, the radio's menu 031 CAT RATE may not match any, or another program holds the port.

CAT not responding / timeouts

• Another program is using the port (sudo fuser -v /dev/ttyUSB*, check ModemManager: systemctl status ModemManager; the installer's udev rule tells it to ignore the radio, re-plug the cable after installing).
• Baud mismatch: set radio.baud to the radio's menu 031 value.
• Raise menu 032 CAT TOT. Check the cable and avoid long unshielded runs near the transmitter (RF in the USB cable can corrupt CAT; ferrites help).
• journalctl -u radio-remote | grep -i cat shows reasons ("radio stopped answering", "unexpected radio ID").

Wrong serial device

The FT-991A exposes two serial ports; the app picks the one that answers ID; with 0670. Force one with radio.serial_port = "/dev/serial/by-id/usb-Silicon_Labs_...-if00-port0" (stable across reboots, unlike ttyUSB0/1). "unexpected radio ID" means a different radio model answered on that port.

USB audio missing

arecord -l / aplay -l must list the radio's codec. If not: cable/power as above; the audio device appears only while the radio is on. Several codecs present: set audio.input_device and audio.output_device explicitly (the UI says "several USB audio CODECs found"). Make sure the service user is in group audio (id radio-remote) and that you use Raspberry Pi OS Lite (a desktop session's PipeWire can hold the device; check with fuser -v /dev/snd/*).

No RX audio

• Click Listen (browsers need a click). Check volume slider and the "RX audio" meter: moving meter but silence = browser/volume; flat meter = nothing arriving from the radio.
• Server side: Admin > Diagnostics > Audio: rx_capture, capture_error.
• Test the sound card directly: arecord -D plughw:CARD=CODEC,DEV=0 -f S16_LE -r 48000 -c 1 -d 5 /tmp/rx.wav && aplay /tmp/rx.wav with a signal on the radio.
• The radio's menus decide whether USB audio carries receive audio (radio-connection.md).
• Plain http:// pages can listen; if audio cannot connect at all, try Audio tab > Connection > WebSocket (TCP); otherwise check browser console for WebRTC errors and that UDP is not blocked between you and the Pi (VPN relays can add delay).

No TX audio

• Needs HTTPS (microphone is blocked on plain http), a microphone permission grant, an operator account, and control (the bar must say "You have control").
• Audio only reaches the radio while you hold PTT. Watch "TX audio (to radio)": it stays 0 until PTT is held and allow_ptt is true.
• Radio side: transmit audio source menus (070/072/106/109...), data/mic gain; with a dummy load adjust audio.tx_gain_db and the radio's out-level until ALC barely moves.

PTT does not work

1. The button says "PTT DISABLED IN CONFIG": an administrator enables it in Admin > Config > Transmitting (PTT) (password required), or sets allow_ptt = true in /etc/radio-remote/config.toml and restarts.
2. "Request control first" / "X has control": take control (control bar).
3. Radio offline, or "radio did not key": check CAT first.
4. Released too soon: PTT is hold-to-talk; it un-keys if the page loses focus, the tab is hidden, the network drops (heartbeat 1 s), or after safety.tx_timeout_s.
5. The radio's own menu 036 TX TOT may also be cutting you off.

CAT reconnect problems

Unplug/replug and radio power-cycle should recover within a few seconds. If the status stays offline: look for "CAT session ended" in the log; confirm the port name did not change (use by-id); sudo systemctl restart radio-remote. After a radio power cycle, the radio forgets auto-information; the app re-enables it on reconnect (log: "FT-991A connected").

Browser cannot connect

• Is the service up? systemctl status radio-remote, curl -s http://127.0.0.1:8080/api/status on the Pi.
• Is Caddy up? systemctl status caddy, journalctl -u caddy -n 30. Does the name resolve (ping radio.local; some Windows/Android setups lack mDNS: use the Pi's IP and --hostname)?
• Certificate warning: trust Caddy's local CA once per device (06-security-remote.md), or use Tailscale.
• Login page loops / "origin not allowed": you reached the app through a name the proxy did not pass on; add it to server.allowed_origins.
• "too many attempts": wait; lock-outs are per address and user.
• Port 8080 is loopback-only on purpose; use the HTTPS address.

Tailscale connectivity

• The Pi shows up in Tailscale but the page does not open (no answer, any port): the HTTPS front end does not know the Tailscale name yet. Run sudo /opt/radio-remote/current/scripts/tailscale_setup.sh (tailscale.md).
• tailscale status on both ends; tailscale ping <pi> shows direct vs relayed (DERP) path.
• HTTPS names need HTTPS certificates enabled in the Tailscale admin console.
• Audio over a relayed path is laggy or fails (WebRTC uses UDP): the page falls back to WebSocket audio by itself after about 9 seconds (Audio tab > Connection; "(WebSocket)" shows in the status line). A direct path is still best.
• If the page loads but the session cookie is not Secure / mic is blocked, the proxy is not forwarding X-Forwarded-Proto: https: use the Caddy variant (tailscale.md).

Service will not start / keeps restarting

journalctl -u radio-remote -n 100. Common: a typo in config.toml (the error names the key); missing Python packages after a failed update (sudo /opt/radio-remote/venv/bin/pip install -r /opt/radio-remote/current/requirements.txt); status=...WATCHDOG means the app hung (please send the log).

Start over

sudo scripts/uninstall.sh (keeps data) then sudo ./install.sh; or --purge for a completely clean slate.

Mic armed but "To radio: 0 frames"; log says "Unknown PCM 6"

The server could not open the radio's sound card for transmit: audio.output_device holds something that is not an ALSA device name (for example a bare card number 6). Leave Admin > Config > Pi -> radio (playback) empty (auto-detect) or set plughw:CARD=CODEC,DEV=0 (see aplay -l), save, restart the service. A bare number is now rejected when saving, and the Audio tab shows "Audio to the radio failed: ..." when the playback device cannot be opened.

Other radios: FTDX101D (tested), FTDX101MP (same commands), FTDX10, FT-710

These four profiles were written from the Yaesu CAT manuals (FTDX10 2308-F, FTDX101MP/D 2101-I, FT-710 2306-C). The app shows an amber EXPERIMENTAL PROFILE banner whenever one is selected whose capability file says bench_tested = false (the FTDX10 and FT-710; the FTDX101D was tested on a real radio, and the MP, which has the same commands, shows no banner either).

• FTDX101D: tested on a real radio (2026-10-05, Raspberry Pi 4, USB), see the next section for what works and what the manual gets wrong. Not everything is tried yet (transmitting on the SUB receiver, the MP variant).
• FTDX101MP: same CAT commands as the D (one shared manual), so its profile is enabled exactly like the D's, with transmit power 5 to 200 W (the D: 5 to 100 W). No MP has been available here, so please report anything that differs; the first owner to try it should follow the checklist below.
• FTDX10 and FT-710: still only on paper. Nothing there has been seen working on a real radio.

FTDX101D: what was verified on a real radio

Connection. The radio has a dual CP210x USB bridge: the Enhanced port (usually /dev/ttyUSB0) is CAT. Set, on the radio, CAT RATE 38400, CAT TIME OUT TIMER to a long value and CAT RTS = OFF. With CAT RTS on, the radio only answers while the computer holds RTS high, and this program keeps RTS low on purpose (RTS can key a transmitter, and the Standard port may be set to use it for the CW keyer or PTT), so it would stay silent: the app then says "radio offline". The ID is 0681; the radio's CAT port answers at the rate set in the menu only.

MAIN and SUB receivers. FA is the MAIN receiver and FB / OI the SUB receiver (the radio's VFO-A and VFO-B). The app shows them as MAIN and SUB. Instead of the VFO copy / swap buttons it has:

• a MAIN | SUB selector (VS0; / VS1;: the receiver the radio's own dial and keys operate; follows the radio's MAIN / SUB keys),
• RX buttons (FR P1 P2, 0 = listening, 1 = muted; at least one stays on) and TX buttons (FT2; MAIN / FT3; SUB; the answer to FT; is 0 / 1). Listening to one receiver and transmitting on the other is split,
• MAIN ↔ SUB swaps the two frequencies, Set MAIN frequency and Set SUB frequency sit side by side in Band select.

The rear / USB audio carries one receiver at a time, chosen per mode family by the menus SSB / AM / FM / DATA / RTTY / CW OUT SELECT (EX010108, EX010208, EX010308, EX010410, EX010510, EX020108; 0 = MAIN, 1 = SUB). When only one receiver is listening the app sets all six to that receiver; when both listen it leaves them alone. Changing receivers on the radio's own panel does not change them.

Controls (Filters & DSP panel; a MAIN | SUB switch at the top makes the per-receiver ones act on the chosen receiver, set_control carries receiver):

Levels: RF gain and AF gain exist per receiver (RG0 / RG1, AG0 / AG1). AF gain is only the radio's own speaker volume (the app does not use it for remote audio); all 0-255 gains are shown as 0-100 %. TUNE works (AC002;, keys the transmitter: dummy load or antenna, the app asks first). Memories are listed, recalled (MC) and left with the radio's V/M key (VM;); nothing is ever written.

Where the manual is wrong or unclear on this radio

• Speech processor (PR): the manual says 1 = OFF / 2 = ON. The radio uses 0 = OFF, 1 = ON (PR0 the processor, PR1 the parametric mic equalizer) and rejects PR02; with ?;. The processor level is PL.
• The radio's PROC / PITCH knob sets the AMC output level (AO, 1-100), shown on the radio as "AMC out", unless the menu OPERATION SETTING → TX AUDIO → PROC LEVEL is set to COMP; then it sets the processor level (PL). The processor on / off is the MIC / SPEED knob (press).
• SD (break-in delay) is answered with two digits (SD04), not the four digits the manual shows, so it is not offered.
• GT answers AUTO as 4, 5 or 6 (AUTO-FAST, -MID, -SLOW); the app shows AUTO.

Not tried yet: transmitting on the SUB receiver on the air, the DATA / RTTY / CW audio-source menus with a signal, and the MP.

How a model is selected

radio.model (Admin > Config > Radio > Model, restart needed) picks, for that model:

1. its capability file (radio/capabilities/<model>.toml): which functions the UI offers (only true entries; "unverified" is hidden);
2. its protocol object (radio/cat/proto.py): the exact commands, answer layouts, mode codes, width tables, level ranges and the menu (EX) items for that radio. The FT-991A keeps its own, bench-verified protocol object; the four newer radios share one (HfProto) whose per-model differences are plain data (HfModel).

The driver (YaesuCatDriver) never builds a command itself, so an FT-991A command can never reach another radio, and the ID answer (ID0761; FTDX10, ID0681; FTDX101D, ID0682; FTDX101MP, ID0800; FT-710) is checked on every connect: a different radio is refused.

What is the same as the FT-991A and what is not (from the manuals)

Same: FA FB (9 digits, 30 kHz-75 MHz), IF/OI layout (25 characters), TX0/1, AG0 RG0 (0-255), MG (0-100), PC (5-100 W, 5-200 W on the FTDX101MP), SM0, RM selectors (3 COMP, 4 ALC, 5 PO, 6 SWR), NA NB NL NR RL BC BP CO PA ML AC formats, BS band codes 00-10, AB BA SV, PS (dummy data, then PS1 after 1-2 s), RT XT RU RD RC (not on the FT-710).

Different (and handled by the protocol object):

What is deliberately NOT offered yet ("unverified" in the capability file)

This list is for the radios that have not been tried (FTDX10, FT-710); the FTDX101D (and the MP, which uses the same commands) have these enabled as described above.

• Speech processor (PR/PL): the manual says PR 1 = OFF / 2 = ON, which is wrong on the FT-991A and on the FTDX101D (it is 0/1). Verify on the radio first.
• TUNE (tuner_tune): it keys the transmitter. Enable it only after a dummy-load test, by setting tuner_tune = true in the model's toml.
• Split (ST) on the FTDX101: the TX buttons (FT) cover the MAIN / SUB case; the radio's own VFO-A / VFO-B split inside one receiver is not offered.
• FT-710 clarifier (only the CF command is in its manual) and quick split (no QS).
• APF (CW only, did nothing on the FT-991A) and C4FM / DG-ID (FT-991A only).
• Roofing filter (RF), the spectrum scope, CW message keying (KY, it transmits), VOX, the break-in delay: not implemented.

Practical notes

• Two serial ports. The radios have a Dual CP210x bridge: the Enhanced COM port is CAT, the Standard one is PTT/keying. Auto-detect probes every Silicon Labs port with ID; and keeps the one that answers; if it picks wrongly, set radio.serial_port explicitly. The "Power on radio" button also needs the CAT port: set radio.serial_port explicitly for these radios.
• Baud. Set the radio's CAT RATE menu and radio.baud to the same value (38400 is the app's default). If the radio does not answer at all, check its CAT RTS menu (it must be OFF, see the FTDX101D section); the log then says which ports and rates were tried.
• Receive audio level to the Pi (USB OUT LEVEL menus, 0-100): FTDX10 EX010111 (SSB OUT LEVEL); FTDX101 EX010109; FT-710 EX010111 (USB OUT LEVEL); on the FTDX101D the app has an Audio out level slider for it. Raise it on the radio instead of boosting audio.rx_gain_db. Transmit audio over USB also needs the radio's REAR SELECT = USB menu (FTDX10 EX010114, FTDX101 EX010112) and, on the FT-710, MOD SOURCE = USB.

First contact checklist (do it in this order, report each step)

1. Stop the service, run the read-only script and keep the output: python scripts/bench_hf_readonly.py ftdx10 # or ftdx101d / ftdx101mp / ft710 Every line shows the command, the radio's answer and what the decoder made of it. A ?; or a "(decoder: ...)" note is exactly what to fix.
2. Start the service with radio.model set, check the banner, the frequency, mode, band and the S-meter.
3. Change frequency, mode, band; switch NB / DNR / notch / contour; try the AGC, ATT and IF-shift controls.
4. Into a dummy load: PTT (a short key-up), meters (power, SWR, ALC), mic source REAR / MIC.
5. Only then consider TUNE, the clarifier, split and the speech processor.

Every function confirmed this way should be written into docs/bench-results.md and the capability toml flipped to bench_tested = true.

What each radio supports

The FT-991A and the FTDX101D are tested on real radios (the FTDX101MP has the same commands as the D). FTDX10 and FT-710 are experimental: their profiles were written from the radios' CAT manuals and tested only against a simulator, and the page shows an "experimental" banner. See other radios for what to check first if you have one.

How to read the table:

Functions

Modes, bands and frequency range

Levels

Not available on any of them (over CAT)

• C4FM RX/TX DG-ID: not reachable over CAT (checked on a real FT-991A: no menu value changes). Only the WIRES DG-ID menu value is read.
• Antenna selection: the FT-991A has no CAT command for it.
• VOX is deliberately not offered: VOX plus remote audio is a risk of unintended transmission.
• Memory writing: the program reads and recalls memory channels but never creates, changes or deletes one.

Where each status comes from: the capability files in backend/radio_remote/radio/capabilities/; the results of the real-radio tests are in bench results.

UI

No build step. Plain ES modules, served as static files; the Pi never needs Node.

frontend/
  index.html  style.css  manifest.webmanifest  sw.js  icons/
  src/
    main.js  api.js  audio.js  tuner.js  util.js  meter-cal.js
    pages/    login.js  radio.js  admin.js
    components/
      freq-display.js   LCD-style frequency; tap a digit = tuning step, wheel over a digit tunes by it
      vfo-b.js          VFO B readout, swap / A=B / B=A, SPLIT, quick split, set B
      dial.js           small round dial (tablet/desktop): drag, wheel, arrow keys; Fine / Coarse x10
      tuning-strip.js   sliding tuning ruler (phones): swipe, flick, x10
      meters.js         coloured segment meters: S-meter, power, SWR, ALC, COMP
      controls.js       colour-coded chips, level sliders, and the filter/DSP panel as tabs per group (Filter, Noise,
                        Receiver, Transmit; last tab remembered). All generated from the radio's capabilities
      ptt.js            hold-to-transmit, heartbeat, TX timeout bar

Layouts

The radio's CAT meters are raw 0-255 values and the manual gives no calibration. So:

• S-meter: bar and "S9+20" readout use the table S_TABLE in src/meter-cal.js: raw -> dB relative to S9, in the style of the Hamlib calibration for this radio family. It is an approximation, not measured on your radio (the label says "approx. scale"). S0-S9 fill 60% of the bar like a real meter, S9 to +60 dB the rest. Colours: blue, cyan, green up to S9, yellow and orange above, red for strong signals.
• ALC and COMP: shown as 0-100%, blue/green when low, yellow near 45-50%, red above 50%. 100% means the raw value set in Admin > Config > Meters (ui.meter_alc_full, ui.meter_comp_full). The ALC default is now 160: with normal speech into a dummy load the radio's ALC meter showed about 50% when the raw peak was 79, so 100% ~ 158 (one data point, assumes a straight line); adjust it so the app's bar matches the radio's own meter. The COMP default (255) is a placeholder: no data yet.
• Power / SWR: still raw (labelled "raw") on a real radio, because no calibration exists; coloured green / yellow / red.

To calibrate properly (bench 5 in 03-bench-checklist.md): feed known signals (S-meter), and compare against the radio's own meters and a wattmeter (power, SWR, ALC).

Tuning behaviour

• One set_frequency is in flight at a time; the newest target wins. The display shows the target while tuning and returns to the radio's own reported frequency shortly after (the radio is authoritative).
• Tuning is clamped to the coverage range you are in (no jumping across gaps).
• Phones: swipe the strip left = frequency up, right = down (9 px per step), a flick keeps gliding; the ×10 button switches coarse. Tablet/desktop: the dial (clockwise = up), mouse wheel, arrow keys, PageUp/PageDown = ×10. The Coarse switch is shared.

Honest limits

• Tested in a desktop browser at 375, 768 and 1280 px widths with mouse and synthetic touch-like events. Real iPad/iPhone/Android touch (including strip momentum feel), vibration, wake lock and PWA install are untested.
• Installing as a PWA and the microphone need HTTPS (or localhost).

PWA

manifest.webmanifest + sw.js (network-first shell cache, never caches /api or /ws) + generated icons (python tools/make_icons.py). Static files are served with Cache-Control: no-cache; an open page shows a "Reload now" banner when a new version has been installed under it.

Device detection: src/main.js sets data-tablet on the page when the screen has no hover (touch) and is 700 px or wider. To force a mode open the page with ?device=tablet, ?device=desktop or ?device=auto (remembered per browser).

Changes after the first field tests

• Tune sits next to the tuning step. The old "Receiver & tools" chip row is gone: every toggle exists in Filters & DSP, where an on/off button and its adjustment bar (DNR + level, NB + level, notch + frequency, contour + frequency, processor + level, monitor + level) now share one row.
• APF (audio peak filter, CW only) is not offered on the FT-991A: it did nothing on the bench.
• Listen / Mic are speaker and microphone icon switches at the top right of the VFO A panel (teal = on). Only the user switches them: the audio engine survives page rebuilds and reconnects, and re-connects by itself while Listen is on (screen lock, background, server restart). The browser's media session is set so the OS shows the page as playing audio. A browser may still suspend a page in the background (iOS Safari in particular); that cannot be overridden from a web page.
• Big screens now use the tablet layout (tabs Radio / Filters / Audio & Levels / Digital, compact controls, centred, max 1240 px). Open the page with ?device=desktop to get the old all-in-one page back in a browser (remembered); ?device=auto resets it. Manual notch and auto notch (DNF) moved to the Noise tab of Filters & DSP.

• Aligned rows: every control in Filters & DSP, every level and every audio meter is one row [button or label | bar or select | value] (two columns of rows on wide screens). RIT and XIT are two buttons on one row with the shared clarifier offset bar (double-click the bar to clear it). The offset bar range is now +-9990 Hz in 10 Hz steps: the old -9999..+9999 range produced values such as 201 Hz that the server rejects (must be a multiple of 10), which is why the clarifier "did nothing". On the FT-991A, setting an offset while neither RIT nor XIT is on also switches RIT on (RU/RD only move the clarifier knob). NOT bench-verified yet.

• Audio devices: Audio tab, "Speaker / output" and "Microphone / input" lists (this browser only, remembered): choose a Bluetooth headset or a car hands-free kit. Output selection needs setSinkId (Chrome, Edge, Android Chrome); Safari/iOS cannot choose it, there the system sound settings decide. Device names appear after the microphone was allowed once. If the chosen microphone is gone, the default one is used.

• The REAR/MIC selector was removed from the PTT area: the microphone button in the VFO panel arms the mic and sets menu 106 to REAR (off = MIC).

• VFO A: the band text ("20m") sits next to the mode ("USB") under the frequency. VFO B: [VFO-B] [TX] [SPLIT] [mode] [band] ... frequency with the frequency right aligned. The VFO B mode comes from OI; (opposite band information, manual p.14, read only; same layout as IF;), polled with the other VFO B reads. Bench-verified. (Earlier notes saying VFO B has no mode were wrong.) VFO B still has no S-meter. The Tune button has more space from the tuning step buttons.

• Radio meters (raw) row on the Audio tab: live raw 0-255 ALC, COMP, power, SWR and S-meter values, plus the peak ALC and COMP of the last transmission (reset at each new key-down). Used to calibrate the percentage scales (ui.meter_alc_full, ui.meter_comp_full).

• PTT on every tab (Radio, Filters, Audio & Levels, and Digital for FreeDV), pinned at the bottom above the tab bar, so levels and audio can be adjusted while transmitting. A long note on the Audio tab (device names hint) no longer widens the page: the page used to grow wider than the screen and push the tab bar out of view.

• AGC (Receiver tab of Filters & DSP): OFF / FAST / MID / SLOW / AUTO via GT0 (documented in all four manuals). The radio answers AUTO as AUTO-FAST / AUTO-MID / AUTO-SLOW (4 / 5 / 6); the app shows them all as AUTO. Offered on the FT-991A too; NOT bench-verified yet. ATT is a four-step list (OFF / 6 / 12 / 18 dB) on the newer radios. See docs/08-other-radios.md.

• Memory channels (FT-991A and FTDX101D): the Memories button, beside Tune in the tuning step row, opens a list of the radio's stored channels (001-099: number, tag, frequency, mode) with a filter box; tap one to recall it. While the radio is in memory mode a purple MEM 005 badge shows in the VFO A header and a Back to VFO button appears (it sends VM;, the radio's V/M key, which is a toggle, so it is only sent while in memory mode). The list is read with MT ccc; (the READ form, which also returns the tag) and cached by the server; Re-read reads it again after you changed memories on the radio. Recall is MC ccc;. Export saves the list as a CSV. Add / Edit (FT-991A, administrators; capability memory_edit) writes one channel with the WRITE form of MT (MT ccc + frequency + +0000 + clarifiers off + mode + 0 + tone mode + 00 + shift + 0 + 12-character tag, manual p.11); the frame is checked first (channel 1..99, frequency range, known mode, ASCII name of at most 12 characters) and matches the layout the radio itself reports. Because a real FT-991A answers every MT read with channel 001 in P1, a write is never trusted: the whole list is read before and after, the channel must read back as written (only the frequency may be rounded to the radio's step) and no other channel may have changed; if one did, editing is switched off until the service restarts. Endpoint POST /api/memories/{channel} (administrators, CSRF token, confirm: true, refused while the radio transmits, audited as memory_write). Bench findings (FT-991A, 2026-10-08): the MT write has no tone-number field, but the radio stores, per channel, the tone number (CN00 CTCSS 000-049, CN01 DCS 000-103) that VFO-A holds at the moment of the write; so for a channel with a tone the driver sets VFO-A (mode, frequency, OS0 shift in FM, CT0 tone mode, CN00/CN01), writes the channel, recalls it and reads CN00/CN01 back, then puts VFO-A, its own shift/tone settings and the V/M state back. GET /api/memories/{channel}/tone returns what a stored channel holds (it recalls the channel and puts the radio back); the editor uses it so that editing a name keeps the tone. Deleting: recall the channel (checked against IF), then AM; (VFO-A TO MEMORY CHANNEL) empties it (POST /api/memories/{channel}/delete); proved the same way as a write, and AM is never sent unless the recall took. Not offered: the repeater offset (a radio menu setting). Channels 100-117 (the PMS ranges P-1L..P-9U) are not listed. Empty channels are skipped (the radio answers ?;). Bench finding (FT-991A on a Raspberry Pi): the answer to MT ccc; always says channel 001 in its P1 field while carrying the data of the channel asked for. The server therefore accepts the next MT answer as the reply to its own question and takes the channel number from the request. A channel that stays silent is retried once, then tried with MR ccc; (read without tag), then skipped; the list read only fails after four silent channels in a row. The status answer IF reports the recalled channel correctly.

• Status lights in the VFO A header, after RX / TX / MEM: one preamp light whose text is the setting in use (IPO, AMP1 or AMP2, from PA0;), ATT (RA0;, or the ATT step of the newer radios), one AGC light whose text is the setting (GT0;: AGC OFF / FAST / MID / SLOW / AUTO; dark while OFF) and TUNER (AC;; blinks amber while tuning). Green = active, dark = inactive; they appear only for functions the radio profile has. Read-only: they mirror the state the server already polls. On phones (< 700 px) they wrap onto their own row. Each light can be hidden per device (Account > Display, kept in localStorage as rr.lights; the header closes up when all are off).

• SWR warning: ui.swr_warn (default 3.0, 0 = off). While tx and the SWR is at or above the limit the SWR bar is drawn fully red and a line "High SWR: x.x:1" appears under the meters; it is kept 5 s after the transmission and a new transmission starts a new reading. Radios that report a ratio (swr) are compared directly; the FT-991A reports swr_raw (0..255, RM6), turned into an estimated ratio with 1 + 2 * raw / ui.swr_raw_at_3 (PROVISIONAL, default 100 = "3:1"; the manual has no calibration, set it from the radio's own meter). The limits are delivered in the hello message (ui.meter), so a change needs a restart like the ALC/COMP calibration.
• Memory list pre-read: a few seconds after the radio connects (Timings.prefetch_s, 4 s) the server reads the 99 channels in the background, so Memories opens at once. The cache is dropped and re-read on every reconnect.
• Settings backup (Admin > Config): GET /api/admin/backup returns the config as a .toml download; POST /api/admin/restore applies the settings the web UI may change (EDITABLE) and ignores the rest (never server.*, storage.*, safety.allow_ptt).
• New release notice (administrators): after sign-in the page asks GET /api/admin/update; when newer is true and that version was not dismissed (localStorage rr.updateSeen) a bar offers What's new (the release page), How to update (opens Admin > Config > Updates, which shows the self_update.sh command) and Dismiss. The server asks GitHub once a day (updates.py; updates.check, updates.repo; the simulated radio never does); Check now in the Updates card asks at once. Nothing is installed from the page.
• Hands-free (latched) transmit: the TX LOCK button beside HOLD TO TRANSMIT latches a transmission with one tap (Locked on - tap TX LOCK or the button to stop); it shows STOP while latched, and a tap on TX LOCK or on the big button un-keys. (The earlier slide-up gesture is gone.) HOLD TO TRANSMIT still transmits only while held. The heartbeat keeps running, so the server still un-keys on silence, disconnect or the time limit; the page also releases when it becomes hidden or the transmission ends. The Lock PTT button still blocks starting one.

• Lock (screen lock): a round padlock button beside HOLD TO TRANSMIT. While on it locks the WHOLE screen of this device: the PTT button, TUNE and every other control, the top bar and the tabs are inert (no touch, click, wheel or key press reaches them; scrolling still works) and only the padlock stays live. This device only (remembered in localStorage as rr.pttLock; a running transmission can still be released, and locking while PTT is held releases it). It is a client-side convenience against stray touches; the server-side safeguards are unchanged.

• Top bar on phones shows icons only (labels from 700 px up). The radio tab shows only a status dot: green = radio online, yellow (pulsing) = connecting/reconnecting, red = radio offline.

• Menu 106 safety: when no operator or administrator connection is left for 15 s (a reload or a network drop is not enough), the server sets the radio's mic input back to MIC (audit event mic_input_reset). If the page comes back with the microphone still armed it sets REAR again.

Architecture

As built (version 1.1)

The design below was written before the program existed. This is how it turned out; where the two differ, this section is right.

• One process. The audio service runs inside the core process (the design proposed a separate radio-audio process). It is a self-contained class with a narrow interface, and the measured CPU cost on a Pi 4 (see audio) made a second process unnecessary.
• Native Yaesu CAT only. Every radio is driven through a Yaesu CAT protocol object (Ft991aProto for the FT-991A, HfProto for the FTDX10, FTDX101D/MP and FT-710) and one YaesuCatDriver. Hamlib is not used. A Hamlib "NET rigctl" server (so a logbook can follow the radio) is planned.
• Frontend: plain ES modules, no framework and no build step (the design proposed Preact + htm). The page is a PWA with a service worker.
• Python 3.11+, aiohttp, pyserial, aiortc, numpy, sqlite3 (accounts and audit), scrypt for passwords, TOML for the configuration.
• Capability files (backend/radio_remote/radio/capabilities/*.toml) describe each radio; the page's controls are generated from them. What each radio supports is generated from the same files.
• Safety: TxGuard (the only thing that can key the transmitter: permission, one owner, heartbeat, time limit, un-key on disconnect or lease change) and ControlLease (who controls the radio). The transmit permission is off by default and is switched on by an administrator.
• Added since the design: roles and trusted users, the audit log, remote audio with a server-side gate, Bluetooth device choice, memory channels, status lights, Lock PTT, the SWR warning, settings backup and restore, the update notice and self_update.sh, tailscale_setup.sh, the installer pack, and the ready-made Raspberry Pi image with its Imager repository.
• Audio over a WebSocket (/ws/audio, binary Opus packets both ways, WebCodecs in the browser) is built as the fallback for networks that block WebRTC/UDP.
• Not built: a separate audio process, Hamlib as a backend.

Original design (kept for the reasoning behind the decisions)

Written as a proposal; the [DECISION] marks were the points confirmed before building.

1. System overview

 Browser (tablet / phone / desktop)
   │  HTTPS (443)           WebSocket (state, control)       WebRTC/Opus (audio, UDP)
   ▼
 Caddy  (TLS, optional)  ──► 127.0.0.1:8080  radio-core  (single owner of CAT)
                                  │  ├─ auth / sessions / REST
                                  │  ├─ WebSocket hub  ◄── fan-out of RadioState
                                  │  ├─ Radio State Engine (authoritative copy of the rig)
                                  │  ├─ TX Safety Controller (PTT lease, watchdog, timeout)
                                  │  └─ Radio Abstraction: RadioDriver ─► CatTransport
                                  │                                          ├─ serial (pyserial)
                                  │                                          ├─ mock (no hardware)
                                  │                                          └─ hamlib (optional)
                                  │  unix socket (control + tx-permit)
                                  ▼
                            radio-audio  (separate process)
                              ALSA capture/playback ◄─► aiortc WebRTC (Opus)
                                  ▲
                                  └── USB audio codec of the radio
 USB: CAT serial ──► radio       USB: audio codec ──► radio

Principles: the Pi owns the CAT port (no browser ever talks to the radio); the radio is the source of truth; the browser is a view plus an intent sender; safety logic lives in the backend; audio is isolated from CAT so audio problems cannot stall PTT release.

2. Backend technology [DECISION]

Python 3.11+ (asyncio), packaged in a venv.

Rejected: Node (not installed here, no better audio story), Go/Rust (excellent performance, but a bigger build/learning surface; revisit only if the aiortc spike fails — see §5.3), Docker (adds a layer to USB device passthrough/udev/ALSA and ~100 MB; systemd is simpler on a dedicated Pi. A Dockerfile can be added later for dev).

Two processes, one repo: - radio-core — HTTP, WebSocket, CAT, state, auth, TX safety. - radio-audio — ALSA ↔ WebRTC only. Talks to core over a Unix domain socket. It cannot key the radio; it only streams mic audio to the radio's codec while core says "TX permitted".

3. Frontend technology [DECISION]

No-build ES modules + Preact + htm (vendored, ~12 KB gzip), plain CSS (custom properties, container queries), SVG/Canvas for dial and meters, a service worker + web manifest for PWA.

Trade-off: no TypeScript compile step. If you prefer TypeScript + Vite we can adopt it; it needs Node on the developer machine only, and output is committed/released as static dist/.

4. CAT / Hamlib architecture [DECISION]

Hybrid, native-first. One Python CatTransport per radio; drivers speak Yaesu CAT directly. Hamlib is an optional second backend.

RadioDriver (abstract)                  capabilities: machine-readable, per model
 ├─ FT991ADriver     (native CAT, verified from the official manual)
 ├─ FTDX101Driver    (declared, disabled until manual verified)
 ├─ FTDX10Driver     (declared, disabled)
 ├─ FT710Driver      (declared, disabled)
 └─ HamlibDriver     (generic fallback; capability set derived from `--dump-caps`)
CatTransport
 ├─ SerialTransport  (pyserial; exclusive lock file; reconnect with backoff)
 ├─ MockTransport    (simulated radio; default for development; refuses PTT-to-hardware)
 └─ ReplayTransport  (tests: recorded CAT transcripts)

Core CAT mechanics (all model-agnostic, in radio/cat/):

• Command pipeline: priority queue (PTT-off > PTT-on > user sets > fast meters > periodic polls). One command in flight; ;-framed parser tolerant of interleaved auto-information frames. Per-command timeout; limited retries; ?; handling.
• State sync: on connect → ID; check → AI1; → full read-out → steady state. AI push updates keep latency low and detect front-panel changes. If AI isn't reliable, driver falls back to IF; poll (~2/s).
• Polling tiers (driver-tunable): TX meters 8–10 Hz while keyed; S-meter 5–8 Hz while receiving; IF;/TX; 2 Hz as AI backstop; slow settings round-robin one command every ~250 ms; paused for the user's own command bursts. Throughput check: at 38400 baud an SM0;→SM0xxx; pair is ~11 bytes ≈ 3 ms on the wire; the radio's own latency dominates, so a budget of ~15 transactions/s is realistic and leaves headroom.
• Single owner: lock file + fcntl.flock (Linux) / named mutex (Windows dev); udev symlinks /dev/yaesu-cat by USB serial/interface number. Port auto-detection: enumerate pyserial.tools.list_ports by Yaesu/Silicon Labs VID:PID, probe candidate ports with ID; (read-only, never a set), pick the one that answers with a known ID. Two-port radios (the 991A) are disambiguated by this probe, not by order.
• Reconnect: any read timeout burst/serial exception → state connected=false (UI banner), backoff 1→10 s, re-detect port, replay init sequence, then read the radio and overwrite the state (physical radio wins). Pending set-commands queued during disconnect are dropped, never replayed (could surprise the operator).
• Radio authoritative: after each user "set", the optimistic UI value is replaced by the radio's answer; rejected/clamped values show up automatically.

5. Audio architecture [DECISION]

5.1 Transport

WebRTC with Opus (mono, 20 ms frames, 16–24 kHz wideband-speech profile, ~24–32 kbps, in-band FEC enabled). Chosen because it is the only browser-native low-latency real-time audio stack that works on iOS Safari, Android Chrome and desktop without plugins, includes jitter buffer/loss concealment, and the same peer connection carries the microphone upstream.

Library: aiortc (Python, ctypes libopus). Risk to verify, not assume: aiortc's Opus path is hard-wired to 48 kHz and its CPU cost on a Pi 3B+ with an ARM64 build has not been measured by me. Plan a Phase 6 spike: 2-way stream, measure CPU/latency/jitter on a real Pi 3B+. Fallback A: GStreamer webrtcbin (C, lower CPU, heavier install). Fallback B: WebSocket carrying Opus frames decoded in the browser with WebCodecs (not available on older iOS) — used also when UDP is blocked.

5.2 Local capture/playback

ALSA only (Raspberry Pi OS Lite 64-bit; no PulseAudio/PipeWire). Devices referenced by stable names (hw:CARD=CODEC,DEV=0), never numeric index. radio-audio opens the radio's codec exclusively: RX = capture, TX = playback. Detection layer: /proc/asound/cards + aplay -L → candidate list, "looks like Yaesu codec" heuristic, user override in the admin UI, hot-plug via udev/inotify with reopen backoff.

5.3 Levels and echo/AGC

• RX path: capture → gain → (optional) high-pass → Opus → browser. Gain/volume: server-side rx_gain_db, browser <audio> volume.
• TX path: browser mic (getUserMedia constraints for echoCancellation/noiseSuppression/autoGainControl are user settings, default AGC off, echo-cancel on for speaker use) → Opus → server decode → tx_gain_db → limiter → ALSA playback to the radio. Limiter on the TX path is mandatory to prevent over-deviation/ALC pumping.
• Level meters: RMS/peak computed in radio-audio, sent to core at ~10 Hz and fanned out through the WS; the browser also meters its own mic locally.

5.4 Important constraint: HTTPS is required for the microphone

Browsers only expose getUserMedia on a secure context (HTTPS, or localhost). A plain http://raspberrypi.local/ page cannot capture the microphone on any modern browser, iOS included. So:

• LAN: Caddy with its internal CA (user installs the root cert once per device) or Tailscale-issued certs on the *.ts.net name.
• Remote: Tailscale (tailscale serve/tailscale cert) gives real publicly-trusted certificates for the Pi's tailnet hostname — the recommended default for tablets/phones.
• RX-only listening works over HTTP; TX audio does not.

This is why the installer sets up Caddy by default [DECISION]: the app listens on 127.0.0.1:8080 only; Caddy exposes 443/80. Without HTTPS, the UI disables the microphone button and says why.

5.5 WebRTC and Tailscale

No STUN/TURN is needed on LAN or tailnet: ICE host candidates on the LAN/tailscale0 interface suffice. If Tailscale falls back to a DERP relay (TCP/HTTPS), WebRTC UDP latency increases; the UI shows the ICE path and the user can force the WebSocket-Opus transport.

6. Real-time protocol

Single WebSocket /ws (JSON; msgpack optional later).

• Server → client: state (full snapshot on connect), patch (changed fields only, coalesced at ≤20 Hz), meters (high-rate, separate small message), event (errors, warnings), lease (who controls), audio (stream status).
• Client → server: cmd messages {id, type, args} with ack {id, ok|error}; hello with a short-lived ticket; ptt heartbeat.
• REST (/api/…): config, users, diagnostics, logs, auth. Never used for high-rate data.
• WS auth: session cookie + Origin allowlist check + one-time ticket issued by REST after login (prevents cross-site WS hijack).

7. Radio State Engine

A single server-side RadioState (dataclass → dict). Sources: driver events (AI push, poll answers). Sinks: WS hub. Rules:

• Writes go to the radio first; state changes only when the radio confirms (or a short optimistic window for sliders, reconciled after ≤500 ms).
• Fields carry {value, ts, source}; per-field "unsupported" simply isn't in the snapshot.
• State persistence on disk: only last-known config, never TX state.

8. Capability model

Machine-readable radio/capabilities/<model>.toml, e.g.

[model]  id="ft991a" name="Yaesu FT-991A" cat_id="0670"
[verified] source="FT-991A_CAT_OM_ENG_1711-D" bench="pending"
[features]
vhf=true uhf=true antenna_switching=false  # no CAT opcode (verified absent)
swr_meter=true alc_meter=true comp_meter=true
power_off_cat=true  power_on_cat="unverified"

Each field is true | false | "unverified". The UI builds itself from the capability snapshot sent at connect; "unverified" is treated as false for display. Ranges (rf_gain 0..255, power 5..100) come from the same file. A test asserts every UI control maps to a capability key.

9. TX safety (server-side, authoritative)

PTT request ──► [auth] ──► [ALLOW_PTT?] ──► [lease holder?] ──► [rate limit] ──► driver.tx(True)
                                   (default false)      (one owner)
      TxGuard watchdog (core, independent asyncio task + monotonic clock):
        • heartbeat: owner's WS must send a ptt-hold ping ≥ every 300 ms; miss 1.0 s ⇒ TX0
        • WS close / error / lease loss / auth expiry ⇒ TX0
        • max TX duration (default 120 s, config) ⇒ TX0, lock PTT until released
        • CAT disconnect while keyed ⇒ attempt TX0 repeatedly; radio TOT (`EX036`) is the final backstop
        • SIGTERM / shutdown ⇒ TX0 before exit
        • TX0 retried until the radio acknowledges (`TX;` → 0)
      Radio-keyed externally (`TX;`=2): shown as TX; software never claims control.

PTT is momentary (hold-to-talk) by default; latching requires an explicit setting + confirm. Test suite: transports are mocks; a RealSerialTransport refuses to open when RADIO_REMOTE_TESTING=1 and PTT code paths require ALLOW_PTT=true in the config file, not the environment, so tests cannot enable it. Tuner start (AC) and any other TX-causing command go through the same guard.

10. Multi-client control

• Roles: admin, operator, viewer.
• Everyone with a session sees state/meters/audio-status.
• Control lease: at most one operator holds it; lease.request → current holder gets a prompt (accept/deny/timeout 10 s); admin can force-release; lease expires with heartbeat loss (5 s).
• Setting commands, PTT, and TX-audio require the lease. PTT additionally requires the holder's own active connection (not just the lease).
• RX audio can be listened to by multiple viewers (separate peer connections; Pi 3B+ limit configurable, default 3).

11. Security

12. Configuration & storage

• /etc/radio-remote/config.toml (admin-edited through the UI; atomic write + backup .bak).
• /var/lib/radio-remote/radio-remote.db (SQLite: users, sessions, audit).
• Logs: journald via systemd + rotating /var/log/radio-remote/*.log at configurable level.
• Defaults are safe: allow_ptt=false, radio.model=mock, mock transport.

13. Deployment

systemd (no Docker): radio-remote-core.service, radio-remote-audio.service, caddy (stock package), udev rule for stable device names and plugdev/dialout/audio groups, Restart=always, WatchdogSec using sd_notify from core (health), TimeoutStopSec large enough for TX0. install.sh is idempotent; update.sh does git pull, venv update, migrate, restart. Debian packages: python3-venv libopus0 libasound2 libportaudio2 hamlib-utils caddy (Hamlib from Debian may be older than 4.7 — the installer reports the version and can build 4.7+ from source on request).

14. Raspberry Pi 3B+ budget

15. Logging & diagnostics

Structured logs (JSON optional), per-subsystem loggers (cat, audio, auth, ptt, web, config). Diagnostics page: Pi model, uptime, CPU, RAM, temperature (/sys/class/thermal), version, radio model/ID, port, CAT counters (tx/rx/timeouts/errors), Hamlib version, audio devices & stream state, clients, lease holder, last 200 log lines (scrubbed).

16. Testing strategy

• Unit: CAT frame parser/generator, frequency/mode/width tables (from the manual), capability loader, state merge, lease logic, TX guard (with fake clock), auth/session/CSRF, WS protocol.
• Integration: MockRadio over a pty-pair "serial port" so the real SerialTransport code is exercised without hardware.
• Safety tests assert no real transport can ever be keyed in the test environment.
• Replay tests from recorded transcripts once real hardware traffic is captured.

17. Proposed project structure

radio-remote/
  README.md
  install.sh  update.sh
  pyproject.toml  requirements.txt
  backend/radio_remote/
    app.py  config/  auth/  api/  ws/  state/  safety/  services/
    radio/
      base.py  registry.py
      cat/ (frame.py transport_serial.py transport_mock.py hamlib_backend.py)
      drivers/ ft991a.py ftdx101.py ftdx10.py ft710.py hamlib_generic.py
      capabilities/ ft991a.toml ftdx101d.toml …
    audio/ (devices.py worker.py webrtc.py levels.py)
  frontend/ (index.html manifest.webmanifest sw.js  src/ components/ radio/ meters/ controls/ pages/ styles/ vendor/)
  config/  radio-remote.example.toml  udev/  systemd/  Caddyfile.example
  scripts/  detect-radio.py  probe-hamlib.sh
  docs/  01-capability-matrix.md 02-architecture.md installation.md …
  tests/

18. Roadmap (each phase ends runnable)

19. What I need from you

1. Approve or change the decisions: Python backend, no-build Preact frontend, native-CAT-first with optional Hamlib, aiortc (with spike), systemd + Caddy HTTPS.
2. Provide the FTDX101D/MP, FTDX10 and FT-710 CAT manuals (and the FT-991A operating manual) so those drivers can be verified. Until then I'll build FT-991A + mock only.
3. Confirm you have an FT-991A + Pi available for the bench tests in Phases 4–6 (power-ON via PS1;, audio-route menus, meter calibration). I will give a checklist; PTT stays disabled until you say otherwise.

Bench checklist (FT-991A + Raspberry Pi 4)

Status: the benches below were run on a real FT-991A and passed (results: bench results). This page is kept as the procedure for checking a new radio or a new setup, and for re-testing after a change. The experimental radios have their own first-contact checklist in other radios.

Rule for every step: PTT stays disabled (safety.allow_ptt = false) and the antenna jack should have a dummy load or be disconnected until a step says otherwise.

Before connecting

1. Radio menu 031 CAT RATE: note the value (default 4800). Recommended: 38400 on both ends.
2. Radio menus 071 DATA PTT SELECT, 076 FM PKT PTT SELECT, 108 SSB PTT SELECT, 047 AM PTT SELECT: note them. Our software holds DTR/RTS low when opening the port, but if any of these is set to RTS/DTR, a different program opening the port could key the radio. Prefer DAKY.
3. Menu 036 TX TOT: set to a non-zero value (for example 3 min) as a radio-side backstop for later phases.
4. USB-connect the radio, power it on. On the Pi: ls /dev/serial/by-id/ and lsusb (expect Silicon Labs CP210x, two serial ports).

Bench 1 - read-only

sudo systemctl stop radio-remote          # the service holds the port
python scripts/bench1_readonly.py
sudo systemctl start radio-remote

Expected: ID; -> ID0670;. Things to look at: - whether ?; appears for any read (the manual is silent on error replies), - the real IF; / SM0; / RM* values at idle (meter calibration starts from these), - which of the two serial ports answers, and at what baud.

Bench 2 - app against the real radio, RX only

Config: radio.model = "ft991a", serial_port = "auto", allow_ptt = false. - Turn the VFO knob: browser frequency must follow within ~0.5 s. - Change mode on the radio and in the browser. - Pull the USB cable and re-plug: UI shows "radio offline" then recovers on its own. - Power-cycle the radio: UI recovers; confirm frequency/mode are correct afterwards. - Check the log shows AI1 re-sent after reconnect.

Bench 2b - Phase 5 controls (RX only, PTT disabled, dummy load)

Change each control in the browser and compare with the radio's own display. Things the manual leaves open:

Never offered: VOX (VOX plus remote audio risks unintended transmission) and menu (EX) writes, with one exception: the REAR / MIC input switch (menu 106). AGC and power on/off are offered because they were verified on the radio.

Bench 2c - antenna tuner and C4FM DG-ID (done; the diagnosis method is kept)

The tuner on/off chip (TUNER) was once reported as "does nothing" on the real radio (it was fine; the radio replies were checked). If a function seems dead, diagnose with raw reads first (no transmit):

sudo systemctl stop radio-remote
sudo -u radio-remote /opt/radio-remote/venv/bin/python - <<'EOF'
import serial, time
s = serial.Serial(); s.port, s.baudrate, s.timeout = '/dev/ttyUSB0', 38400, 0.5
s.dtr = False; s.rts = False; s.open()
def ask(c):
    s.reset_input_buffer(); s.write(c); time.sleep(0.4); print(c, '->', s.read(64))
ask(b'AC;'); ask(b'AC001;'); ask(b'AC;'); time.sleep(2); ask(b'AC000;'); ask(b'AC;')
s.close()
EOF
sudo systemctl start radio-remote

(AC001;/AC000; switch the tuner on/off; they do not transmit.) Watch the radio's display for the tuner indicator.

TUNE button (works on the FT-991A; re-test it on any other radio): sends AC002; (manual: "tuning start / tuning stop"), which makes the radio transmit a carrier. Server-side it is guarded like PTT: needs allow_ptt = true, control, an operator account; hard limit 15 s; stops if the browser disconnects; a stop (AC002; again) is only ever sent while the radio itself reports RF going out, because the command is a toggle and would otherwise start a new tune. Test ONLY with a dummy load / suitable antenna, at 5 W, tuner switched on, and be ready to switch the radio off. Questions to answer on a new radio: does AC002; start a tune; does the radio report TX (TX;) or a power reading while tuning; does a second AC002; stop it; how long does a tune take.

DG-ID (new): radio menu 153 "WIRES DG-ID" via EX153 (00 = AUTO, 01-99), shown next to the mode buttons in C4FM mode only. The CAT manual lists ONE DG-ID item; no separate TX/RX one. If the radio has separate TX and RX DG-ID settings, give me their menu names/numbers (or the operating-manual page); they will not be guessed. Check: set a value in the app, compare with the radio's menu 153; set it on the radio, see the app follow within about 10 s (read every slow-poll cycle).

Later benches (not yet implemented)

• Bench 3: PS0; power off / PS1; power on from standby (does the USB UART answer in standby?).
• Bench 4: PTT with dummy load, timeouts, heartbeat loss (unplug network while keyed).
• Bench 5: meter calibration (S-meter vs signal generator, PO/SWR vs wattmeter).
• Bench 6: USB audio routing menus.

Bench results (real FT-991A)

Summary (as of version 1.1.9, 2026-10-05)

Everything below was tried on a real FT-991A with a Raspberry Pi 4 (Raspberry Pi OS Trixie, Python 3.13).

Radio behaviour that differs from the CAT manual (all handled in the code): - PR (speech processor): the radio uses 0 = off, 1 = on, not 1 / 2 as printed. - FT (TX VFO): set 2 / 3 (TX on A / B), read 0 / 1. - MT (memory read with tag): the answer to MT005; carries the data of channel 5 but always says channel 001; empty channels answer ?;. The server matches the answer on MT alone and takes the channel number from its own request. A channel that stays silent is retried and then read with MR (no tag). - EX153 (WIRES DG-ID): the radio answers with three digits (EX153000;), the manual shows two. - The radio answers a read taken immediately after a VFO command with the old value: reads after VFO operations wait 0.35 s and repeat. - The radio does not announce VFO B changes: VFO B is polled every second.

The sections below are the log of the tests in the order they were done (some notes at the time said "to be tested": the summary above is current).

Bench 1 - read-only: PASSED

Date: 2026-10-01. Hardware: Raspberry Pi (hostname FT991A), FT-991A over USB, app v0.1.0. Method: bench1_readonly.py (sends read commands only).

Link statistics: tx 16, rx 28, timeouts 0, rejected (?;) 0, unsolicited 12.

Findings: - The CAT port is /dev/ttyUSB0 (the FT-991A exposes two ports; detection picked the right one at 38400 baud). - No read command was answered with ?;. - The service user needs read access to /opt/radio-remote/..., not /home/<user>/... (home directories are private). - The service must be stopped while running the bench script: it holds the port.

Bench 2 - app against the real radio, receive only, PTT disabled: PASSED (operator report)

• Status badge shows "radio online".
• VFO knob changes follow in the browser.
• Mode changes on the radio follow in the browser.
• Band buttons in the browser move the radio to that band (BS command).
• USB unplug/replug and radio power cycle: shows offline, then recovers by itself.

Antenna tuner on/off (AC) and split (FT): replies from the real radio

So FT behaves as the manual says: set 2 / 3 (TX on A / B), read 0 / 1. Split in the app = FT3;, normal = FT2;; the state follows the radio's own FT announcements. QS; (quick split) and the TUNE button (AC002;) are implemented but NOT yet verified. Auto-information also streams RM0nnn; (front-panel meter) continuously; currently ignored.

VFO operations, tuner, DG-ID: operator report after the first VFO B build

• A=B, B=A, SPLIT: work. Tuner on/off and TUNE: work (operator: "tuning works").
• A<->B: the radio changed but the VFO B label did not follow. Cause: the radio answers a read taken immediately after the command with the OLD value, and VFO B was only re-polled every ~13 s. Fixed: reads after VFO operations wait 0.35 s and repeat about 1 s later; FB; and FT; are now in the 1 s backstop poll.
• Set B (type a frequency): reported as not working. Not yet understood (possibly the same stale-read problem); raw FB test requested.
• Raw FB check on the real radio: FB; -> FB007498700;, FB007074000; accepted (the radio sent no echo of the new B frequency, unlike AC, FT which announce changes), FB; -> FB007074000;. So Set B works at the CAT level; the radio does not announce VFO B changes, they must be polled (now every 1 s). The "Set B does not work" symptom was the stale label, not the command.
• DG-ID: the control wrote menu 153 and "does nothing on the radio". The CAT manual lists only menu 153 "WIRES DG-ID" (the WIRES-X setting) and menu 090 "AMS TX MODE" (AUTO / MANUAL / DN / VW / ANALOG). There is NO documented command for the C4FM RX DG-ID / TX DG-ID shown on the radio, so they cannot be controlled over documented CAT. The control is relabelled "WIRES DG-ID" so it does not mislead. If the radio's front-panel menu number for TX/RX DG-ID is known, EX<number>; reads could be probed; nothing will be guessed.

Installer and updater on a real Pi: PASSED

• install.sh ran on Raspberry Pi OS (aarch64, Python 3.13.5): service, Caddy, udev rule, config created; app healthy. (First install was done before these notes; it worked, app reachable, radio detected.)
• update.sh from a tarball copy (no git): backup written, new release deployed beside the old one, dependencies already satisfied, switched, restarted, health check passed ("Updated and healthy"). Config and users untouched.
• Not yet exercised: the automatic rollback path, restore.sh, uninstall.sh.

Bench finding: manual vs radio, speech processor (PR)

The service logged bad frame from radio: bad PR every slow-poll cycle. Raw capture from the real radio:

The manual says the on/off digit is 1 = OFF, 2 = ON; the radio uses 0 = OFF, 1 = ON. Set test on the real radio:

Fixed in both directions (parser and encoder): the processor toggle now sends PR01; / PR00;. Before the fix the UI would have turned the processor on when asked to turn it off. Lesson: the CAT manual can be wrong on value tables; every set command in the controls panel should be checked on the real radio (Bench 2b), not trusted from the manual. Side note: with auto-information on, the radio streams RM0nnn; (front-panel meter) frames continuously; they are currently ignored.

All other polled controls (NA, SH, IS, CO, BP, BC, NR, RL, NB, NL, PA, RA, RT, XT, PL, ML, AC) produced no warnings on the real radio, i.e. their reply formats parsed. Rejections (?;) are not logged at warning level, so a command refused in the current mode would not show up in that log.

Receive audio: PASSED (operator report)

Listen in the browser: receive audio is heard and the RX meter moves. Observation: with IPO selected nothing useful is heard, with AMP1/AMP2 it receives. Expected radio behaviour (IPO = no preamp gain) but needs confirming against the radio's own display (open question: do app labels IPO/AMP1/AMP2 match the radio's front panel?).

Audio: device detection and CPU

arecord -l / aplay -l (Pi 4, radio on): the radio appears as card 1: CODEC [USB Audio CODEC], device 0 for both capture and playback; the other playback cards are the Pi's headphones and two HDMI outputs. Exactly one USB audio CODEC, so auto-detection selects plughw:CARD=CODEC,DEV=0 for both directions.

audio_spike.py on a Raspberry Pi 4 Model B (aarch64, 4 cores, Python 3.13.5):

Reading: real server-side cost is below these figures because the loopback also runs the client. A Pi 4 has ample headroom for the default audio.max_peers = 3; a separate audio process is not needed there. A Pi 3B+ is expected (estimate, not measured) to be 2-3x slower per core: use max_peers 1-2.

At that point still unverified (all of it was verified later, see the summary at the top): every set command, the controls panel, PTT, audio, NA/GT quirks, PS0;/PS1;. Meter calibration against real signals is still open.

• DG-ID follow-up (bench): scripts/ex_dump.py dumped EX001..EX160 (153 readable) before and after changing the DG-ID on the radio (GM long press, C4FM). No EX value changed, so the C4FM RX/TX DG-ID is not reachable over CAT. The web selector was replaced by a hint "DG-ID: set on the radio (hold GM)"; the backend dgid control (menu 153) remains but is not offered in the UI.

• Mic input (menu 106 SSB MIC SELECT, manual p.9: 0 = MIC, 1 = REAR): added as a control mic_select (EX106), shown as a "Mic: REAR/MIC" button in the Receiver & tools block, refused while transmitting. Verified later: the button flips menu 106 on the radio (now the REAR / MIC buttons above PTT).

• Power on (PS1): the CAT manual (p.15) says the command needs dummy data first and PS1; one to two seconds later. Implemented in the driver supervisor (power_on, wake_gap_s = 1.4 s): while the radio is not connected an admin gets a "Power on radio" button in the offline banner; the server opens the serial port, sends ;, waits, sends PS1;, closes it and keeps retrying the normal connection. Bench to do at the time (done, see below): radio in standby with the DC supply on, USB cable connected: does the USB serial port stay present and answer? If the port disappears in standby this cannot work over USB (the Pi would need a relay on the radio's power input instead).

• Power on / off VERIFIED on the real FT-991A (operator report): "Power off" (PS0) and "Power on radio" (dummy data, 1.4 s, PS1) both work over USB with the radio in standby; the USB serial port stays available in standby.

• VFO B mode: added OI; (manual p.14) to the sync and the 1 s backstop poll; the answer is decoded like IF and only mode_b is used. Bench to do at the time (done, see below): check that VFO B shows the right mode, also after A<->B / A=B / B=A.

• RX audio level (operator report): the browser audio was too quiet with menu 107 SSB OUT LEVEL at its default (50). Setting menu 107 to 90 fixed it, with audio.rx_gain_db left at 0. So the radio's USB output level menus (107 SSB, 073 DATA, 046 AM, 075 FM, 054 CW, 099 RTTY) are the right place to set the receive level for the Pi.

• ALC calibration (operator report, dummy load, FT-991A): normal speech: radio ALC meter about 50%, app raw ALC peak 79 (with the old scale 50 the app bar was full). So ui.meter_alc_full default raised to 160. One point only: the radio's ALC meter may not be linear; a second point (louder speech) is still wanted.

• VFO B mode via OI; VERIFIED on the real FT-991A (operator report): VFO A and VFO B show the correct band and mode.

• RIT/XIT clarifier VERIFIED (operator report): the RIT + XIT buttons with the shared offset bar work on the FT-991A. COMP scale (ui.meter_comp_full = 255 default) looks right to the operator, no change needed.

• Background audio VERIFIED (operator report, phone): Listen keeps playing with the app in the background.

• Memory channels (to be tested at the time; verified below): Memories button, list read with MT001;..MT099;, recall with MC005;, back with VM;. Check: do the tags and frequencies match the radio's own memory list, are empty channels skipped (?;), does the MEM badge follow the radio, and does Back to VFO return to the previous VFO frequency? If an empty channel is answered with frequency 000000000 instead of ?; it is skipped as well.

• Memory channels VERIFIED on the real FT-991A (operator report: "it works"): Memories list, recall and back to VFO.

• AGC VERIFIED on the real FT-991A (operator report): the AGC list (OFF / FAST / MID / SLOW / AUTO, GT0) works.

• Bluetooth audio device choice VERIFIED (operator report): choosing a Bluetooth output/input on the Audio tab works.

• ALC scale accepted by the operator for now (ui.meter_alc_full = 160); a second point (louder speech) is optional.

• Installer pack, static checks (development PC, Debian under WSL1): every shell script passes bash -n; install-everything.sh --dry-run prints the expected sequence (packages, user, release copy, offline pip from the bundled wheels, config, udev, systemd, Caddy, docs URL); --model ftdx10 prints the experimental note, a bad model and a non-root run are refused. (Run for real on a Pi 4 afterwards: it found one bug, the program folders were copied with private permissions so the service user could not read them; fixed and covered by a test.)

• Ready-made image, Imager and updates (2026-10-03): the image built by GitHub Actions booted on a Pi 4 and ran. Raspberry Pi Imager 2.x shows its own hostname / user / Wi-Fi screens for it through the content repository (os-list.json); the settings script was needed before. The in-app update (self_update.sh: checksum, backup, install, health check) installed a newer release. tailscale_setup.sh made the Pi reachable over its .ts.net name with a real certificate. The memory list read failed until the "answer says channel 001" behaviour was handled.

FTDX101D (real radio, 2026-10-05)

Hardware: Raspberry Pi 4 (hostname FT991A), FTDX101D over USB, app v1.1.9 plus the local FTDX101D work. The radio first stayed silent until its menu CAT RTS was set to OFF (with RTS high it answered ID0681;), CAT rate 38400, Enhanced port /dev/ttyUSB0. Read-only first contact: 36 commands answered, 0 timeouts, 0 rejected.

Not tried: transmitting on the SUB receiver, and the FTDX101MP.

Status and roadmap

What is finished, what is verified on a real radio, and what is still open. For the details of each test see bench results; for what each radio supports see the capability matrix.

Done and verified on a real FT-991A (Raspberry Pi 4)

• Frequency, mode, band, VFO B (A=B, B=A, swap, set frequency, mode), split, RIT/XIT, memory channels (list and recall).
• Receive filters and DSP: width, IF shift, contour, notches, noise reduction, noise blanker, IPO / preamp, ATT, AGC.
• Meters: S-meter, power, SWR (with a warning limit), ALC and COMP (ALC scale calibrated from one point).
• PTT with the server-side safeguards, the transmit switch in Admin > Config, Lock PTT, TUNE, the REAR / MIC input switch.
• Remote audio both ways, Bluetooth headsets, background listening on phones; power off and power on over USB.
• Accounts, roles, the control lease, trusted users, the audit log, settings backup and restore.
• Installation: the ready-made image (also through Raspberry Pi Imager's own screens), the installer pack, in-app update notice and self_update.sh with automatic rollback, Tailscale access (tailscale_setup.sh).

Done, but only against the simulator

• FTDX10, FTDX101D/MP and FT-710: profiles written from their CAT manuals and marked experimental. They need someone with the radio to run the first-contact checklist in other radios.
• Quick split (QS;) on the FT-991A.

Built, not yet released (simulator and real Hamlib rigctl only)

• Logbook link (logbook): a Hamlib "NET rigctl" server on the Pi (port 4532, home network only, off by default) so a logbook such as Log4OM can follow the radio and change frequency and mode. PTT and power are blocked for it. Tested against Hamlib 4.6.2 rigctl; a test with Log4OM itself on the real radio is still to do. WSJT-X transmitting through the Pi is out of scope.

Open