Mercury — HERMES HF Modem

Mercury is part of the HERMES project (High-Frequency Emergency and Rural Multimedia Exchange System) by Rhizomatica, funded by ARDC and others.

Mercury is a software modem for sending email, files and messages over HF radio — the kind of link you have when there is no internet, no phone network and no power grid worth speaking of.

Start here: Getting Started · Graphical interfaces · Configuration · Docs · Mailing list · Google Play (Android) · App Store (iPhone, iPad)

Help wanted: Apple hardware. We build and test the macOS and iOS apps in a macOS virtual machine on an Intel PC, so we have never run the arm64 builds on real Apple hardware with a radio ourselves. Any ARM64 Apple device helps: an Apple Silicon Mac (M1 or later), an iPhone or an iPad, and any donation is welcome. Please write to the mailing list or open an issue.

What this software does

Mercury turns a single-sideband radio into a data link. It handles the waveform, the error correction, the retransmissions and the radio keying, and presents the result to your application as an ordinary TCP connection.

• ARQ data link for point-to-point sessions — a connect/accept handshake, an erasure-coded "carousel" that the receiver drives (Reed-Solomon blocks, so a lost frame is replaced by any other frame of the block rather than resent), and a controlled disconnect, so a file either arrives intact or you are told it did not.
• Adaptive speed — each direction runs on one of seven rungs, from the 32-tone MFSK floor through DATAC15, DATAC4, DATAC3, DATAC1 and DATAC17 up to QAM16C2. It starts on the rung the connect's SNR supports and moves on measured delivery. Control frames ride DATAC16 (and MFSK, or tone patterns, at the floor), so signalling survives when payload cannot.
• Broadcast mode alongside ARQ, with its own framing and TCP ingress port — used for one-to-many traffic and for Reticulum mesh networking.
• VARA-style TCP TNC interface on two sockets (control on the base port, data on base+1), speaking MYCALL, LISTEN, CONNECT, BUFFER, SN, BITRATE, TUNE (a 1 kHz ATU tuning carrier with a hard 60 s unkey timer) and MONITOR (a passive VARA-style monitor that decodes every mode). Existing VARA-aware software can generally talk to Mercury unchanged.
• Runs on the audio hardware you have — alsa, pulse, oss, coreaudio, aaudio, dsound, wasapi, rtp (to hermes-radio-daemon), hl2 (a Hermes-Lite 2 on the network, with no sound card or CAT), plus shm, null, fifo and sock for embedded and test use.
• Keys the radio for you via Hamlib, serial RTS (including DigiRig), or the HERMES shared-memory interface — or stays out of the way and lets your client do it.

Mercury runs on Linux, Windows and macOS, including Raspberry Pi.

On-air compatibility. 1.9.20 and later (the "2.0" architecture) connect to each other, but not to 1.9.19 or older in either direction: their connect frames have a packet type of their own (and 1.9.18 and 1.9.19 did not connect to each other either). A station with mfsk_tx_only set needs 1.9.21 or later at the other end. See docs/RELEASE-1.9.24.md, docs/RELEASE-1.9.23.md, docs/RELEASE-1.9.22.md, docs/RELEASE-1.9.21.md, docs/RELEASE-1.9.20.md, docs/RELEASE-1.9.19.md and docs/UPGRADING-TO-1.9.18.md before upgrading.

Command-line reference

Most settings live in mercury.ini (see Configuration File); command-line flags override it. Run ./mercury -h for this list at any time.

Usage modes:
./mercury -m [mode_index] -i [device] -o [device] -x [sound_system] -p [arq_tcp_base_port] -b [broadcast_tcp_port] -f [freedv_verbosity] -H [hamlib_log_level] -k [rx_input_channel] [-P ptt_method] [-A ptt_device] [-G] [-T] [-U ui_port] [-W] [-d]
./mercury [-h -l -z -K -Q -V]

