Latest WSJT-X state snapshot plus listener/connection health.

Returns the most recent Status broadcast — dial frequency, mode/sub-mode, Tx Enabled / Transmitting / Decoding, DE/DX call & grid, Rx/Tx DF, T/R period, special-operation mode (e.g. FIELD DAY), configuration name, current Tx message — together with the discovered instances and the transmit-gate state.

If no Status has arrived yet, that is reported with guidance (WSJT-X must have its UDP Server pointed at this host:port).

Host + network + listener diagnostics for troubleshooting connectivity.

Does NOT command WSJT-X. Reports the resolved WSJTX_HOST/PORT, whether the UDP listener is bound (and any bind error), datagram counts by message type, the discovered instances, the transmit-gate state, and this host's network interfaces — so you can tell whether this process can even receive WSJT-X's broadcasts (e.g. host-side vs. sandboxed, or a port already owned by JTAlert / GridTracker).

The RX data plane: buffered Decode / WSPRDecode lines.

operations:

• read (limit): the most recent N decodes (default 50).

• drain: every decode seen since the last drain — the polling primitive for automation. Advances an internal cursor so each line is returned once.

• clear_local: empty our local buffer (does not touch WSJT-X).

• replay: ask WSJT-X to re-broadcast its current Band-Activity decodes (each with New=false) followed by a Status — useful to backfill state on connect. (No transmit; safe.)

Each decode carries: kind (decode/wspr), New, time, snr, delta_time, delta_frequency, mode, message, low_confidence, off_air, and a seq you can pass to the reply tool.

Read buffered completed QSOs (QSOLogged paired with LoggedADIF).

Observe-only: WSJT-X emits these when the operator accepts its "Log QSO" dialog. Each entry has the structured QSO record (call, grids, frequency, mode, reports, times, exchanges, propagation mode) and the one-record ADIF document — ready to forward to N3FJP via contest-mcp.

Answer a buffered decode — initiates a transmission (gated by callsign).

Equivalent to double-clicking that decode in the Band Activity window. WSJT-X only acts if the message exactly matches a prior decode that is a CQ or QRZ. If WSJT-X's "Auto Seq" is on (the usual FT8/FT4 default) it then sequences the rest of the QSO to completion on its own; if Auto Seq is off this starts only the first transmission (Auto Seq is a UI setting, not UDP-controllable).

Identify the decode by seq (from the decodes tool) or by exact message text (the most recent matching buffered decode is used). modifiers may be a name or list (shift, ctrl/cmd, alt, meta, keypad, group) to mimic modifier-clicks.

Set the free-text (Tx5) message; with send=true initiates TX (gated).

Setting the text alone (send=false) is safe and always allowed. With send=true the message is transmitted — that keys the radio, so it requires WSJTX_CALLSIGN. An empty text with send=true sends the current free text unchanged; empty text with send=false clears it.

Stop transmitting. (WSJT-X's UDP protocol can halt but cannot enable Tx.)

operations:

• halt: stop immediately (takes you off the air now).

• halt_auto: stop at the end of the current transmission period.

Always allowed — halting only ever takes you off the air. To start a transmission use reply (answer a CQ) or free_text with send=true.

Set operating parameters via a Configure message (no transmit).

Sets: mode, submode, frequency tolerance, fast mode, T/R period, Rx DF, DX call, DX grid, and whether to regenerate the standard messages. Empty string = "no change" for text fields; None = "no change" for the numeric fields.

IMPORTANT caveats:

• There is no dial-frequency control over UDP. QSY is a rig-control concern (Hamlib/CAT or the WSJT-X UI), not this tool.

• The protocol has no "no change" for the two booleans, so fast_mode and generate_messages are always sent (defaulting to false). Pass them explicitly if you care about their state.

Clear a WSJT-X decode window (no transmit).

window: 'band' (Band Activity, default), 'rx' (Rx Frequency), or 'both'.

Colour (or clear) a callsign in the Band Activity panel (no transmit).

operations:

• set (callsign, background, foreground, highlight_last): apply colours. Colours accept a name (red, yellow, …), '#RRGGBB', or [r,g,b].

• clear (callsign): cancel highlighting for one callsign (sends an invalid colour).

• clear_all: cancel every highlight at once.

Keep the number of active highlights modest (a rough cap of ~100) so WSJT-X decoding performance isn't impacted.

Override the session Maidenhead grid (4- or 6-character). No transmit.

Session-lifetime only — does not change the persistent setting. Intended for mobile/portable operation where the grid changes during a session.

Switch WSJT-X to a named configuration (which must already exist). No transmit.

Set a Fox/Hound sort-order annotation for a DX call (no transmit).

Niche DXpedition feature (AnnotationInfo): lets a server "score" callers so the Hound queue can be sorted by it. sort_order is a number (lower sorts first); omit it to send "no sort order"; pass 4294967295 (0xFFFFFFFF) to remove a call's entry from WSJT-X's internal table.

Escape hatch: build and send any WSJT-X message type by name.

message is a type name (heartbeat, clear, reply, close, replay, halt_tx, free_text, location, highlight, switch_configuration, configure). fields is a dict of builder arguments for that type (see protocol.build_* signatures), e.g. message="configure", fields={"mode":"FT8","rx_df":1500}.

The same transmit gate applies: a keying message — reply, or free_text with send=true — is refused unless WSJTX_CALLSIGN is set.