Skip to content

WebSDR transport protocol v1

This reference covers receiver control and binary IQ between the appliance gateway and the browser workstation.

The MkDocs contracts cover this boundary together with decoder/event/time contracts. Public identity and ports come from appliance configuration, not a compiled device name, IP or profile-specific receiver port.

Session shape

A client opens /ws/control with subprotocol rfsentry-control-v1 on the UI/API listener and sends auth.status. The workstation uses browser.session to resume a tab session or obtain local access when sign-in is disabled. When sign-in is required, browser.login accepts the appliance account's username and password over HTTPS. Read-only accounts can inspect permitted records. Receiver acquisition and tuning require control permission. Machine clients such as rfsentry-jobctl use auth with their configured credential. Browser access and roles

Then stream.endpoint advertises {port, scheme, path, protocol} for the dedicated external IQ listener. Defaults are API 8443 / IQ 8444, both configurable in /etc/rfsentry/appliance.conf and served by the same process/ TLS identity. The browser retains the page hostname, requires a distinct valid port, /ws/iq and rfsentry-iq-v1, and requires WSS for HTTPS. Plain WS is only accepted by the browser for loopback development. Discovery failure closes control; there is no silent API-port fallback. The IQ listener is not another web/API server.

session.open acknowledges a sessionId and separate opaque iqToken for that active session. Its acquisition state and asynchronous session.ready are distinct from the ack; none alone proves valid IQ or decoder lock. The lane's ingress worker opens the discovered IQ socket with rfsentry-iq-v1 and sends {"type":"stream.bind","token":"<session iqToken>"} as its first message. The gateway checks the token against an active, unbound session with a ten-second bind timeout. The client sends the type label; the current callback identifies the session by token, not a separate control-command dispatch. Further application messages after binding close that IQ connection. Never put tokens in URL queries, logs or exports.

Multiple adapters share the listener ports, not their leases: each lane has its own session, token, IQ socket and bounded queue. Control disconnect releases its owned sessions; IQ disconnect releases only its bound session. Reconnect requires a fresh session/token, not another USB/backend path. Explicit session close honors configured release grace; disconnect requests immediate gateway release, followed by the demand manager's independent idle deadlines.

The additive session.ready.payload.clockAnchor object pairs server realtime and monotonic clocks as decimal nanosecond strings:

{
  "unixNs": "1787810400000000000",
  "monotonicNs": "123456789000000",
  "uncertaintyNs": 25000,
  "quality": "server-paired",
  "epoch": 1
}

This clock example is synthetic. Strings preserve all 64 bits in JavaScript. The monotonic midpoint pairs with the realtime read; uncertainty is half the enclosing monotonic interval, rounded up to a nanosecond. Active sessions also receive clock.anchor refreshes; a material clock step advances its epoch. Decoder clients estimate a block's first-sample time, bind UTC once per capture epoch and advance by sample counters/rate, not independent arrival timestamps. Missing/malformed anchors stay unavailable. See time semantics.

Control requests use id, type, version: 1, and payload. Responses are ack or error correlated by requestId, not a response id. Asynchronous events have gateway-wide eventSequence values, not lane-contiguous IQ counters. Unknown commands are rejected; recognized handlers read their known fields.

Receiver session requests

auth.status / browser.session / browser.login / auth (machine clients)
stream.endpoint
receiver.list
session.open / session.tune / session.close
receiver.configure (alias of session.tune)
ping

The same control socket also supports continuous job management and record-source discovery and authorization. Readers consume appliance records on /ws/records on the API listener.

Open/tune use logical rfHz, sampleRate, centerOffsetHz, optional routeId, gainTenthDb, ppm and offsetTuningEnabled; open also supplies laneId and mode, while tune/configure addresses sessionId. The gateway derives tuner geometry from the reviewed route and normalizes supported tuner settings. receiver.acquire/release, stream.start/stop, scan.* and decoder.start/stop were draft commands, not implemented gateway requests. Browser decoder jobs and presentation controls do not add these network commands.

The gateway validates frequency, sample rate, gain, ownership and path policy. The browser never submits shell commands, service names, backend ports, USB indices or undocumented tuner registers. Bias-Tee policy is not a documented receiver.configure field in this implementation.

Binary IQ frame

All multibyte header integers use network byte order (big endian); signed fields below use two's-complement representation. The fixed header is 80 bytes. The live gateway emits v1.0 CU8 with at most 65,536 payload bytes (32,768 complex samples); quarantine can shorten a frame. The parser rejects invalid magic, major version, header length, format and exact payload length. Successful framing is not protocol CRC/FEC validation or proof of contiguous reception.

