SPEEDBIRD

SPEEDBIRD Modem for Windows#

SPEEDBIRD runs on a Windows 10/11 PC as a desktop app: the daemon (modem, decoders, waterfall, TX arbiter, VARA-compatible TNC) runs in-process and the UI opens in a desktop window. Radios connect through the PC's sound cards plus a CAT link, and any number of radios can run at once, each with its own sound devices, CAT port and PTT.

Install and first run#

  1. Run SPEEDBIRD-Setup-<version>.exe. It installs per user and needs no administrator rights (%LOCALAPPDATA%\Programs\SPEEDBIRD). It adds Start menu entries and an optional desktop shortcut.
  2. Start SPEEDBIRD Modem. The first run creates: * %APPDATA%\SPEEDBIRD\speedbird.yaml: the configuration. It starts with no radios and contains commented examples. Set station.callsign here. Nothing transmits while the callsign is N0CALL. * %LOCALAPPDATA%\SPEEDBIRD\: the state directory, with radios added in the UI (radios.json), per-radio audio levels (audio\<radio>.json), the TX log (txlog.jsonl), SBP files and the numba JIT cache. * %LOCALAPPDATA%\SPEEDBIRD\logs\speedbird.log: the log. SPEEDBIRD Modem (console) shows it live.
  3. The window opens the Radio audio page (/static/desktop.html). It has links to the full interface (Radios, Console, Spectrum...).

The UI is served at http://127.0.0.1:8073 on loopback only, over plain HTTP. With web.host: 0.0.0.0 other machines on the LAN can use it. There is no authentication, so only do this on a trusted network. Without the Edge WebView2 runtime (standard on Windows 11 and current Windows 10), or without pywebview, the UI opens in the default browser instead.

Command line: SPEEDBIRD.exe [--config PATH] [--port N] [--browser] [--no-window] [--sim] [--listen HOST] [-v]. --sim (first run only) adds a simulated radio and demo source so you can look around without a radio.

Adding a sound-card radio#

On the Radios page, use + Add a radio manually and choose the driver soundcat. The form lists the PC's sound devices. Pick RX and TX devices, the channel, the CAT type and port, and the PTT method. You can also add the radio to speedbird.yaml:

radios:
  - id: ic7300
    name: IC-7300
    rig: soundcat
    tx_enabled: true            # allow the modem to transmit (always through the TX arbiter)
    tx_power_max_pct: 10        # the arbiter sets RF power to at most this before keying
    cat:   {kind: icom, port: COM4, baud: 115200, model: IC-7300}   # civ_addr: 0x94 if not default
    ptt:   {method: cat}
    audio: {input: "USB Audio CODEC", output: "USB Audio CODEC", channel: left, rate: 48000}
  - id: ts590
    rig: soundcat
    cat:   {kind: kenwood, port: COM6, baud: 115200, max_power_w: 100}
    ptt:   {method: rts}          # RTS on the CAT port; or {method: dtr, port: COM9, invert: false}
    audio: {input: "Microphone (USB Audio CODEC)", output: "Speakers (USB Audio CODEC)", hostapi: "Windows WASAPI"}
  - id: ft991
    rig: soundcat
    cat:   {kind: yaesu, port: COM7, baud: 38400}
    ptt:   {method: cat}
    audio: {input: 3, output: 4}  # device indexes also work (GET /api/audio/devices)
key values
cat.kind icom (CI-V serial, or LAN with host/username/password), kenwood, yaesu, elecraft, rigctld (host, port of a running Hamlib rigctld), none (manual tuning; dial_hz, mode)
cat.port, cat.baud COM4, 115200 (defaults: kenwood 115200, yaesu/elecraft 38400, icom 115200)
cat.max_power_w text CAT: watts that equal 100 % (PC command), default 100
cat.tx_command / rx_command text CAT PTT override (defaults: Kenwood TX1;/RX; = data send on rear/USB audio, Yaesu TX1;/TX0;, Elecraft TX;/RX;)
ptt.method cat, rts, dtr, vox, none (receive only)
ptt.port serial port for RTS/DTR. Leave it empty to use the CAT port: Windows can't open a COM port twice, so SPEEDBIRD shares it
ptt.invert true for active-low PTT lines
audio.input / audio.output device name (substring, case-insensitive), index, default, or null / none (no RX / receive only)
audio.hostapi Windows WASAPI (preferred automatically), MME, Windows DirectSound
audio.channel mono, left, right, mix. The IC-7300/705/9700 USB codecs are stereo: use left (IC-9700 sub RX: right)
audio.rate working rate, default 48000. WASAPI shared mode is opened with auto-convert. Other devices are resampled
audio.latency, audio.blocksize PortAudio latency (low, high or seconds; default high) and block size (0 = automatic)
audio.monitor_device optional speakers that play RX audio when Monitor is on
audio.rx_gain_db, tx_gain_db, monitor, agc starting levels. Changes made live in the UI are saved in audio\<id>.json and override these
tx_ranges optional [[lo, hi], ...] Hz. The default is the amateur bands, or the model table for Icom

