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.candinclude/rfsentry_api.hundercomponents/rfsentry-api. - Browser:
src/api/RfsentryClient.ts,src/api/types.ts,src/protocol/iqFrame.ts,src/transport/iq.ingress.worker.ts,src/replay/readers.tsandsrc/decoder/ClockMapper.ts. - Regression references: gateway
test_iq.c/ mock integration harness and browserrfsentryClient.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.