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#
- 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. - Start SPEEDBIRD Modem. The first run creates:
*
%APPDATA%\SPEEDBIRD\speedbird.yaml: the configuration. It starts with no radios and contains commented examples. Setstation.callsignhere. Nothing transmits while the callsign isN0CALL. *%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. - 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.
Winlink Express with SPEEDBIRD#
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.
- Add a TNC port per radio to
%APPDATA%\SPEEDBIRD\speedbird.yamland 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.
- 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 - 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.
- 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#
- Event bus: ZeroMQ
ipc://doesn't exist on Windows, so the bus uses TCP loopback (127.0.0.1, two free ports) automatically (BusAddress.default).SPEEDBIRD_BUS=tcp|ipcforces the choice on any OS. - The asyncio loop on Windows is a selector loop, because zmq.asyncio needs
add_reader. - Sample rings use
multiprocessing.shared_memoryand decoder workers usespawn. Both work on Windows, and the frozen exe callsfreeze_support(). - The ALSA source (
alsa) is Linux-only. On Windows usesoundcatradios.