Winlink — Email over Amateur Radio

With the Winlink module, HAM-Tools sends and receives email over the Winlink network — to other radio amateurs (by callsign) or to regular email addresses. The far end does not need internet: the worldwide network of CMS servers and RMS gateways delivers the messages. That is exactly what makes Winlink the standard for emergency communications and for operating far away from any infrastructure.

The complete protocol engine (B2F/FBB, compression, secure login) lives in the in-house, open-source Swift package WinlinkKit — no external programs are required.

New in 1.33.0

The Winlink module is new — the internet path (telnet/CMS) is live-verified on the Winlink network. From 1.34 the radio paths follow: native ARDOP with a bundled modem and VARA over the network, plus contact and signature management.

Opening the module

Winlink sits in the sidebar with the main applications (below SSTV). Like the logbook and SSTV it takes over the whole window: folders on the left (Inbox, Drafts, Outbox, Sent, Trash), the message list with search in the middle, the reading pane on the right. ‹ Overview takes you back.

Setup (one-time)

You need a (free) Winlink account — it is created automatically on the first connect with your own callsign, or beforehand at winlink.org. Then in Settings → Winlink:

1. Enter the password of your Winlink account. It is stored exclusively in the macOS keychain — never in files.
2. Callsign and locator are taken from the Station tab automatically. The fields in the Winlink tab normally stay empty; an entry there applies to Winlink only (e.g. HB9HJI/P for portable operation).
3. CMS server: the default is production (server.winlink.org). The test server (cms-z.winlink.org) is suitable for connection tests — note: it does not deliver anything (isolated message store).

Composing messages

Compose in the toolbar opens its own window:

• To/Cc: Winlink callsigns (HB9XYZ) or email addresses (name@example.com), mixed and multiple (separated by comma/semicolon).
• Attachments via the paperclip — Winlink transfers them compressed; over radio the rule is: the smaller, the better.
• Image attachments are shrunk automatically from 1.39 — the Images menu offers four target sizes (small ~50 KB, medium ~150 KB, large ~400 KB, original), medium by default. The original is kept in the window, so changing the target recomputes without loss. Below the attachment bar you get the estimated transfer time for ARDOP 500 and ARDOP 2000 — a 4 MB photo takes over an hour on ARDOP 500, and just under two minutes once shrunk to 50 KB.
• Signatures: the default signature is inserted automatically and can be switched per message via the signature menu (management from 1.34 in Settings → Winlink).
• Save as Draft (⌘S) files the message under “Drafts” — saving again updates the draft instead of piling up copies.
• Put in Outbox (⌘⏎) queues the message for the next exchange.

From the reading pane there are Reply, Reply All and Forward; in the Drafts folder the pencil button opens a draft to continue writing.

Send & Receive

The Send & Receive button (⇧⌘R) connects to the Winlink CMS via telnet, authenticates with secure login, transfers the outbox and fetches new messages. The status bar at the bottom shows live progress; after the session it shows the summary (“1 message sent, 2 received”).

• Log opens the full session log (copyable, with a jump to the log folder). Every session is also written to a file under HAM-Tools/Winlink/Logs/.
• Sent messages move to Sent, received ones appear unread in the inbox (blue dot, badge on the folder).

From 1.34: the arrow next to “Send & Receive”

The button becomes a split button: click = internet (CMS), arrow menu = radio via ARDOP or VARA — see Radio operation.

Inbox, folders & search

• Custom subfolders below the inbox can be created and nested freely (e.g. QSL/2026); move messages there — the unread state moves along.
• Delete moves to the Trash; deleting there is final.
• The search above the list filters the active folder by sender, recipient, subject and message text.
• Technically all messages are stored as individual .b2f files (the Winlink standard format) under HAM-Tools/Winlink/Mailbox/ — compatible, portable and backup-friendly.

Contacts from 1.34

Contacts in the toolbar opens the address book: contacts with callsign, additional email addresses, QTH/locator, notes; favorites and freely named groups (simply enter them comma-separated on the contact). In the compose window the contacts picker sits next to To/Cc — favorites first, contacts with several addresses as a submenu.

Radio operation: ARDOP & VARA from 1.34

Without internet, the exchange runs via an RMS gateway on HF/VHF. The arrow menu next to “Send & Receive” opens the connect dialog with a gateway picker, bandwidth choice and manual callsign entry.

Step by step

The complete path to your first mail over radio — audio, PTT path, drive level, choosing a gateway and the traps along the way: Tutorial: Your first Winlink mail over ARDOP.

Gateway directory from 1.39

Which gateways are worth considering at all is fetched straight from the Winlink web services — for ARDOP, VARA HF and VARA FM. The picker in the connect dialog shows a short list (favourites first, then the nearest); the full directory lives in the Gateways window (⌥⌘G, also under Window ▸ Winlink).

For every channel it lists distance and bearing from your own locator, plus band, dial frequency, bandwidth and origin. Sorting by distance answers the practical question directly: which gateway is closest from here? Search by callsign or locator, filter by band, and star the stations you use regularly — favourites always sit at the top of the picker. Right-click offers “Connect via …” and “Copy dial frequency”.

Distance is computed locally

The service's own figure is not used; the distance is recomputed from your locator. That way it still holds when you move and change your locator without fetching the list again.

