WSJT-X / FT8 — OpenHamClock Manual

A Quick Primer on Weak-Signal Modes

WSJT-X is a free program by Nobel laureate Joe Taylor, K1JT, that implements a family of highly efficient digital modes designed to make contacts in conditions where voice or CW would be impossible. The most popular are:

Mode	Period	Sensitivity	Best use
FT8	15 seconds	−21 dB SNR	DX, casual contacts, POTA/SOTA — the most popular HF mode worldwide
FT4	7.5 seconds	−17 dB SNR	Contests — faster exchanges than FT8
JT65	60 seconds	−25 dB SNR	EME (moonbounce), very long-distance HF paths
WSPR	2 minutes	−28 dB SNR	Propagation beaconing — no QSOs, just signal reports across the globe

How Decodes Reach OpenHamClock

WSJT-X integration in OpenHamClock works entirely through the Rig Bridge WSJT-X Relay plugin. There is no direct connection between WSJT-X and OpenHamClock's server — Rig Bridge is the bridge between them.

The data flow is:

flow

WSJT-X → UDP port 2237 → Rig Bridge (WSJT-X Relay plugin) → SSE /stream → OpenHamClock browser

Step by step: WSJT-X sends every decoded message as a UDP packet to Rig Bridge. The WSJT-X Relay plugin parses the binary WSJT-X protocol, enriches each decode (grid → coordinates, band detection, callsign lookup), and immediately broadcasts it on the /stream SSE endpoint that OpenHamClock's browser is already connected to. The decode appears in the dashboard within a second.

ℹ️

Rig Bridge must be running

WSJT-X decodes only reach OpenHamClock if Rig Bridge is running and the WSJT-X Relay plugin is enabled. This also means the radio control connection is active — tuning a decode in OpenHamClock tunes your radio at the same time.

Setup

Step 1 — Enable the WSJT-X Relay plugin in Rig Bridge

Open the Rig Bridge setup UI

Navigate to http://localhost:5555 in your browser. If Rig Bridge is not yet installed, see Rig Bridge first.
Go to the Plugins tab and enable WSJT-X Relay

Find WSJT-X Relay in the plugin list and toggle it on. The default UDP port is 2237 — leave it as-is unless you have a conflict. Click Save.

Step 2 — Point WSJT-X at Rig Bridge

WSJT-X needs to know where to send its decoded packets. In WSJT-X: File → Settings → Reporting tab.

UDP ServerTick the UDP Server checkbox to enable packet output

Server name127.0.0.1 — if WSJT-X and Rig Bridge run on the same machine

UDP port2237 — must match the port set in the Rig Bridge plugin

Accept UDP requestsTick this to allow OpenHamClock to send reply commands back to WSJT-X

💡

WSJT-X on a different machine

If WSJT-X runs on a separate shack PC from Rig Bridge, set the UDP Server hostname to the IP address of the machine running Rig Bridge (e.g. 192.168.1.50). In the Rig Bridge plugin settings, set UDP Bind Address to 0.0.0.0 so it listens on all network interfaces, not just localhost.

Step 3 — Verify

Start a decode session in WSJT-X on any band. Within one 15-second FT8 period, decoded callsigns should appear in OpenHamClock's WSJT-X panel. The panel header shows a green indicator when the live SSE stream is delivering decodes.

What the Plugin Does with Each Decode

The Rig Bridge WSJT-X Relay plugin does more than pass packets through. For every decode it receives, it:

Parses the FT8 message — identifies CQ calls vs. QSO exchanges, extracts the caller callsign, the DX callsign, any modifier (DX, POTA, etc.), and the grid square if present in the message text.
Converts grid to coordinates — Maidenhead locators found in messages are immediately converted to latitude/longitude so the station appears on the map.
Detects the band — the dial frequency (in Hz) is mapped to a band name (160 m, 80 m, 40 m, 20 m, etc.) for colour-coding.
Deduplicates — the same decode from multiple propagation paths (e.g. multicast) appears only once in the panel.
Caches callsign → grid mappings — if a callsign has been seen with a grid before, that grid is reused for future decodes without one, for up to 2 hours.
Optionally looks up unknown callsigns on HamQTH — if a callsign has no grid in the decode, Rig Bridge can look it up asynchronously. When the result arrives, the map marker updates automatically. Enable this in the plugin settings.

The WSJT-X Panel in OpenHamClock

📻 Screenshot: WSJT-X panel with live FT8 decodes assets/img/screenshots/wsjtx-panel.png

The WSJT-X panel showing live FT8 decodes arriving from Rig Bridge. CQ calls are highlighted. Each row shows time, SNR, frequency offset, decoded message, derived band, and distance. Clicking a callsign draws the path on the map; clicking the row tunes the radio.

