Skip to content

Continuous appliance decoding

An enabled appliance HRIT job can keep receiving after you close the browser. Its isolated decoder sends validated canonical records to a bounded RAM buffer owned by the gateway. An optional paired Server can subscribe and commit records to disk when ingestion is enabled for the stream.

Event What survives
Close the browser Enabled Pi jobs continue. The gateway keeps its bounded buffer. An active Server subscription can keep archiving. Browser-only decoder jobs end with the page.
Restart the Pi decoder service Saved enabled definitions resume with new decoder runs. Previously admitted records remain available within the still-running gateway’s retention limits. The interruption can leave a gap.
Restart the gateway Its RAM history is lost. Saved job definitions survive and enabled jobs can reacquire. Interactive clients reconnect.
Pi power loss RAM records are lost. Persisted configuration survives on intact storage. After startup, enabled jobs resume. Records already durably committed on an independent Server remain subject to that Server’s retention policy.

For overnight history that must outlive the Pi, enable and verify per-stream archiving on the Server. A displayed thumbnail or a connected reader alone does not establish durable progress.

Ownership and persistence

/etc/rfsentry/streams.d/ID.json is the authoritative model for configuration and API changes. No enabled jobs ship. The generic example under components/rfsentry-decoder/config/ requires an installed verified route and a freshly generated stream UUID. Do not clone appliance or stream identities. The installer generates /etc/rfsentry/appliance.uuid once and preserves it. Public identity/TLS/ports still belong to appliance.conf, not job files.

An enabled job holds the gateway's real acquisition demand without a fabricated browser lease. Startup resumes enabled definitions. Page/auth/discovery/status reads do not wake or retune receivers. One compatible legacy IQ attachment may use the capture; its detach removes only its demand. Incompatible route, capture center, sample rate, gain, PPM or driver-offset changes fail with the owning job named. Browser-only VFO movement is possible if capture stays compatible.

Disable releases job demand. A legitimate remaining browser retains capture; otherwise normal demand idle/deep-idle shutdown applies. Re-enable may reuse a compatible already protected capture without retuning. An ordinary existing legacy capture must first be released; it is not silently adopted. Failed decoder workers do not stop acquisition; hardware failures follow the existing lane-local supervision. Other receivers remain independent.

Controls

The C++ rfsentry-jobctl uses the configured canonical API origin and certificate with normal TLS verification. It never prints the token or puts it in a URL. It reads /etc/rfsentry/api.conf by default; --config FILE selects another API configuration. CANONICAL_ORIGIN and TLS_CERTIFICATE select the endpoint and trust certificate. The operator credential is loaded automatically from AUTH_TOKEN_FILE (default /etc/rfsentry/auth.token); no token argument or manual copying is needed. Installed credentials are restricted, so use sudo. An access-denied error names the file and shows the command to retry with sudo.

Help works without credentials, configuration or a running gateway:

rfsentry-jobctl --help
rfsentry-jobctl help disable
rfsentry-jobctl configure --help

The help covers job controls, Server pairing and record-delivery commands. Command responses remain JSON.

sudo rfsentry-jobctl list
sudo rfsentry-jobctl status continuous-hrit
sudo rfsentry-jobctl capabilities
sudo rfsentry-jobctl enable continuous-hrit
sudo rfsentry-jobctl disable continuous-hrit

list includes each job's ID, configured enabled flag, actual state, receiver, actuallyRunning, acquiring and fault. To stop one, use its ID with disable; this persists across restarts and upgrades. Use enable to resume it.

An explicit full appliance installation warns about active SDR clients and interrupts acquisition while updating services. It stops the gateway, decoder and demand service in that order, then starts demand, decoder and gateway. Saved enabled definitions resume automatically; disabled definitions stay disabled. The installer reports current job states/faults without treating a configured enabled flag as proof of acquisition or RF lock. --no-start leaves the services and jobs stopped. Interactive clients must reconnect themselves.

