Skip to content

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:

  1. recursively enables required USB domains;
  2. performs a bounded cold census or warm cached-port probe;
  3. verifies the exact configured serial;
  4. enables named accessories and the receiver data port;
  5. starts the serial-keyed backend supervisor;
  6. connects to its private loopback rtl_tcp port; and
  7. 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.