SPEEDBIRD

Winlink over SPEEDBIRD#

SPEEDBIRD supports Winlink in two ways:

  1. SBP as a VARA-compatible TNC (src/speedbird/core/sbptnc.py). Each configured radio gets a TCP command port and data port that speak the VARA HF TNC host protocol. Winlink Express, Pat and VarAC use them as if SPEEDBIRD were VARA, but the RF link is SBP: SPEEDBIRD's own OFDM, LDPC and ARQ modem. Both stations must run SPEEDBIRD (or another SBP implementation). This is not VARA on air.
  2. Connect strings (src/speedbird/core/connectstr.py, connect.py). These are Pat-style URLs and classic C CALL via ... lines, executed on SBP or on a real VARA instance configured under vara: endpoints: (see docs/vara.md).

Enabling the TNC ports#

# speedbird.yaml
tnc:
  - {radio: ic7300mk2, cmd_port: 8400}            # data port = 8401, bound to 127.0.0.1
  - {radio: ic7610,    cmd_port: 8410, freq: 7105000}

Warning: the TNC listens on 127.0.0.1 by default. Setting host: 0.0.0.0 lets anyone who can reach that port make your station transmit under your callsign. There is no authentication in the VARA host protocol. Only do this on a trusted network, and firewall the port. Keying still goes through SPEEDBIRD's TX arbiter: TX enable, band and power limits, timeout and the station log.

GET /api/tnc shows each port: whether a host program is connected, its MYCALL, the session state and peer, buffered bytes, and any commands the TNC did not understand.

What the TNC does with VARA commands#