How often it refreshes: at most once a day, in the background. Winlink asks that the service be queried sparingly, so the app also throttles the refresh button — the window then shows “earliest again at HH:MM”. Without a connection the local cache applies, and until a first fetch has happened, the built-in Swiss starter channels. A locator in the settings is a prerequisite: without one there is no proximity search. Daily refresh and search radius (300 to 3000 km) are under Settings → Winlink.

ARDOP (recommended, fully native): HAM-Tools ships the ardopcf modem — all it needs is the USB cable to the rig. In Settings → Winlink under “Radio: ARDOP”:

1. Choose TNC “Integrated (ardopcf)”.
2. Set audio input/output to the rig’s USB audio codec (not the Mac microphone/speakers!). On the first connect macOS asks for microphone permission.
3. PTT: with Icom the easiest is CAT (CI-V) via the serial USB port (IC-7610: address 98, IC-705: A4). Alternatively RTS, rigctld or VOX.
4. Put the rig into data mode (USB-D) — with CAT PTT, HAM-Tools sets frequency and USB-D automatically when connecting via the gateway picker (auto QSY). After the session the rig stays on the gateway's channel; to get the previous state back, switch on Restore frequency after the session.

VARA (HF/FM): The VARA program is Windows-only — it runs on a Windows machine (or a VM) on the same network; HAM-Tools connects over TCP. Enter the host (IP of the Windows machine) and ports (8300/8301) under “Radio: VARA”; VARA keys the transmitter itself.

Where do I connect the rig — in the CAT module or in Winlink?

Once, in the CAT module. Winlink uses that connection from 1.39.1 onwards — there is nothing to set up twice. The PTT path “HAM-Tools CAT connection” is the default: keying and tuning go through the connection that is already up, and automatic QSY comes along. Serial port, CI-V address and baud rate stay where you entered them once — in the CAT module.

Before 1.39.1 the Winlink part carried its own rig configuration. That was a legacy of its origin (it comes from a standalone client without a CAT module) and led into a dead end: on macOS a serial port belongs to one program at a time, so the two connections excluded each other. If you still carry an older setting, the connect dialog offers a button that switches it over.

The other paths remain — for the cases where they are the right one:

• CAT (Icom CI-V) straight on the serial port, if you only run Winlink anyway and the CAT module is not connected. This path knows the rig's data mode most precisely.
• rigctld, if your rig hangs off an external instance (wfview or kappanhang for an IC-705 over WLAN, say). The CAT module's “share CAT” belongs here too: it keeps the Hamlib server on 127.0.0.1:4532 open, the same one WSJT-X uses to work in parallel.
• RTS or VOX, when no CAT is involved.

Who performs the QSY

For a gateway from the list, HAM-Tools sets frequency and USB-D itself — using whichever path currently applies. The footnote in the connect dialog names it. If no path is available, the dialog says you have to tune manually rather than promise a QSY that never happens.

Staying put after the session from 1.40.2

After the exchange the rig stays on the gateway's channel, and the last gateway used stays filled in in the connect dialog. The next call goes straight through the short path (“Receive & send” → arrow menu → over ARDOP) without retuning — and the display shows what you were working.

If you would rather find your rig the way you left it, switch on “Restore frequency after the session” under Settings → Winlink → Radio: ARDOP. HAM-Tools then puts frequency and mode back after the session — over the same path it used to change them.

Setting the drive level from 1.40

Over the air, link quality depends less on power than on a clean signal. The modem feeds audio to the radio, and in data mode (USB-D and relatives) that goes straight to the modulator — without the microphone chain that would otherwise limit it. Too much level overdrives, widens the signal and costs decodes; too little costs barely any range. Hence the rule of thumb: low enough that the rig's ALC meter just barely moves.

Up to 1.39 the modem always ran at full amplitude — the app could not set the level at all. Settings → Winlink → Radio: ARDOP now has a slider.

The level assistant does the work for you. It transmits a two-tone signal, raises the level step by step and reads the rig's ALC over the existing CAT connection. The step below the first one where the ALC responds is adopted.

The assistant transmits

Several seconds per step, on the frequency currently set. Only on a clear frequency or into a dummy load — and with an antenna or dummy load connected. You can cancel at any time; the transmitter is always unkeyed afterwards.

Whether measuring is possible depends on the PTT path — more precisely, on who holds the serial port:

PTT path	Measurement
HAM-Tools CAT connection	yes
rigctld	yes
VOX	yes, via CI-V
CAT (Icom CI-V)	no
RTS	no

With CI-V and RTS, ardopcf opens the serial port itself, and a port belongs to one program at a time — HAM-Tools then cannot reach the radio. The assistant says so before the start and sends the tone anyway: you read the ALC on the rig's display and move the slider by hand. If your rig does not report ALC at all, it says that too.

The rig-side half is not set by the app: the USB MOD Level in the radio (on Icom under MENU ▸ SET ▸ Connectors) is not reachable over CAT. Leave it at the factory value and do the fine adjustment with the level in HAM-Tools.

Good to know

• Messages to your own callsign count as delivered immediately at the CMS and do not come back. For testing: send a message to TEST (auto-reply bot) or write to your callsign from an external address.
• Spam protection: emails from senders your Winlink account does not know are discarded — either whitelist the sender address at winlink.org or start the subject with //WL2K.
• Gateway time budget: RMS gateways limit radio usage (typically 120 minutes per day and gateway) — the gateway reports the remaining budget on connect, visible in the log.