Options:
 -c [cpu_nr]                Run on CPU [cpu_nr]. Use -1 to disable CPU selection, which is the default.
 -m [mode_index]            Startup payload mode index shown in "-l" output. Used for broadcast and idle/disconnected ARQ decode. Default is 1 (DATAC3)
 -s [mode_index]            Legacy alias for -m.
 -f [freedv_verbosity]      FreeDV modem verbosity level (0..3). Default is 0.
 -H [hamlib_log_level]      Hamlib radio log level (0..6). Default is 0.
 -k [rx_input_channel]      Capture input channel: left, right, or stereo. Default is left.
 -i [device]                Radio Capture device id (eg: "plughw:0,0").
 -o [device]                Radio Playback device id (eg: "plughw:0,0").
 -x [sound_system]          Sets the sound system or IO API to use: alsa, pulse, oss, coreaudio, aaudio, dsound, wasapi, hl2, shm, rtp, null, fifo or sock. Default is alsa on Linux, dsound on Windows.
                            null, fifo and sock are developer/test backends; fifo uses raw s32le PCM at 8 kHz via -i/-o paths; sock is a framed, virtual-clock lockstep transport (MERCURY_AUDIO_SOCK=<path>).
                            rtp exchanges the radio signal with hermes-radio-daemon as RTP multicast: -i <rx group>[,iface] (default 239.255.72.1,lo), -o <tx group> (default 239.255.72.2); PTT travels in the TX stream.
                            hl2 uses a Hermes-Lite 2 on the network as radio and sound card: -i auto (the first that answers a broadcast) or -i <host>[:port]; set its frequency with -F (or [hl2] in the INI).
 -F [frequency_hz]          Hermes-Lite 2 (-x hl2) dial frequency in Hz, upper sideband. Without one it receives but never transmits.
 -p [arq_tcp_base_port]     Sets the ARQ TCP base port (control is base_port, data is base_port + 1). Default is 8300.
 -b [broadcast_tcp_port]    Sets the broadcast TCP port. Default is 8100.
 -U [ui_port]               Sets the UI port (WebSocket port). Default is 10000. Requires -G.
 -W                         Disable waterfall/spectrum data sent to the UI (used to spare CPU). Requires -G.
 -G                         Enable UI communication (WebSocket server for mercury-qt). Off by default.
 -T                         Use WSS (WebSocket Secure/TLS) for UI communication. Requires -G. Default uses plain WS (no TLS).
 -l                         Lists all modulator/coding modes.
 -z                         Lists all available sound cards.
 -v                         Verbose mode. Prints more information during execution.
 -d                         Trace mode. Logs the raw bytes of every decoded connect frame (implies -v).
 -L <path>                  Write log to file (TIMING level and above). Windows default: logs\mercury_engine.log beside mercury.exe.
 -J                         Use JSONL format for log file (requires -L).
 -P [ptt_method]            PTT method: none, hamlib, serial, cm108, or hermes_shm.
 -R [radio_model]           Sets HAMLIB radio model and selects Hamlib PTT.
 -A [ptt_device]            PTT serial device or HAMLIB device/ip:port endpoint.
 -S                         Select HERMES shared-memory PTT (Linux shorthand for -P hermes_shm).
 -C [config_file]           Path to init configuration file (INI format). Default is mercury.ini in the current
                            directory, else $XDG_CONFIG_HOME/mercury/mercury.ini (~/.config/mercury/mercury.ini),
                            else /etc/mercury/mercury.ini. A file that is there but cannot be read in full
                            stops the modem.
 -K                         List HAMLIB supported radio models.
 -Q                         Test PTT: key the configured backend for one second, release it, and exit.
 -t                         Test TX mode.
 -r                         Test RX mode.
 -V                         Print version information and exit.
 -h                         Prints this help.

Mode behavior notes: - -m / -s sets the mode for broadcast, for the test modes, and for what the payload decoder listens on while no ARQ session is up. It does not affect an ARQ session. mercury -l lists the indices: 0 DATAC1, 1 DATAC3, 2 DATAC0, 3 DATAC4, 4 DATAC13, 5 DATAC14, 6 FSK_LDPC, 7 DATAC15, 8 DATAC16, 9 DATAC17, 10 QAM16C2, 11 MFSK. - During an ARQ session, control frames use DATAC16, and each direction's payload runs on the carousel's rungs: MFSK, DATAC15, DATAC4, DATAC3, DATAC1, DATAC17, QAM16C2. The start rung comes from the SNR measured on the connect; see docs/CAROUSEL-ARQ.md. - VARA BW500 keeps the link narrow; BW2300 and BW2750 allow the full Mercury payload-mode ladder. - CALL advertises the local BW token and ACCEPT returns the negotiated session token. If either side uses BW500, the link stays narrow; BW2750 is preserved in CONNECTED ... BW only when both peers advertise it. - FSK_LDPC is currently experimental (mainly for lab/test usage), may have longer decode/sync latency depending on setup, and is not recommended for production links yet. - [arq] mfsk_tx_only = true makes the station transmit MFSK only (CALL/ACCEPT, control and payload) for radios that can only key FSK — the QRP Labs QDX, QRPguys AFSK III and similar. Its peers keep its transmit direction on the MFSK floor rung for the whole session; receive is unaffected, so the cost is throughput, not reach. Such a station connects only to releases after 1.9.20; the others still connect to 1.9.20. - [arq] max_keydown_s = 16 holds every transmission of the station to 16 s, a poll sent before a round included, for TCP clients that abort when PTT stays on too long. vARIM 1.13 and later need no setting: they allow 35 s keyed, longer than any Mercury transmission (30 s at most). vARIM before 1.13 gives up after about 20 s keyed, and a fu