Winlink over SPEEDBIRD#
SPEEDBIRD supports Winlink in two ways:
- 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. - Connect strings (
src/speedbird/core/connectstr.py,connect.py). These are Pat-style URLs and classicC CALL via ...lines, executed on SBP or on a real VARA instance configured undervara: endpoints:(seedocs/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.1by default. Settinghost: 0.0.0.0lets 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, managed by SPEEDBIRD (recommended)#
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.
Winlink Express#
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#
- Host bytes are cut into SBP transfers after a 0.3 s pause or at 4 KB. Valid UTF-8 goes as an SBP
msg. Anything else, such as compressed B2F message blocks, goes as an SBP file named_tnc_data.bin. Both arrive byte-exact and in order at the peer's data port. The temporary file is then deleted. - B2F (
[WL2K-…],FC EM …,F>,FS, compressed blocks) passes through unchanged. - The SBP link drops a session after a few idle seconds. The TNC keeps the logical session open and re-opens the
SBP link on the next write. A TNC session ends on
DISCONNECT/ABORT, when the peer disconnects, when a transfer fails, or after 10 minutes without traffic. - While a TNC session is up, plain Console text messages from the same peer are also passed to the host program.
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.