Skip to content

Receiver lanes and tuning

A receiver lane is an independent browser DSP/control context. It can acquire one eligible route and run one manifested decoder while another lane uses a different receiver and decoder.

Frequency coordinates

Coordinate Meaning
Operator RF Real-world frequency requested by the operator
Route translation Fixed up/downconverter offset from route policy
Logical capture center RF Sentry's source capture center
Physical tuner/LO Hardware value after route and driver offset policy
VFO Desired signal inside the capture
Display center/span Independent view of retained spectrum history

For a direct route these can coincide. For the 125 MHz HF upconverter they do not. Driver-controlled offset tuning may also move the physical LO while preserving the selected VFO.

Start a lane

  1. Select the lane.
  2. Choose automatic routing or pin a verified route.
  3. Enter the operator RF frequency.
  4. Choose a capture rate that satisfies the intended decoder and receiver.
  5. Review gain/AGC and advanced correction controls.
  6. Start the receiver.

The route decision explains eligibility and translation. An unverified path is not eligible for automatic routing.

Route selection and policy

Serial, alias and public/backend port relationships come from /etc/rtl_tcp/<serial>.conf. /etc/rfsentry/routes.d/*.conf references that serial and a path-profile identifier; multiple routes may reference one receiver. USB indices, transient bus addresses and browser-hardcoded ports never identify the receiver. Use the installed inventory and routes to check which receivers can cover your frequency.

The current gateway parses these route fields:

Role Configuration keys
Identity and presentation ROUTE_ID, SERIAL, PATH_PROFILE_ID, LABEL
Eligible purpose PURPOSES
Operator RF and physical tuner limits RF_MIN_HZ, RF_MAX_HZ, TUNER_MIN_HZ, TUNER_MAX_HZ
Frequency conversion NET_TRANSLATION_HZ
Preference and lifecycle PRIORITY, POWER_COST, RELEASE_MS, HYSTERESIS_HZ
Admission ENABLED, VERIFIED

Incomplete definitions or RF-to-tuner mappings outside configured limits fail configuration validation. Automatic selection requires enabled, verified, purpose-compatible routes covering the request. A compatible current route has hysteresis preference; otherwise owned/waking receivers are excluded and priority/power ranking favors an already-awake, unowned receiver. Fault state reduces rank rather than guaranteeing the route is never retried. A pin gives an explicit route or eligibility error; acquisition still checks ownership. Current open/retune commands request the manual purpose. A scan purpose tag does not implement the deferred scan scheduler.

Allowed capture rates are appliance-wide configuration; the current route schema has no per-route sample-rate/bandwidth/mode constraints, arbitrary capability tags or maintenance state. Pins belong to operator requests, not route-file booleans. The roadmap retains those richer policy requirements; do not add unknown keys and expect the parser to ignore them. Antenna, converter and preselector context can be identified by the path/label and accessory definitions without claiming a general capability-matching engine.

Cross-receiver handoff

For a different physical receiver, the gateway reserves/configures the target while the old session assignment remains. It commits the target after a valid RTL-TCP header and upstream configuration (or successful awake-target reuse), then schedules the old receiver's route-specific release grace. That is not a first-usable-IQ verification: sample-domain quarantine and flagged IQ occur separately. The intended wait-for-usable-IQ/continuity handoff remains a stronger requirement; a setup acknowledgement alone does not prove it.

One owned session per physical receiver is enforced. If target acquisition is busy or fails, report the condition; the current path does not promise an automatic retry through every eligible route. Preserve the intended no-steal, safe-failure and explicit-discontinuity contracts without documenting them as a fully qualified failover service.

Capture rates

Capture rates come from the validated, ascending SAMPLE_RATES configuration, not a browser-only list. Rates above 2.4 MS/s are explicit higher-throughput choices: selecting one is not proof that the USB/network/browser path is loss-free. Preserve the operator's route, mode, VFO, bandwidth, and correction choices when changing workspace layout or reviewing decoded products.

Local tuning and passband controls

Display center/span is separate from the capture center. Wheel input over the upper spectrum pans the view, over the waterfall zooms span around the cursor, and over the left dB gutter tunes by the selected step. VFO follow, focused Arrow-key tuning and precision drag scrubbing through 100x are lane-local controls. Local navigation preserves the selected step and zoom; cross-band or outside-view jumps use deterministic fallback step/span defaults.

Panning within the capture changes only the display center. When the view crosses the hardware capture boundary, a serialized capture-center handoff is necessary. It keeps the VFO at its absolute RF frequency while the complete passband fits, then moves it only enough to remain capturable. An edge badge keeps an off-screen VFO discoverable. Independent display navigation therefore means no needless retunes, not that hardware can never retune at a boundary.

Mode, bandwidth and tuning pins remain authoritative. Automatic frequency profiles must not replace sticky manual choices. Passband lock and direct bandwidth/squelch entry coexist with edge dragging; an edit must not accidentally become a click-to-tune action. Edge drags retain pointer capture and show the appropriate resize cursor.

Filters carry explicit low/high cutoffs through lane state, worker configuration and the WASM FIR. USB/LSB expose only the outer passband edge for canvas dragging. Their carrier-side cutoff belongs in the active mode's options drawer and may extend to the carrier. The selector envelope stays carrier-aligned while the display separately shows the actual filtered passband and any suppressed near-carrier guard.

Detected-signal passband placement

An explicit assisted activation fits the published occupied envelope into the active demodulator's real passband:

Mode Tuning reference
USB Lower carrier-side edge
LSB Upper carrier-side edge
AM / WFM / NFM Symmetric center
CW Center of the actual symmetric pre-BFO filter

The detector's published lower/upper edges are authoritative. BW90/BW99 can inform analysis but must not replace or recenter this activation envelope. A small guard follows the matching fast/fine detector resolution. Frequency and bandwidth pins can constrain or block a proposed fit; selecting a signal alone does not authorize it. See Detection and Auto Start for activation, undo, manual takeover and decoder authority.

Implementation: src/ui/tuningModel.ts, src/ui/SpectrumCanvas.tsx, and src/detection/activation.ts under components/rfsentry-web/.

Gain and AGC

Manual tuner gain, tuner AGC, RTL/digital AGC, and software gain are different controls. RF Sentry reports requested state, command/driver confirmation where available, and measured IQ effects separately. A slider moving is not hardware readback; a brighter auto-scaled waterfall is not a calibrated gain test.

R82xx gains snap to the upstream supported table. E4000 capabilities come from the RTL-TCP header's tuner type and reported gain count. The gateway verifies that the reported count matches a known table before treating that table as authoritative. The wire/API representation retains tenths of a dB; the display converts those units once.

Fresh lanes request 28.0 dB manual tuner gain and normalize that request to the detected hardware's supported steps. This is not a claim that every tuner has a 28.0 dB setting. Browser audio AGC starts disabled and can be enabled explicitly per lane. Automatic tuner gain remains an operator option, but was observed to cause sustained raw-CU8 saturation on the HF/upconverter path; it must not silently replace the manual default or a saved operator choice.

When authorized assisted tuning optimizes gain, it uses fresh, complete fixed-window raw-IQ quality plus local signal evidence. It applies bounded hardware-table steps, preserves the owned route and capture center, quarantines the resulting settings transition, then remeasures before another step. Settings-only changes must not discard detector identity or clear spectrum history. Brightness, command acceptance and classifier confidence alone are not gain-quality measurements.

Driver offset tuning

Offset tuning is a separate hardware/driver setting, gated by the learned tuner capability. The supported zero-IF E4000/FC families and the unsupported low-IF R820T/R828D families follow librtlsdr's contract; this is not an E4000-only feature and not a reason to issue unsupported commands to every adapter.

The gateway reapplies supported offset tuning across acquisition, hardware retunes, and rate changes. Logical RF coordinates remain stable while the physical tuner LO and offset are reported separately. Preserve the setting and its evidence with raw IQ so replay restores capture-time context.

Classic RTL-TCP supplies no per-command result or hardware register readback. RF Sentry can report command transmission and measured IQ effects, but neither establishes a hardware readback. Do not use undocumented tuner-register writes as a substitute for the supported driver operation.

Tuner settling and sample continuity

The gateway quarantines post-command tuner transients in the sample domain before publishing IQ to audio, waterfall, detection or candidate analysis. IQ_SETTLE_MS in /etc/rfsentry/api.conf configures this policy; the code default is 100 ms. Retune/settings flags accompany the first published frame, and its sample counter advances across the discarded interval. The quarantine must not hide a gap by pretending discarded samples were received.

The earlier cold HF receiver/upconverter validation recorded a roughly 57 ms transient, motivating margin in that default. This is historical evidence for that path, not a universal timing guarantee for other hardware. Current source: components/rfsentry-api/src/config.c and src/receiver.c.

Raw-IQ warning windows are sample-based rather than packet-based; their quality/correction contract remains separate from demodulator or protocol validation.

Residual DC correction

Software residual IQ correction is lane-local, operates on processing samples, and leaves raw recordings unchanged. The estimator time constant controls how quickly a constant complex mean is removed. Because correction occurs before VFO translation, its zero-frequency target is the current capture center. It can also attenuate a real narrow signal at capture center. To investigate such a signal, compare reception with the correction enabled and disabled.

Reset/settle occurs on acquisition, hardware retune, sample-rate change, and discontinuity. Existing waterfall rows are history and do not change when the control is toggled.

Concurrent lanes

Independent physical receivers can run concurrently. Decoder workers, channelizers, queues, and status are lane-scoped. Two lanes cannot own one physical receiver simultaneously, and a decoder cannot start if its manifest geometry does not fit that lane.

The current browser exposes primary and secondary lanes with independent VFO, mute, volume and status. Their local DSP/decoder consumers share the owning lane's IQ fan-out. The gateway's consumer_count is currently a 0/1 ownership indicator, not a separate lease for every browser worker. Cooperative scanning must reuse that ownership boundary; it must not open another upstream connection for each local consumer. Its wider scheduling/refcount requirements remain planned.

Release

Stop the decoder if desired, then release the lane. This closes its demand connection. The appliance owns clean backend shutdown and power isolation; another active receiver is unaffected.

Normal session release schedules the route's RELEASE_MS grace before the gateway closes its public demand connection; an immediate release bypasses that grace. sdr-demandd then owns backend idle shutdown, standby and logical USB isolation, with its separate deep-idle deadline. Inventory reports runtime state, consumers, release deadline and fault separately from route policy. An unused lane must not retain acquisition just to keep a UI panel convenient.

Routing sources: components/rfsentry-api/src/config.c, routing.c, receiver.c and server.c; focused selector coverage is in components/rfsentry-api/test/test_routing.c. These are source references, not a new live handoff or power test.

Ledger and acceptance context

docs/roadmap/receiver-dsp-scanning.md records the Phase 1 navigation refinement accepted on 2026-08-31, including scoped wheel actions and capture-boundary handoff. The Phase 3 correction checkpoints and Phase 3B — Accepted Intelligent-Policy Work establish the passband references, settling/quality evidence, staged gain and operator authority described here. The 57 ms transient and 28.0 dB HF validation are dated path-specific evidence, not universal hardware facts.

Keep these accepted contracts separate from the still-open Phase 2 and acceleration qualification matrices. See the source-document map. This chapter reconciliation performs no new receiver test and closes no gate.