Offset Bytes Field Meaning
0 4 magic ASCII WSDR
4 1 major 1
5 1 minor 0
6 2 headerBytes 80
8 4 flags discontinuity flags below
12 4 sampleFormat enum below
16 8 sequence u64; increments per emitted frame within the receiver acquisition
24 8 sampleCounter u64; first payload complex-sample counter; includes discarded settling samples
32 8 monotonicNs u64; server completed-block timestamp, not UTC or exact ADC time
40 8 tunerHz u64; commanded tuner center, not driver-offset physical LO or hardware readback
48 8 rfCenterHz i64; logical capture RF center after route/center-offset transform, not browser VFO
56 4 sampleRate complex samples per second
60 4 sampleCount complex samples in payload
64 4 gainTenthDb signed; INT32_MIN means automatic
68 4 ppmMilli signed correction in 0.001 ppm
72 4 payloadBytes exact payload length
76 4 captureOptions u32; persistent capture-path bits, including 0x01 applied driver offset tuning

Byte 76 was reserved in the initial design; it is populated by today's emitter and retained by the parser/encoder without changing the emitted v1.0 header length. Capture options are not transient discontinuity flags or independent hardware verification. Gain likewise records command-path metadata, not readback.

Defined formats (the live gateway emits CU8 only):

Value Name Payload
1 CU8 interleaved unsigned 8-bit I,Q, midpoint 127.5
2 CS16LE interleaved signed little-endian 16-bit I,Q
3 CF32LE interleaved IEEE-754 little-endian float I,Q

Flags are bitwise: 0x01 GAP, 0x02 OVERFLOW, 0x04 RETUNED, 0x08 SETTINGS_CHANGED, 0x10 REPLAY, and 0x20 END. A retune begins a new continuous segment. Consumers reset state that cannot span discontinuities. Replay is defined for browser-generated frames; a live socket close does not promise a terminal End frame.

payloadBytes must equal sampleCount * bytesPerComplexSample, and total bytes must equal header plus payload. decodeIQFrameView exposes a non-owning payload view: its transport backing slot must remain valid until consumption finishes. decodeIQFrame returns an owning copy. Sequence/sample gaps remain evidence, not something presentation can conceal.

The first-sample estimate subtracts exact block duration from completed-block monotonic time before binding the epoch. Subsequent timing advances from source sample counters; live USB/callback uncertainty remains explicit. A discontinuity invalidates affected capture/decoder state; protocol input must not be concatenated across it. Replay uses source metadata/counters rather than browser arrival time.

Flow and backpressure

The queue is source-rate-sized, not negotiated: two seconds plus frame rounding, ceil(sampleRate * 2 / 32768) + 1 slots. Overflow drops a complete oldest queued frame, increments drop counters and marks the newly enqueued frame GAP|OVERFLOW; older queued frames can still be sent first. Sequence/sample counters reveal the actual lost range, not just the later flagged frame.

More than 512 consecutive enqueue overflows arms the slow-client close flag; dequeue resets that count. Writable processing then closes that IQ peer and releases its session. Other lanes retain their queues/leases. Quarantine advances sample counters across discarded settling samples and preserves pending change flags. See queue and release details.

Recording metadata

The original recording contract calls for SigMF where possible and audio WAV with a JSON provenance sidecar. Preserve tuner/RF centers, sample format/rate, receiver/path identity and revision, gain/PPM/capture options, retunes, gaps and UTC or explicit absence. This is a provenance requirement, not evidence that every general-purpose recording/export path is implemented.

Replay readers map SigMF core:datetime or an explicit raw-CU8 captureTime to a replay-metadata clock anchor at monotonic zero. The basic SigMF reader uses its first capture's frequency/time; stereo PCM16 IQ WAV uses left=I/right=Q and does not supply UTC. Missing/invalid time stays unavailable. Browser DVR's hot RAM/warm OPFS timeline, imported recordings and ASan .rfiq diagnostics are distinct paths; DVR retention is not proof of a complete SigMF recorder. See replay/storage.

Security boundary

Deploy the appliance on a trusted LAN. The gateway checks the WebSocket origin even when sign-in is disabled. In that mode, clients with network access and an accepted origin can acquire and tune a receiver. When sign-in is required, the browser session carries the account's permissions. Each IQ attachment also needs the token for its receiver session.

Keep TLS verification, receiver leases and bounded inputs enabled. A public-facing service would also need deployment-specific protections such as per-user resource limits. See the security policy.

Source and regression references

  • Gateway: src/server.c, src/receiver.c, src/util.c and include/rfsentry_api.h under components/rfsentry-api.
  • Browser: src/api/RfsentryClient.ts, src/api/types.ts, src/protocol/iqFrame.ts, src/transport/iq.ingress.worker.ts, src/replay/readers.ts and src/decoder/ClockMapper.ts.
  • Regression references: gateway test_iq.c / mock integration harness and browser rfsentryClient.test.ts, iqFrame.test.ts, decoderClock.test.ts.

This reference was checked against source; those runtime tests were not newly run as part of the documentation batch. PHASE0, ADRs and WEBSDR retain their original acceptance/decision evidence.