Appliance and RF ingress¶
The appliance converts a stable operator request into a verified stream from a specific physical receiver. It is deliberately not a general SDR desktop.
Inventory, routes, and accessories¶
Receiver configuration is keyed by hardware serial under /etc/rtl_tcp/.
Route policy under /etc/rfsentry/routes.d/ references that serial and adds RF
range, tuner range, net translation, purpose, priority, power cost, and release
timing. Generic accessory definitions and USB-domain topology are separate so
an upconverter, LNA power path, or shared parent gate is not encoded as a
special-case receiver.
flowchart TB
RC[Receiver config<br/>serial, alias, ports] --> ROUTE[Route policy<br/>RF range and translation]
DOMAIN[USB domain topology] --> DEMAND[sdr-demandd]
ACC[Named accessories] --> DEMAND
ROUTE --> API[rfsentry-api inventory]
RC --> DEMAND
DEMAND --> PUBLIC[Stable public port]
PUBLIC --> API
An HF upconverter route can therefore present 7.074 MHz to the operator while tuning the receiver to 132.074 MHz. The mapping is explicit; the UI must not call the tuner frequency absolute RF.
The example profile illustrates this with two routes. fan-hf adds 125 MHz
for a Ham It Up in UP-CONVERT mode. vhf-direct tunes the requested RF
frequency directly. Verify the translation and usable range against your own
signal path before enabling automatic selection.
USB topology and power evidence¶
Domain files describe parent gates, managed user ports, reserved cascade ports, and receiver-capable discovery pools. Accessory files describe named dependencies referenced by receiver configuration. A cached serial/domain/port association accelerates discovery but never proves hardware identity.
Keep a hub's internal cascade port reserved. On a cold wake, the stable census
verifies receiver serials, repairs the cache, and prunes unrelated managed ports.
The controller first binds hub locations using a unique, identity-checked parent
hierarchy containing a configured receiver serial. Its separate operational
domain cache records the physical controller and policy fingerprint for cold
wake and bus renumbering; configuration and reserved cascade ports stay unchanged.
Ambiguous matches or relocation with an active receiver fail instead of probing
unidentified trees. Status distinguishes configured from effective hub locations.
Shutdown reverses the dependency order: stop a receiver's backend before disabling
its data port, then unlink child domains before parents once all receivers idle.
POWER_CONTROL=logical-only reports logical USB isolation, not removal of VBUS
from an externally powered hub or power-only accessory.
The public profiles/example directory is a synthetic Pi 5 template with a
3 → 3-1 → 3-1.1 USB hierarchy. Customize a private copy and verify actual
hardware before installation. Existing installations retain their configured
hardware policy; see identity and recovery profiles.
Demand-start lifecycle¶
sdr-demandd listens on each receiver’s configured frontend port. The gateway
connects to that port via loopback. Raw rtl_tcp clients on the LAN can also
reach the frontend where network policy permits. The serial-keyed
rtl_tcp@SERIAL.service backend listens on a separate, private loopback port.
On first connection the proxy:
- recursively enables required USB domains;
- performs a bounded cold census or warm cached-port probe;
- verifies the exact configured serial;
- enables named accessories and the receiver data port;
- starts the serial-keyed backend supervisor;
- connects to its private loopback
rtl_tcpport; and - forwards the original client without a manual retry.
After the last client closes, a receiver-specific idle timer allows quick
reconnection. The supervisor then closes rtl_tcp cleanly so librtlsdr can put
the tuner/ADC into standby before logical USB isolation. A separate deep-idle
timer unlinks parent domains only when all receivers are idle.
Backend instances remain disabled at boot; the demand manager starts them transiently. Each browser lane owns and independently releases one receiver lease after its route grace. Static page loads and authentication do not acquire leases or wake hardware. A fault, hot-unplug, or shutdown on one receiver must not disturb another active receiver.
Hot-unplug resilience¶
Restart=always cannot repair an rtl_tcp process that stayed alive while its
USB device disappeared. RF Sentry's supervisor watches the exact serial,
terminates a stale process, waits quietly for that serial to return, and uses
bounded crash-loop backoff. Absence logging is edge-triggered to avoid an
endless journal stream.
Gateway path¶
rfsentry-api serves HTTPS and WebSockets through libwebsockets. It loads inventory, routes,
spur masks, TLS/auth policy, and allowed sample rates. A lane session selects
an eligible route, obtains one receiver lease, establishes rtl_tcp, applies
tuner state, quarantines post-command IQ for the configured sample-domain
settling interval, and publishes framed IQ over TLS.
sequenceDiagram
participant UI as Browser lane
participant API as rfsentry-api
participant D as sdr-demandd
participant R as rtl_tcp@SERIAL
UI->>API: session.open(route, RF, rate, mode)
API->>D: connect stable public port
D->>D: wake topology and verify serial
D->>R: start transient backend
API->>D: send tuner settings
D->>R: forward tuner commands
API-->>UI: session.ready on control connection
R-->>D: CU8 samples on private port
D-->>API: forward samples over frontend connection
API->>API: discard settling samples
API-->>UI: framed samples on bound IQ connection
UI->>API: session.close
API-->>D: close demand connection
D->>R: clean stop after idle grace
The gateway does not use private backend ports directly and runs without USB device access or elevated capabilities.
Outbound IQ and Wi-Fi priority¶
The appliance's independent rfsentry-qos.service applies AF41 DSCP 34 before
outbound transmission. It matches the gateway UID, configured TCP source port,
and selected/discovered WLAN interfaces for IPv4 and IPv6, preserving ECN.
It matches only the dedicated STREAM_PORT (8444 by default). UI/API/control
and downloads stay on PORT (8443), outside the priority rules. Both external
TLS listeners share the same gateway process, certificate and receiver leases.
Each lane discovers its endpoint through control and binds its existing token;
the IQ listener rejects API/control access, and the API listener rejects IQ.
The unit owns only inet rfsentry_qos, leaves other firewall/NAT/routing policy
intact, and requires no gateway privileges or receiver restart. Its Linux
nftables/systemd implementation is independent of Pi model and memory size.
/etc/rfsentry/qos.conf controls enable, named profile, and interfaces; choices
survive upgrades. Driver/AP WMM mapping is separate from verified DSCP bits.
See the QoS guide for configuration,
live-safe install.sh --install --qos-only, verification, and rollback.
IQ geometry and continuity¶
The source is interleaved unsigned 8-bit complex IQ. Conversion to normalized floating-point complex samples happens in the browser. Quality windows use fixed 65,536-complex-sample spans, never WebSocket packet boundaries, and are discarded across a discontinuity.
Raw CU8 costs two bytes per complex sample before framing/TLS overhead: 2.4 MS/s is 4.8 MB/s or 38.4 Mbit/s per receiver; 3.2 MS/s is 6.4 MB/s or 51.2 Mbit/s. These are bandwidth examples, not a hardcoded supported-rate limit. Actual rate choices come from appliance policy, and high-throughput operation requires loss/continuity evidence on the active USB, network and browser path. Each simultaneous receiver adds its own stream cost.
Tuner/configuration operations advance the sample counter across quarantined samples and flag the first published block. The browser can therefore reset filters and decoder timing without inventing a continuous stream.
Power and recovery¶
The selected policy uses Chrony, capped persistent journals, and a status/banner path that performs no network fetches. Health/network recovery and PID 1's hardware watchdog are profile-configurable, not assertions about today's live enabled state. Do not add a competing watchdog daemon. These appliance concerns are outside the browser runtime; see installation and the repository appliance runbook for recovery procedures.
Clock discipline¶
Chrony is a client-only service, not a network-exposed time server. The selected
profile preserves /var/lib/chrony/chrony.drift, uses makestep 1 3 only during
the first three updates, and slews established corrections. Do not add allow
or a local-server directive, replace its drift model, or make appliance boot
wait for Internet time. The installer selects Chrony rather than the alternative
systemd-timesyncd provider.
Status and login/banner rendering use bounded queries to the local Chrony control socket; they do not initiate network requests or fetch datasets. Cached source timestamps must remain distinct from the cache's most recent fetch time.
Recovery ownership and power budget¶
Hardware-watchdog activation follows the selected profile and detected device; when enabled, systemd PID 1 is its sole owner. Never introduce a second watchdog daemon against that device. Keep active-client shutdown protection, bounded network-recovery/reboot budgets, and edge-triggered diagnostics.
Appliance-side background work should remain bounded and economical in CPU, resident RAM, polling, and wakeups. The Pi provides acquisition and local services; it must not become a second workstation DSP or rendering tier.