For a new definition: copy/adapt the disabled example, supply a fresh UUID, then sudo rfsentry-jobctl configure /path/job.json absent. For updates use the current configurationDigest, increment decimal-string revision, and retain streamUuid: sudo rfsentry-jobctl configure /path/job.json DIGEST. Enable/disable fetches the digest then performs compare-and-swap. Repeated requests for the current flag do not rewrite/increment configuration.

Manual edits also increment revision and preserve the stream identity:

sudo systemctl reload rfsentry-api
# Or authenticated API reconciliation:
sudo rfsentry-jobctl reload

Reload validates the entire desired set before reconciliation. Invalid/conflicting definitions leave the prior running model intact and expose configurationError. API writes use a lock, digest compare-and-swap, staged file, file fsync, rename and directory fsync. A concurrent manual/API change cannot be silently overwritten. Configuration acceptance is not startup or lock success: read requested/applied revision, state, fault, actuallyRunning, acquiring, and frameLocked.

Permissions and API

Job commands use /ws/control with the rfsentry-control-v1 subprotocol and the configured authorized origin. The rfsentry-jobctl client reads a credential from disk even when browser sign-in is disabled. Its operator token grants job status and control. To allow status checks without granting acquisition, tuning or job changes, configure a separate random host-only STATUS_TOKEN_FILE in api.conf and restart the gateway in a maintenance window. rfsentry-jobctl --read-only status ID uses that credential.

The browser uses its appliance access policy. Reading a stream on /ws/records uses a separate, scoped records.read grant. That grant confers no authority to start or tune the receiver.

Request Payload Permission
job.list {} read
job.capabilities {} read
job.configuration, job.status {"id":"ID"} read
job.watch {"id":"ID","enabled":true}; unsubscribe {"enabled":false} read
job.set-enabled id, boolean enabled, expectedDigest control
job.configure full configuration, expectedDigest (absent for new) control
job.reload {} control

job.watch selects one job per connection, at most one update/second. job.status.update has an exact decimal notificationSequence per connection; jumps indicate missed updates. This is status, not decoded record delivery.

Configuration evidence

Job schema 1 specifies decoder, stream UUID, revision, enabled flag, installed route, VFO/capture offset/rate/bandwidth, manual or maximum-manual gain, AGCs, PPM, supported driver offset and software residual constant. Maximum-manual is resolved from the actual RTL-TCP tuner steps; unsupported mandatory capability faults rather than silently changing it. Gain and offset acceptance are commands, not hardware readback. Physical LO geometry is driver-derived.

Canonical rfsentry.configuration.v2 adds gain/AGC/offset/residual/readback evidence without changing envelope 1.0 or configuration-v1 bytes. The first IQ supplies accepted settings. Configuration precedes frame records; each frame references its configuration hash/revision and original producer/stream/run identity. Delivery sequence is not the VCDU counter. See the exact wire layout.

Complete diagnostics

job.capabilities.diagnostics.metrics is the machine-readable, versioned inventory, with units, stage, derivation, availability and reset behavior. The complete snapshot is job.status.diagnostics; there is no curated-only health view hiding supported metrics. Exact uint64 counters, times and revisions are decimal strings. Null means unavailable, never zero/success.