Each decoded row shows:

TimeUTC time of the decode period (HH:MM:SS)

SNRSignal-to-noise ratio in dB. More negative = weaker signal. FT8 is reliable down to −21 dB.

ΔtTime offset of the signal in seconds — how far off the 15-second boundary the station is

FreqAudio frequency offset within the passband, in Hz

MessageThe raw decoded FT8 text — e.g. CQ DX W1AW FN31 or K0CJH W1AW -12

BandDerived from the WSJT-X dial frequency (e.g. "20 m")

DistanceCalculated from the grid square if available

CQ calls are highlighted in the panel. Clicking any row:

Draws the great-circle path from your QTH to the station on the world map
Tunes your radio to the dial frequency (via Rig Bridge)
Opens a popup with the callsign, grid, country, and distance

Sending Commands Back to WSJT-X

The connection is bidirectional. When you click a callsign and enable Accept UDP requests in WSJT-X's settings, OpenHamClock can send commands back through Rig Bridge to WSJT-X:

Auto-replyClicking a CQ decode queues an automatic reply in WSJT-X — it will respond on its next TX period

Halt TXStops transmission from the WSJT-X panel in OpenHamClock

Highlight callsignHighlights a callsign in WSJT-X's own decode window

Other Digital Mode Software

The same Rig Bridge plugin architecture supports additional digital mode programs, each listening on its own UDP port:

Software	Plugin name	Default UDP port	Modes
WSJT-X	WSJT-X Relay	2237	FT8, FT4, JT65, JT9, MSK144, WSPR, Q65
JTDX	JTDX	2238	FT8, JT65 (with enhanced decoding algorithms)
MSHV	MSHV	2239	MSK144, Q65, FT8, JT65, FT4
JS8Call	JS8Call	2242	JS8 (keyboard-speed messaging over weak-signal paths)

Each plugin is enabled independently in the Rig Bridge Plugins tab. You can run multiple at the same time if you use more than one program simultaneously. In each piece of software, point the UDP output to Rig Bridge at the corresponding port.

WSPR Decodes

WSPR decodes are handled by the same WSJT-X Relay plugin — WSJT-X transmits WSPR packets using the same UDP protocol as FT8 decodes. Each WSPR report includes the transmitting station's callsign, grid square, power level, SNR, and drift.

OpenHamClock plots WSPR reports on the world map as a signal density overlay, giving an instant visual picture of HF propagation on the selected band. A WSPR decode appearing from a distant continent is confirmation that your antenna and receiver are working — even if no one is calling CQ.

Using a Cloud-Hosted OpenHamClock

If your OpenHamClock instance is hosted in the cloud (openhamclock.com or your own Railway deployment), the browser tab is served from a remote server and cannot reach Rig Bridge directly over your LAN.

The solution is to enable the Cloud Relay in Rig Bridge alongside the WSJT-X Relay plugin. Rig Bridge will forward decoded spots to your cloud OpenHamClock server in batched HTTPS posts, authenticated with a relay key. Configure this in Rig Bridge: Plugins → WSJT-X Relay → Relay to server, entering your cloud OpenHamClock URL and the relay key from OpenHamClock's Settings → Rig Bridge page.

ℹ️

Retry and reliability

When relaying to a cloud server, Rig Bridge batches decodes every 2 seconds and retries failed posts with exponential backoff. If the cloud server is temporarily unreachable, decodes are queued and delivered when the connection recovers. A heartbeat is sent every 30 seconds to keep the session alive.

PSKReporter & Reverse Beacon Network

These two data sources are independent of Rig Bridge — they are global reporting networks that OpenHamClock queries directly, with no local software required.

PSKReporter

PSKReporter is a crowdsourced network of receivers that automatically report every digital mode signal they decode. OpenHamClock shows PSKReporter data in two tabs:

TX tab Who is hearing your signal right now — every station that decoded your callsign in the last 15 minutes, plotted on the map. The best real-time propagation check available.

RX tab Who you are hearing — all callsigns your receiver has decoded, useful for assessing your antenna's receive coverage.

Data arrives via MQTT WebSocket in near-real time when available, or falls back to the HTTP API polled every 2 minutes. PSKReporter uses your callsign from .env automatically — no registration needed.

Reverse Beacon Network (RBN)

The Reverse Beacon Network is a global grid of automated CW and RTTY skimmer receivers that spot every CQ call they hear. OpenHamClock shows RBN skimmer locations on the world map and lists recent CW spots in the RBN panel — useful for contest operating and confirming your CW signal is being heard.