host sends SPEEDBIRD
MYCALL K4MFC-7 recorded; the SBP modem is started or restarted under this call at LISTEN ON / CONNECT (must be the station call, SSID 0-15)
LISTEN ON/OFF incoming SBP sessions to MYCALL raise PENDING and then CONNECTED <peer> <mycall> 2300
CONNECT <my> <target> opens an SBP session, then CONNECTED <my> <target> 2300, or DISCONNECTED if no answer within 120 s
CONNECT ... VIA ... WRONG (SBP has no digipeating yet)
DISCONNECT / ABORT graceful close (the peer's host gets DISCONNECTED) / immediate stop with TX abort
BW500/2300/2750, PUBLIC, CHAT, CWID, COMPRESSION, P2P SESSION, WINLINK SESSION, CLEANTXBUFFER OK, recorded (SBP adapts its own bandwidth and rate)
VERSION VERSION SPEEDBIRD-SBP <version>
ENCRYPTION ... WRONG, always (Part 97)

The TNC also sends BUFFER n (bytes not yet acknowledged over the air), PTT ON/OFF (informational only, so do not let the host program key the radio), SN, BITRATE, BUSY, and IAMALIVE every 60 s.

Pat (https://github.com/la5nta/pat, MIT license) is installed as a separate program (/usr/bin/pat, Debian package pat 1.0.1). SPEEDBIRD generates its configuration and drives it through Pat's HTTP API (src/speedbird/core/winlink.py, UI page Winlink, API /api/winlink/*).

Profiles. A Pat instance has one VARA modem address, so each modem is a profile:

profile kind modem use
ic7300mk2 (main) SBP SPEEDBIRD TNC 127.0.0.1:8400 Winlink P2P with another SPEEDBIRD station
ic7610 SBP SPEEDBIRD TNC 127.0.0.1:8410 same, on the IC-7610
digiall-7300mk2, digiall-705, ... VARA DIGIALL 172.19.2.150:83xx real Winlink RMS gateways / VARA P2P
telnet internet cms.winlink.org:8772 Winlink CMS without RF (main profile's telnet alias)

SBP is not VARA on air: an SBP profile only reaches another SPEEDBIRD station (P2P now, a SPEEDBIRD-run RMS later). To reach the real Winlink network over RF use a VARA profile (DIGIALL's VARA modems key their own radios).

Files (/var/lib/speedbird/pat/, mode 700, user speedbird): * config.json main profile, profiles/<name>.json one per profile (0600), rewritten by SPEEDBIRD and by speedbird pat-config -c /etc/speedbird/speedbird.yaml. varahf.rig is empty and ptt_ctrl false: SPEEDBIRD (or DIGIALL) owns the radio. The locator follows the station location (6-character grid). * cms_password (0600): your Winlink password, for secure login to the CMS / RMS. Set it on the Winlink page or write the file by hand. It is merged into the 0600 config files and never shown by the API or logged. * mailbox/<MYCALL>/{in,out,sent,archive} shared by all profiles; pat.log (main), logs/<profile>.log.

Processes. * pat-speedbird.service runs the main profile: pat http on 127.0.0.1:8080 (local only; use ssh -L 8080:127.0.0.1:8080 for Pat's own web UI). It runs independently of speedbird.service, so a SPEEDBIRD restart does not cut a session or a listener. deploy/install.sh installs and enables it. * No systemd unit (the Windows desktop app, a plain speedbird serve): SPEEDBIRD runs the main Pat itself (winlink.manage_pat, default auto). A few seconds after startup (manage_delay_s, 5), if nothing answers on http_addr and a Pat binary is found, it starts pat http as a child process (Windows: no console window), restarts it with backoff (1 s doubling to 60 s) if it dies and stops it on shutdown. With auto, an installed pat-speedbird.service (systemd_unit) always wins, so the live Linux setup never gets a second main Pat; true also manages it when the unit exists but is inactive; false never starts one. The Winlink page shows a Pat card (version, binary and where it came from, systemd / managed / external, running, http address) with Start / Restart / Stop for the managed mode (GET /api/winlink/pat, POST /api/winlink/pat/{start,restart,stop}). * Which binary (find_pat): winlink.pat_bin if set (only that), $SPEEDBIRD_PAT, the bundled Pat (Windows <install dir>\pat\pat.exe, Linux /usr/local/bin/pat), then pat on PATH / /usr/bin/pat. * Bundled Pat. The .deb/.tar.gz carry the official Pat release binaries for amd64/arm64/armhf (third_party/pat/, sha256-pinned in speedbird.core.patbundle); the setup script installs it to /usr/local/bin/pat unless an installed Pat is at least as new (--without-pat / SPEEDBIRD_INSTALL_PAT=0 to skip). The Windows installer puts pat.exe in <install dir>\pat\, and Pat's files (config, mailbox) live in %LOCALAPPDATA%\SPEEDBIRD\pat. Pat's MIT licence ships next to it with THIRD-PARTY-NOTICES.txt. * Connecting on another profile uses pat-speedbird@<profile>.service if you enabled it (e.g. to listen on the IC-7610 TNC), otherwise SPEEDBIRD starts a temporary pat http for that profile on a free localhost port, runs the session and stops it. If the main Pat is down, the main profile also gets a temporary instance.

# speedbird.yaml (all optional)
winlink:
  http_addr: 127.0.0.1:8080
  main_profile: ic7300mk2
  listen: [ic7300mk2]        # Pat answers incoming P2P on these profiles (LISTEN ON at the SBP TNC)
  manage_pat: auto           # auto | true | false: run the main `pat http` when no systemd unit does
  pat_bin: ""                # explicit Pat binary (default: $SPEEDBIRD_PAT, bundled, PATH)
  max_attachment_bytes: 120000

Connect strings (POST /api/winlink/connect {"connect": ...}): varahf:///K4MFC-6 (main profile), varahf://ic7610/K4MFC-6?freq=7105 (profile by name; freq retunes that SPEEDBIRD radio first), varahf://digiall-7300mk2/W1AW-10 (real VARA, RMS), sbp://ic7610/K4MFC-6, telnet, or a bare K4MFC-6.

Before dialing, Pat checks once per 100 days that a Winlink account exists for MYCALL (an internet lookup). If it cannot confirm it, it asks whether to activate an account over the air; the Winlink page shows the question.

Part 97: Winlink over amateur radio is not encrypted. No business/pecuniary content or obscured meaning; third-party traffic only where agreements allow it.

Pat by hand#

~/.config/pat/config.json:

{
  "mycall": "K4MFC",
  "varahf": {
    "addr": "localhost:8400",
    "bandwidth": 2300,
    "rig": "",
    "ptt_ctrl": false
  }
}

Leave rig empty and ptt_ctrl false. SPEEDBIRD tunes and keys the radio itself. Then:

pat connect varahf:///K4MFC-6          # P2P to another SPEEDBIRD station's MYCALL

The ?freq= part only matters to Pat when it controls a rig. To QSY through SPEEDBIRD, use the connect string API with sbp://<radio>/<call>?freq=…, or tune the radio in the UI.

Open a Vara HF P2P (or Vara HF Winlink) session, then Settings → VARA TNC Setup: * VARA TNC host: 127.0.0.1 (or the SPEEDBIRD host, if you exposed the port) * Command port 8400, data port 8401 * Turn off "automatically start VARA". There is no VARA program to start. * Radio setup: no PTT and no rig control from Winlink Express. SPEEDBIRD owns the radio.

The station you call must also run SPEEDBIRD. A real VARA station cannot decode SBP.

How the byte stream rides on SBP#

Connect strings#

POST-style execution: connect.execute(connectstr.parse(s), sbp, vara, radios).

string meaning
sbp:///K4MFC-6?freq=7105 SBP on the radio already running the modem; QSY to 7.105 MHz (Pat: freq in kHz)
sbp://ic7300mk2/K4MFC-6?freq=7.105MHz SBP on radio ic7300mk2 (starts the modem if needed)
varahf:///W1AW-10?freq=7101.5&bw=2300 real VARA HF via the default vara: endpoint
varahf://172.19.2.150:8320/W1AW-10 the VARA endpoint at that host:cmd_port (or use the endpoint name as host)
varafm:///W1AW-10 the endpoint with kind: fm
ax25://vhf/WIDE1-1/LA1B-10 parsed. Like Pat, the last segment is the target and earlier ones are digipeaters (≤ 8). Not executable yet
ardop:///LA1B-10?freq=3601.5, telnet://K4MFC:pw@cms.winlink.org:8772/wl2k parsed, "transport not available"
C W1AW-10, C W1AW-10 via K4MFC-6,K4MFC-2, CONNECT W1AW-10 V WIDE1-1 classic (default transport SBP)
CONNECT K4MFC W1AW-10 VIA D1 D2 VARA host form: MYCALL then TARGET
W1AW-10@7.105, W1AW-10 on 7105 kHz USB-D bw 2300 target with frequency/mode/bandwidth

Frequencies: a bare number is kHz (as in Pat). A bare number below 100 is read as MHz and one of 1e6 or more as Hz. MHz/kHz/Hz suffixes are accepted. Callsign SSIDs are 0-15. Via limits: SBP 2 (SBP currently rejects any via, because mesh routing is pending), VARA 2, AX.25 8. user@ in a URL sets the mycall for that connect.