Group Snapshot fields / interpretation
Identity/config schema, runEpoch, captureEpoch, clockEpoch, configurationRevision, configurationRecordPublished, workerPid
Input/channelizer sourceSamples, decoderSamples, channelizerTaps, channelizerDiscontinuities, sourceGapEvents, knownMissingSourceSamples, malformedInput, resets, clockChanges
Carrier/timing carrierTracking, carrierOffsetHz (decoder-baseband Hz), costasErrorNormalized, timingTracking, timingHypothesis, samplesPerSymbol, timingErrorClipped; independent carrier/timing lock verdicts unsupported
Signal means signalMetricsAvailability, powerWindowDecoderSamples, meanPowerNormalized, peakPowerNormalized, meanI, meanQ, decoderDcI/Q, agcSmoothedPower, residualI/Q; normalized amplitude/power, not SNR/dBm
Sync syncCandidates, frameSync, collecting, collectedCodedBits, lockLosses, reacquisitions, consecutiveFecFailures
Frame/ASM frameAttempts, validatedFrames, rejectedFrames, decodedAsmAttempts, decodedAsmFailures, uncorrectableRsFrames; rejected includes ASM/Viterbi/RS failures, not IPC loss
Viterbi viterbiAttempts, viterbiDecodeFailures, viterbiHardDisagreements, viterbiComparedCodedBits: hard decisions versus re-encoded survivor, including the 64-bit prelude; not RF BER
RS rsLanes[] lane/attempts/failures/correctedSymbols; every lane examined after ASM; correctedSymbols counts published frames only, per-lane totals also include corrections on otherwise rejected frames
Last successful frame lastValidDecoderSample, last valid monotonic/decode-UTC time, age; lastFrame payload hash, per-lane corrections/disagreements and raw transport header fields. No raw frame payload exposed.
Output outputRecords, outputWireBytes, outputFailures, deliberatelyDisposedRecords, nextDeliverySequence, outputPolicy; configuration/gap records also count
Processing processingNs, peakBlockProcessingNs, processedBlocks, lastProcessingLagNs, peakProcessingLagNs; lag starts at gateway enqueue, not physical RF arrival
Rates rates.windowNs, source/decoder samples/s, attempts/validated/rejected frames/s, legacy disposal-counter rate (handoff failures), processing seconds/wall second; null until two snapshots, actual interval as denominator
Resources cpuUserUs, cpuSystemUs from getrusage; peakRssKiB is peak RSS, not current/locked memory; memoryLock describes required provisioning
Notifications updateSequence, transitionSequence, notificationFailures, bounded transitions, oldestTransitionSequence, transitionHistoryLimit (32)
Freshness snapshotMonotonicNs, snapshotUtcNs, lastInputMonotonicNs, inputState; wrapper diagnosticFreshness and age also mark exited/older-run snapshots stale
Unavailable checks snrDb, rfBer, carrierLock, timingLock: unsupported; packetCrc, fileChecksum: not performed in this receive service. Missing attempts/passes/failures are null.

Cumulative native totals reset on a new decoder-run epoch, not source gaps. DSP/means reset at continuity boundaries with an explicit window denominator. Frame collection and consecutive-failure state have their own documented reset. Gateway handoff totals reset with controllerEpoch: sent/overflow blocks, known overflow samples, failures, decoder starts/restarts/startup failures/retries, kernel send-buffer and queued-byte observations. Socket pressure/IPC loss are separate from RF/FEC rejection. The wrapper also contains requested/applied configuration, complete available receiver capabilities/accepted command geometry, browser attachment, and bounded job-state transitions.

Transitions have exact sequence and host monotonic/UTC times. Coalescing never erases cumulative totals; history truncation and sequence jumps remain detectable. Snapshots are at most 1 Hz and contain no IQ or decoded payload. They never write configuration. Unsupported checks do not become green successes.

Time precision

Exact source lattice includes rational resampling and FIR delay. Completion cursor is not a proven physical frame start/end, which remain unknown. UTC anchor quality is estimated, with unknown USB/RTL-TCP latency and uncertainty. Decode time is separate; no product observation time is manufactured. Host steps start a clock epoch without resetting continuous RF samples. A decoder restart starts a run epoch; capture continuity survives decoder-only faults.

Isolation and RAM-only boundary

rfsentry-decoder.service forks one worker per internal stream (at most 16). AF_UNIX SOCK_SEQPACKET carries the existing 80-byte IQ header plus at most 64 KiB CU8. It is same-UID, local and bounded, before browser queues. The gateway uses nonblocking sends; a stalled/crashed worker cannot backpressure acquisition. Actual socket buffer/queue size and losses are exposed. Five-second startup and bounded 5..60-second retries avoid unbounded queues/restart loops.

Required gateway locked pools and child mlockall protect live payloads. Both payload processes require mlockall(MCL_CURRENT|MCL_FUTURE), disable core dumps and are non-dumpable; no global swap policy changes. Service cgroup no-swap limits are an additional protection where the kernel implements them. The qualified Pi boots with cgroup_disable=memory; the gateway exposes that its cgroup limit is not verified and uses actual process-local locks, not a false claim based on systemd declarations. Its two malloc arenas bound address-space reservation for locked allocation. Failed protected provisioning explicitly faults the new job before demand. Runtime socket and scratch are RAM-only. No payload files, MEMFS archives, crash dumps or raw logs.

