Detection and Auto Start¶
RF Sentry uses one staged suggestion workflow rather than a separate automatic decoder picker.
Detection establishes that a signal occupies spectrum. Candidate analysis describes plausible modulation families. A decoder's validated output is the protocol evidence. These stages are not interchangeable, and inspecting a detected signal is not permission to change receiver settings.
flowchart TB
F[Frequency/service hints] --> R[Ranked manifested candidates]
G[Lane sample geometry] --> R
D[Signal detector] --> R
C[Candidate classifier] --> R
R --> S[Preselected decoder]
S --> M[Manual Start]
S --> A{Auto Start?}
A -->|required measured evidence| START[Start]
A -->|strong exclusive prior| TRIAL[Bounded trial]
TRIAL --> VALID{Validated output?}
VALID -->|yes| HOLD[Confirmed hold]
VALID -->|no| COOL[Stop and cooldown]
Evidence contract¶
docs/adr/0003-detection-evidence.md and the WEBSDR roadmap require separate
observation, detection, characterization, classification and decoding stages.
The sequence below is the intended evidence contract, not a claim that every
audit or protocol-recognition feature is complete:
- Preserve RF/tuner center, sample rate/format, sample/UTC time, gain, AGC, FFT/window and translation context. Check clipping, missing/repeated samples, DC, I/Q imbalance and whole-band gain changes before stronger RF claims.
- Estimate frequency-local background and variation across time and frequency with quantiles/medians, median absolute deviation, candidate exclusion and CFAR-style thresholds. A persistent carrier must not disappear into the noise model; a strong signal must not manufacture or suppress unrelated detections. Candidate-exclusion and temporal-occupancy audits remain open.
- Seed occupancy at a high threshold and grow qualified lower-threshold cells into connected time/frequency envelopes. Keep short/medium/long evidence independent of paint cadence; use band-aware gaps and maximum widths as priors, not proof. Stabilize credible outer edges without losing intermittent outer energy or bridging unrelated narrow signals.
- Mature and coalesce compatible tentative parents before publication. Do not lock a width/nature fingerprint too early and split one FM/multicarrier emission. Hide tentative objects, rate-limit publication, preserve creation order, hold through fades and reuse compatible recurrence identities. Use service-aware burst confirmation; high SNR alone must not bypass evidence.
- Extract inexpensive evidence continuously. Deeper raw-IQ work belongs to confirmed, selected, recorded or explicitly requested candidates, not an indiscriminate full-passband analysis loop.
- Screen center/DC energy, I/Q mirrors, clipping, repeated blocks, FFT leakage, gain shifts, harmonic combs and receiver/path spurs. Retain artifact, noise, coherent-emission, modulation, protocol and service alternatives, including counterevidence and Unknown.
- Publish only the strongest defensible claim. Phase 2 stops at data-quality artifact, noise-like, anomalous energy or coherent/structured emission. Modulation needs independent candidate-IQ indicators; information-bearing claims need framing and variable-content evidence; protocol claims need actual decoder validation. Internal scores are not probabilities.
The wider taxonomy retains likely modulated technological signals, likely information-bearing signals and candidate intentionally encoded communication as later, independently justified classes, not extra Phase 2 outputs.
Signal detection control¶
Each lane has a Signal detection switch, default on unless an explicit saved choice disables it. The disabled presentation says Detection paused. Disabling clears selected detector/candidate state, removes detector overlays and stops a job targeting a detected signal; manual-VFO decoding and ordinary reception remain available. Re-enabling starts a fresh, visible warmup.
The WEBSDR control contract requires genuine detector-only work isolation: disable refinement/occupancy/publication and detector-triggered candidate jobs, release detector-only history, and leave spectrum, waterfall, audio, recording and manual tuning operational. Merely hiding the Signals rail is insufficient. Enabling the control without an active receiver must not wake hardware.
The UI and worker gates are present in src/ui/App.tsx and
src/dsp/analysis.worker.ts; this is not a claim that the full CPU/work
isolation matrix has been proved. Its open acceptance requirements are
recorded below.
Detected signals and parent identity¶
The fast detector uses frequency-local fast/slow noise models, a hidden tentative stage, configurable stability/confirmation, and fading hysteresis. Recent tracks and measurement snapshots are bounded. Compatible recurring emissions can relink to their prior identity; incompatible bandwidth classes at the same center remain separate tracks.
Band-aware parent grouping prevents one emission's spectral lobes from becoming several visible signals. Narrow grouping is resolution- and scale-aware: unqualified blank bins and broad band-plan gaps must not bridge unrelated narrow components. A broad prior can retain a multi-lobed broadcast-FM parent, but an intermittent narrow neighbor must not widen a persistent track. A grouping prior does not validate WFM or any other protocol.
The Signals rail preserves detector creation order and pinned selection. Power and noise measurements are dBFS, not calibrated dBm. Selecting a row opens its evidence without silently changing mode, passband or VFO.
Published boundaries¶
Each track has a persistent absolute-RF evidence grid. Overlapping observation windows contribute only their genuinely new fractions. Sequential occupied evidence acquires edge cells; stronger sustained-vacancy evidence releases established cells. The sufficient statistics survive fine-window recentering and intermittent ownership changes instead of making every window a new track.
The fast detector owns existence, confirmation and parent identity. Bounded fine-FFT temporal median, upper-quartile and duty evidence can refine a confirmed parent's published edges, but cannot create or confirm a signal. Refinement remains tied to the fast core, obeys receiver/path masks and maximum-width priors, bridges only qualified small gaps, limits asymmetric growth, and feeds the persistent boundary evidence.
Use the published lower/upper edges for live boxes and assisted activation; neither a moving power peak nor BW90/BW99 substitutes for those bounds. Edge sensitivity remains selectable, while internal-boundary diagnostics default off. Live and historical waterfall outlines are described in Browser DSP and workers.
Receiver/path exclusions¶
/etc/rfsentry/spurs.d/*.conf supplies detector exclusions. The gateway
validates and inventories the masks, and the browser matches their receiver,
path and RF ranges. This is not a Pi-side detector service. Preserve that
provenance: a receiver-specific artifact must not suppress unrelated lanes.
Candidate analysis and uncertainty¶
An isolated browser worker receives complete IQ blocks through the ingress
worker's shared-ring or credited-transfer sink. It analyzes the selected
live/fading parent or one lane-local VFO probe used by the recommender;
operator selection takes precedence. Eco/Balanced/Analysis analysis intervals
are 1,000/250/100 ms, defined in src/dsp/performance.ts. A slow or failed
candidate worker cannot block audio, display FFTs or scientific detection.
Each arriving decimated sample is filtered once. Channel geometry changes only after a sustained, substantial challenge, rather than being rebuilt for every small bounds fluctuation. Completed features and votes survive compatible bounds jitter, fades, IQ refills and ended-compatible recurrence. Gaps reset sample continuity: retained evidence may survive, but samples must not be concatenated across a gap. Mixer-center jitter is not signal motion.
Candidate analysis is passive. Ranked modulation hypotheses, band-plan priors, Unknown and artifact are legitimate outputs; numeric scores are not calibrated probabilities. Unknown expresses uncertainty rather than competing as another class vote. Initial classification uses recent independent IQ for responsiveness. An established family survives inconclusive windows and requires sustained sequential contrary evidence before replacement. Overlapping feature windows are discounted rather than counted as independent observations.
Holding/challenged presentation has its own dwell gate: brief inconclusive windows, fades, refills and young challengers should not flicker the committed label. This visual stability does not weaken the stricter reclassification decision.
Feature inventory and limitations¶
The original requested feature inventory is broader than today's exposed
metrics. src/detection/types.ts defines TrackedSignal, acquisition, quality
and artifact evidence; src/analysis/types.ts defines the candidate summaries.
Do not present a requested feature as measured just because it is useful.
| Requested evidence | Current exposure / retained requirement |
|---|---|
| Observed center, carrier estimate and frequency error | Track RF/tuner center/bounds; candidate frequency offset/spread and carrier coherence. A spectral midpoint is not a proven carrier. |
| Occupied width, BW90/BW99 | Track occupied envelope and both energy-width estimates; candidate measured BW90. Published bounds remain the activation envelope. |
| Peak/average power, local noise and SNR | Track dBFS power/noise and peak/integrated SNR; no calibrated dBm. |
| Peak-to-average ratio and crest factor | Not exposed as general track/candidate metrics; remain requested. |
| Duty, first/last seen and total observed duration | Track duty, persistence, age, last-seen and confirmation time; age is not integrated on-air duration. |
| Burst interval/repetition, fading and stability | Candidate periodicity/lag and track duty/lifecycle provide evidence; a general burst schedule and fading metric remain requested. |
| Drift and spectral symmetry | Track drift/symmetry plus candidate positive-spectrum fraction; not sufficient to resolve a suppressed carrier. |
| Sideband balance and carrier prominence | Related fraction/coherence/concentration evidence exists; retain the request without treating those proxies as equivalent measurements. |
| Envelope variance and higher moments | Candidate amplitude variation, modulation depth and spectral kurtosis are exposed. |
| Spectral flatness and entropy | Candidate flatness is exposed; entropy is not a general summary field. |
| Tone count/spacing and symbol rate | Candidate tone count exists; general tone-spacing and verified symbol-rate estimates remain requested. |
| Cyclostationary features, especially in Analysis mode | Candidate cyclic coherence/rate indicators exist; a cyclic rate is not automatically a symbol rate or protocol identity. |
| Receiver/antenna, RF center, sample rate, gain and PPM | Receiver/path identifiers and acquisition context preserve source settings; alias/antenna context comes from inventory/path metadata. |
The deterministic candidate analyzer ranks broad AM/FM/SSB/CW/digital families, not every protocol named in the wishlist. It deliberately keeps SSB (sideband unresolved): energy on one side of an arbitrary midpoint does not prove USB/LSB. Service context may rank a mode only after measured evidence; carrier-edge fitting and pins still govern an authorized activation.
The wider classification contract retains editable regional and known-channel priors, multiple independent modulation indicators, framing/variable-content checks, recognition of identifiers such as fldigi RSID, and bounded comparison of plausible demodulators. Current source has no general RSID recognizer or automatic decode sweep across all those protocols. Retain these as requirements, not implemented capabilities or permission to guess.
For an ambiguous SSB signal, the wider requirement is to estimate a plausible carrier edge, consider band context and compare both sidebands/audio when appropriate. Current sideband-neutral features alone cannot fulfill that test.
Recommendation states¶
- Frequency prior — immediately useful but unconfirmed.
- Signal-supported — detector/classifier evidence fits the candidate.
- Decoder-confirmed — the module produced protocol-valid output.
- Manual — explicit operator selection; automatic ranking will not fight it until retune or return to automatic behavior.
- Auto-started trial — bounded attempt awaiting decoder validation.
The UI explains the high-level reason and compatibility. Internal scores are not displayed as probability. Unknown is an uncertainty state, not a protocol.
Fast service priors¶
Known exclusive channels such as 978 MHz UAT, 1090 MHz ADS-B, 14.074 MHz USB FT8, and applicable NRSC-5 allocations can select a likely decoder immediately. Auto Start may try the module after a short bounded wait instead of demanding that a general spectral classifier rediscover the protocol's entire standards committee.
The decoder then becomes evidence: valid frames/messages retain it; no useful output expires the trial. Settle, validation windows, retry cooldown, and switch hysteresis prevent thrashing.
Compatibility preflight¶
Preflight evaluates the manifest's input domain, exact accepted rates, bandwidth, tuning/channel policy, UTC uncertainty, continuity, route and receiver constraints. A blocked start gives a lane-local reason, for example:
1090ES / Mode S requires 2.4 MS/s IQ, but this lane is currently using 1.024 MS/s.
No ADS-B-specific conditional is needed; every new decoder participates by declaring truthful metadata.
Operator authority¶
- Manual selection overrides the suggestion.
- Operator-started/pinned jobs are not silently switched.
- Retuning releases manual stickiness unless explicitly retained by the UI.
- Auto Start is persisted per lane and defaults off.
- One lane's automation cannot stop or reconfigure another lane.
Explicit assisted activation¶
Selecting a signal and activating it are separate actions. Assisted activation is lane-scoped, cancellable and undoable, with explicit Auto/Manual authority, per-setting pins, an explained change list and stale-track rejection. Only authorized, unpinned settings may change; manual takeover wins. Fine tracking is bounded and browser-local, not a second hardware acquisition path.
Single-click inspection remains passive. Waterfall double-click and the selected inspector's tune action use one normalized activation entry rather than separate policies. Unknown or conflicting evidence keeps the current mode instead of guessing a replacement. The request/plan preserves lane, parent identity, acquisition context, evidence, proposed/applied changes and the pre-change undo snapshot.
The occupied envelope must fit the mode's real passband. USB/LSB carrier-edge placement, CW's pre-BFO filter, and symmetric modes have distinct geometry; see receiver tuning. Gain adjustment requires fresh complete raw-IQ quality and remeasurement, not simply a darker waterfall or an uncertain classifier score.
A ranked manifested decoder can be preselected without running it. Explicit Start remains the default. The persisted, default-off Auto Start preference may launch or switch after the manifest's evidence threshold, or use a bounded customary-frequency trial when the manifest permits it. An explicit intelligent activation can also request a matching allowlisted decoder. Holds, validation timeouts, retry cooldown and switch hysteresis prevent thrashing. Manual selection, operator-started/pinned jobs and validated protocol holds retain authority. A trial expires and cools down unless the decoder supplies validated output; a prior or classifier label never becomes a protocol claim.
The original FT8 example is now an evidence/timing-gated, allowlisted protocol attempt, not unconditional launch whenever a spectrum looks FT-like. A successful decode can provide callsigns and Maidenhead locators to shared station intelligence and the map; tuning to a customary frequency cannot. Current activation plans record target/filter/step, gain and browser AGC, squelch, audio/de-emphasis and bounded following where supported. The wider wishlist also includes notch/noise-blanker and other mode-specific refinements; do not imply every planned setting is implemented.
Reading a conservative assessment¶
For example, a hypothetical, not captured, assessment might read:
Observed: persistent 184 kHz occupied envelope · 31 dB peak SNR
Classification: coherent or structured emission
Artifact likelihood: low · stable away from DC · no mirror detected
Modulation evidence: not yet established
Alternative explanation: band-limited interference
Recommended next analysis: candidate IQ autocorrelation and FM hypothesis
Observation, artifact, modulation, framing and decoder evidence stay separate. Manual mode selection, per-setting adjustments and undo remain authoritative.
Learned classification — planned¶
Phase 8 remains open. Today's candidate classifier is deterministic; there is no deployed ONNX model or general learned protocol recognizer in this path. The roadmap preserves this training/inference design:
- Capture user-confirmed SigMF clips from the actual receivers and antennas.
- Label modulation, protocol, bandwidth, SNR, receiver and antenna.
- Augment with fading, frequency/sample-rate error, AGC action, clipping, I/Q imbalance and RTL-SDR spurs.
- Train a small coarse model for analog voice, digital multitone, constant-envelope digital, CW, impulsive telemetry and noise first.
- Retain Unknown/out-of-distribution and calibrate confidence; raw softmax values must not become displayed probabilities.
- Export to ONNX and run candidate-only browser WASM inference, with optional WebGPU acceleration; never analyze the whole raw passband continuously.
- Compare against the deterministic baseline before authorizing tuning or scan actions; fine protocol classifiers follow only after broad reliability.
ONNX Runtime Web and over-the-air modulation research are research references, not declarations of installed runtime dependencies or licensed model weights. Any concrete model/import still needs provenance, compatibility and independent qualification.
Implementation references¶
Paths below are relative to components/rfsentry-web/:
| Concern | Source |
|---|---|
| Signal identity, noise models and boundary evidence | src/detection/SignalDetector.ts, src/detection/emissionPrior.ts |
| Candidate processing, independent votes and stability | src/analysis/CandidateAnalyzer.ts, src/analysis/candidate.worker.ts |
| Activation, pins, passband fitting and gain policy | src/detection/activation.ts, src/detection/activationPolicy.ts |
Scheduling and worker ownership belong to the DSP chapter. Decoder-specific input, validation and protocol limitations belong to the decoder catalog.
Ledger and remaining proof¶
Source: docs/roadmap/receiver-dsp-scanning.md, especially Intelligent Signal Pipeline,
Phase 2 Correction Acceptance Contract, Deferred Phase 2 Closeout Backlog,
Phase 3A — Accepted Groundwork and
Phase 3B — Accepted Intelligent-Policy Work.
Phase 3A and 3B record accepted candidate analysis and explicit activation slices, including evidence stability, passband fitting, staged gain, pins, cancel/manual takeover and undo. They do not complete the deferred Phase 2 proof work. Remaining ledger items include candidate-exclusion and temporal-occupancy audits, activation/detector-off isolation regressions, all IQ-quality flags end to end, long real noise/artifact captures, false alarms per MHz-hour, bandwidth/parent/identity errors, and live airband/weak-signal checks. Synthetic regressions alone do not establish those field metrics.
The ledger's Intelligent Activation Cannot Converge contract additionally
requires reverting a worsening gain/refinement stage, safe cancellation on
target/ownership loss, and decoder failure remaining separate from receiver
health. These remain policy and proof obligations, not permission to force a
mode or decoder merely to finish the workflow. See the
source-document map
for how requirements, current code and acceptance evidence are reconciled.