Each soundcat radio gets an RX audio source <id>-audio. That source feeds the waterfall (Spectrum page and the Radio audio panel), every decoder, and the SBP modem. TX goes only through SPEEDBIRD's TX arbiter, which checks the callsign, tx_enabled, the band, data mode, power limit and timeouts, and logs every transmission. TX needs a CAT link that can set RF power. With cat.kind: none the arbiter refuses to key, because it cannot limit power.

Set the radio's own menus so its USB audio is the data-mode modulation source (for example IC-7300 DATA MOD = USB, TS-590 data VOX off / ACC2-USB input, FT-991A DATA IN = REAR), and choose the PTT input you configured.

Radio audio panel: levels and auto adjustment#

For each soundcat radio, the desktop window and the radio's card on the Radios page show: * RX and TX meters (RMS bar and peak marker in dBFS) with a CLIP light. * A waterfall of 0-4 kHz from the radio's RX audio (/ws/spectrum/<id>-audio). * RX gain: software gain, -30 to +40 dB. * TX level: software gain, -60 to +6 dB, applied in the rig's write_audio after the arbiter's 0.9 peak limit. A clip guard keeps peaks at 0.99 FS or below. Changes take effect live, without reconnecting. * Monitor: plays RX audio on audio.monitor_device. * Auto RX gain: off, on (a slow AGC) or set once and hold (converges, then freezes the gain). It aims for a noise floor of about -40 dBFS and keeps peaks under -6 dBFS. Target, ceiling and time constants are under agc:. * Tune TX…: runs only when you click it and confirm. It transmits short two-tone bursts through the TX arbiter, at the power you enter, capped by tx_power_max_pct. While it transmits it reads the radio's ALC meter: Icom CI-V 15 13, Kenwood RM3, Yaesu RM4, or Hamlib ALC. It raises the TX level in 3 dB and then 1 dB steps and keeps the highest level at which the ALC stays at zero. The result is stored for the current band. If the radio has no ALC readback (Elecraft text CAT, cat.kind: none), it never keys: it sets a fixed safe level of -12 dB and tells you so.

Only the software gains are adjusted. Set Windows' own recording and playback levels for the radio's USB codec once, in Sound settings → Device properties. 100 % playback with TX level adjusted in SPEEDBIRD is a good start.

API (for scripts): GET /api/audio/devices, GET|PUT /api/audio/{radio}/levels, GET /api/audio/{radio}/meters, WS /ws/audio/{radio}/meters, POST|GET|DELETE /api/audio/{radio}/tx-tune (POST needs {"confirm": true}).

Moving from VARA: Import VARA config…#

The desktop window and the Radios page have an Import VARA config… button. Choose VARA.ini (VARA HF or VARA FM), VarAC.ini, VarAC_frequencies.conf and Winlink Express's RMS Express.ini. On Windows, files at the usual places (C:\VARA, C:\VARA FM, C:\VARAChatHF, Winlink Express) are offered for one-click selection. You get a preview before anything changes: * a soundcat radio: VARA's sound devices matched to this PC's devices by name (fuzzy, with alternatives), channel, drive level, and CAT and PTT from VARA and VarAC. TX is always off. Turn it on after you have checked audio and PTT. * a TNC port on the same port VARA used (7300 / 8300...). Winlink Express, VarAC and Pat keep their settings and talk to SPEEDBIRD instead of VARA. Stop VARA first. The port is saved in %LOCALAPPDATA%\SPEEDBIRD\tnc.json, started immediately, and started again at every launch. * station callsign and grid, written to speedbird.yaml only while they are still N0CALL or empty. Restart to apply. * VarAC's calling frequencies go into the frequency list, group "VarAC". Ones already listed are skipped.

VARA's registration key, passwords and e-mail settings are never imported, stored or shown. Settings with no SPEEDBIRD equivalent (KISS port, VarAC UI options...) are listed in the preview.

