Skip to main content
Documentation for qso-graph-interop v0.2.0. Source at v0.2.0.

QG Interop

QG Interop gives radio app developers Rust and C libraries for specification events and commands, and gives operators the qg-interop listener, capture decoder, and simulator.

The library implements QGI-SPEC-001 0.2.0 for WSJT-X message types 0–16, N1MM Logger+ XML, fldigi XML-RPC, PSK Reporter IPFIX submissions and MQTT captures, and QGI event carriage over UDP and TCP. Events preserve native evidence and distinguish observations from commands. Applications supply observer context and own transport and control policy.

What it covers​

listen joins an IPv4 multicast group on a named interface with --interface <IPV4>.

AppProtocol and transportDecodeCommandsExact re-encodeSimulatorCommand-line toolStatus
WSJT-XTypes 0–16, schemas 1–3; UDP✓✓✓sim --wsjtxlisten, decodeSupported
N1MM Logger+XML broadcasts; UDP✓✓✓sim --n1mmlisten, decodeSupported
fldigi 4.2.13XML-RPC; HTTP on loopback✓✓✓sim --fldigipoll, decodeSupported
These appsQGI event carriage; UDP or TCP✓Forwards events—sim --capture --qgi—Supported
PSK Reporter MQTTCaptured spots and receiver information✓—✓—decode --pskreporter-mqttSupported
PSK Reporter IPFIXReception submissions; UDP✓Submission encoder✓sim --pskreporter-ipfixcollectSupported
rigctld, DX cluster, ADIF over UDP, KISSVariousDesigned for, not yet mapped
  • Decode: native messages become specification events, with the original bytes kept as evidence.
  • Commands: events become native requests to the app: WSJT-X replies and controls, N1MM frequency and spectrum requests, and fldigi XML-RPC calls.
  • Exact re-encode: an event rebuilds the native message, checked against the original bytes.
  • Simulator: qg-interop sim produces the app's traffic, so you can develop and test without the app running. See Collect IPFIX submissions for a local PSK Reporter workflow. Every callsign it uses is invented, with a Q prefix.

Every row marked Supported is checked by the specification's test vectors, and also works through the C ABI (qso-graph-interop-ffi).

Install​

From this checkout with Rust 1.99.1 installed:

cargo install --path crates/qso-graph-interop-cli --locked

First use​

Listen on the default local address, 127.0.0.1:2237:

qg-interop listen --wsjtx

In another terminal, send a short synthetic exchange to the listener:

qg-interop sim --wsjtx --to 127.0.0.1:2237

The listener emits one specification JSON event per line. Its events describe heartbeats, radio state, decodes, logged QSOs, and shutdown messages. Each observation includes the complete native datagram. Decode one captured native message from a file or standard input:

qg-interop decode --wsjtx capture.bin
qg-interop decode --wsjtx - < capture.bin

Listen to N1MM Logger+ broadcasts on 127.0.0.1:12060 with qg-interop listen --n1mm, or decode a captured XML datagram with qg-interop decode --n1mm capture.xml. See the N1MM guide.

Poll local fldigi state and received text as specification NDJSON:

qg-interop poll --fldigi --interval 1000 --count 3
qg-interop decode --fldigi response.xml --request-method rig.get_frequency

The poller uses 127.0.0.1:7362 and accepts numeric loopback addresses. See the fldigi guide for setup and library examples.

See the event JSON guide. Each command's --help includes examples.

Use the library​

Install with cargo add qso-graph-interop. Default features select wsjtx, n1mm, fldigi, qgi, and serde. Use default-features = false for the core without protocol families or enable conformance to test a third-party codec. The public Codec trait decodes observations, encodes commands from common fields into ordered requests with response metadata, and separately re-encodes native evidence. Typed views expose common fields while preserving the complete event JSON. Stream input uses caller-owned buffers with explicit progress; QGI event carriage has a separate encoding capability.

C and C++ apps can use the C ABI as shared or static libraries. Consumers need no Rust toolchain. The ABI also supports Python, .NET, and Node bindings.

See the library example, protocol documentation, and contribution guide.

Security​

The library forbids unsafe Rust and opens no sockets. The command-line tool accepts numeric addresses and defaults to loopback. Parser, field, context, and event limits are checked before output is published. Shipped dependencies use compatible ranges and committed lockfiles, with cargo-vet, cargo-deny, and cargo-audit checks. See SECURITY.md for private vulnerability reporting.

License​

GPL-3.0-or-later.

Decode a local MQTT capture with qg-interop decode --pskreporter-mqtt capture.json. See PSK Reporter MQTT captures for JSON and NDJSON input.