Configuration, UUIDs and credentials may persist. Phase 4 sends synchronously verified canonical output through a separate bounded private handoff to the gateway's protected RAM owner. Decoder-worker/service restart retains prior runs; gateway restart/power loss destroys the volatile history. No payload checkpoint, durable archive, file/image assembly or optional-server package is installed. deliberatelyDisposedRecords is retained as a legacy diagnostic field name: it now counts failed record-handoff attempts, not successful retained delivery. Kernel sends do not establish ring admission or durability. recordHandoff publishes configured/connected state, exact sent/dropped byte/record totals, reconnects and same-identity bootstrap retry counts, resetting per decoder run.

Decoded-record retention and delivery

The default 128 MiB aggregate record pool is shared fairly across logical streams, with bounded protected indexes/bootstrap/send copies. Slow readers cannot pin history. Optional age expiry and actual per-epoch coverage are observable; there is no guaranteed fixed outage duration. History/status/subscriber reads never acquire a receiver. Job disable releases only its own capture demand and does not erase retained history.

RECORDS_DIR/RECORDS_SOCKET in appliance API configuration select the policy/ credential directory and private handoff; defaults are /etc/rfsentry/records.d and /run/rfsentry-api/records.sock. The single host-only config.json contains policy, revision and SHA-256 token definitions, not live records. API changes use revision plus file-digest CAS, atomic publication and last-valid protected state. Manual edits increment revision then use rfsentry-jobctl records-reload or systemctl reload rfsentry-api; they never retune RF. Failed allocation/locking/ peak provisioning leaves the previous valid policy/store in use.

sudo rfsentry-jobctl records-status
sudo rfsentry-jobctl --read-only records-capabilities
sudo rfsentry-jobctl records-configuration
sudo rfsentry-jobctl records-policy /private/record-policy.json
sudo rfsentry-jobctl records-credential /private/reader-definition.json
sudo rfsentry-jobctl records-revoke reader-id

Record credentials are separate, revocable records.read scopes by stable logical-stream UUID. They never grant job/tuning/diagnostic/IQ authority; existing status tokens cannot read records. Legacy anonymous control policy, if explicitly retained, is otherwise unchanged. Records always require authentication, including under anonymous legacy operation. Browser authentication uses the first bounded WebSocket message body, not URL secrets or unavailable custom headers; browser origins match exactly. Authenticated native clients may omit Origin only on this record endpoint. TLS verification remains mandatory for network use.

The API listener (8443 by default) exposes /ws/records with rfsentry-records-v1. The IQ-only listener/QoS (8444 by default) is unchanged. Reader cursors retain original producer/stream/run/u64 sequence plus owner epoch; explicit inclusive/after semantics and a replay fence prevent silent skips. Unavailable positions pause with a gap, never auto-convert to live. ACKs mean reader progress only, not Pi durability. Original supplemental configuration and boundary evidence precede dependent records without advancing the forward cursor.

rfsentry-record-client --credential-file /private/reader.json --stream UUID is the C++ reference reader. Run with an appropriate local memlock allowance; it preserves TLS verification and protects all received payload memory, printing only statistics (or explicit identity/hash evidence), never payloads. Full API/ framing examples and limits are in the repository's delivery contract. Browser source integration uses the record-source guide.

Rollback

Disable the job through API/CLI (or set enabled:false, increment revision and reload), verify demand released unless a browser legitimately remains attached, then stop/disable rfsentry-decoder.service. For a gateway rollback restore the pre-install binary/unit backup and restart only the gateway. Preserve job files and appliance identity; do not delete unrelated storage, receiver routes, TLS or QoS. Do not run a full installer as a live-safe deploy: it stops receiver demand.

Selected fixture/live qualification and measurement limits are in the verification index. They do not qualify every configuration/device or establish current installed job/service state.