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:
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.