SPEEDBIRD has a VARA HF-compatible TNC port for each radio. Winlink Express connects to it as if it were VARA HF. The modem underneath is SBP, so the station you call must also run SPEEDBIRD. Real VARA stations can't decode SBP. Details are in winlink.md.

  1. Add a TNC port per radio to %APPDATA%\SPEEDBIRD\speedbird.yaml and restart SPEEDBIRD: ```yaml tnc:
    • {radio: ic7300, cmd_port: 8300} # data port 8301, bound to 127.0.0.1
    • {radio: ts590, cmd_port: 8310} # data port 8311 ``` The desktop window lists the active ports under Winlink Express / Pat.
  2. In Winlink Express, open a Vara HF Winlink or Vara HF P2P session, then go to Settings → VARA TNC Setup: * VARA TNC host / IP: 127.0.0.1 * Command port: 8300, data port: 8301 (use the port pair of the radio you want) * Clear Automatically start VARA (there is no VARA.exe) and leave the VARA path empty
  3. Settings → Radio Setup: no rig control and no PTT from Winlink Express. SPEEDBIRD tunes and keys the radio itself, through its TX arbiter. Leave the COM ports to SPEEDBIRD, because Windows lets only one program open a COM port.
  4. Make sure the radio is running the SBP modem. Open the Console page, or start the modem activity on the Radios page. Then Start the session in Winlink Express.

For a second radio, open a second Winlink Express session (or use a second Winlink Express instance) with that radio's port pair. Bonded transfers that stripe across several radios are started from SPEEDBIRD's Console, not from Winlink Express.

Pat on Windows#

%LOCALAPPDATA%\pat\config.json (or pat configure):

{ "mycall": "N0CALL", "varahf": { "addr": "127.0.0.1:8300", "bandwidth": 2300, "rig": "", "ptt_ctrl": false } }

Then pat connect varahf:///K4MFC-6. Pat is MIT-licensed. The NSIS installer (SPEEDBIRD-Setup-<ver>.exe) ships the official Pat release (<install dir>\pat\pat.exe, 32-bit build: Pat publishes no 64-bit Windows binary) and the desktop app runs it itself for the Winlink page (winlink.manage_pat, see winlink.md), with its config and mailbox in %LOCALAPPDATA%\SPEEDBIRD\pat. A Pat you configure by hand as above is separate from it.

Building the Windows app#

On a Windows 10/11 x64 machine with Python 3.12 (winget install Python.Python.3.12) and Inno Setup 6 (winget install JRSoftware.InnoSetup):

powershell -ExecutionPolicy Bypass -File packaging\windows\build_windows.ps1

The script runs these steps: 1. py -3.12 -m venv .venv-win 2. pip install -e ".[windows,dev]", which installs sounddevice, pywebview, pyinstaller and the test tools 3. pytest -q (skip with -SkipTests) 4. pyinstaller packaging\windows\speedbird.spec, which makes packaging\windows\dist\SPEEDBIRD\ with SPEEDBIRD.exe and SPEEDBIRD-console.exe 5. ISCC /DAppVersion=<ver> packaging\windows\speedbird.iss, which makes packaging\windows\Output\SPEEDBIRD-Setup-<ver>.exe (skip with -NoInstaller)

To smoke test, run dist\SPEEDBIRD\SPEEDBIRD-console.exe --sim. Put speedbird.ico in packaging\windows\ to give the app and the installer an icon.

Not bundled#

External digital-voice decoders (dsd-fme) and Hamlib rigctld are not packaged; if the user installs them, SPEEDBIRD uses them as separate programs. The NSIS installer does ship two separate programs, each with its licence: Pat (MIT, <install dir>\pat) and, in the optional default-on section "Meshtastic support (GPL-3.0 component)", the Meshtastic bridge (<install dir>\meshbridge: meshbridge.py, LICENSE, SOURCE.txt and pkgs\ with meshtastic and its dependencies). The bridge runs in its own process with the bundled Python; its GPL packages never load into the SPEEDBIRD process (they are not in pkgs\).

Licences of the Windows-only dependencies#

package licence use
sounddevice MIT sound-card I/O (bundles the PortAudio DLL, MIT-style licence)
pywebview BSD-3-Clause desktop window (Edge WebView2 through pythonnet, MIT)
PyInstaller GPL-2.0 with bootloader exception build tool only. The exception lets the frozen app stay proprietary
Inno Setup Inno Setup licence (free, commercial use allowed) build tool only

Platform notes#