Skip to content

Phase 10C — 978 MHz UAT Implementation Ledger

Status: approved and in progress
Baseline: main at 4d71732a79abd4eca5a322324e06b2a42566826e
Started: 2026-09-28

This document is the living implementation and validation ledger for RF Sentry's first 978 MHz UAT tranche. It refines the Phase 10C roadmap in docs/WEBSDR.md; it does not replace that roadmap. Check an item only after the implementation exists and the stated validation has passed. Record live limitations honestly rather than treating fixture coverage as live RF acceptance.

Operator-visible target

The first useful milestone is an end-to-end local-first path:

978 MHz RF
  -> existing receiver/lane and exact-rational channelizer
  -> bounded UAT demodulator/FEC decoder worker
  -> UAT aircraft and ground-uplink observations
  -> shared AviationIntelligenceService
  -> Aviation workspace, FAA enrichment, map, and replay
  -> bounded FIS-B product history and initial text products

The operator must be able to tune the adsb1 receiver to 978 MHz, start UAT through the normal decoder workflow, see validated aircraft and ground-uplink activity, inspect UAT provenance in the existing Aviation workspace, and map position-bearing aircraft without creating a second aviation identity or map system.

Non-negotiable boundaries

  • The Pi remains the IQ relay and local metadata/artifact host. UAT DSP and decoding run in the browser worker/WASM architecture.
  • Reuse the existing decoder ABI, lane jobs, exact-rational channelizer, Aviation workspace, FAA enrichment, selection, map, IndexedDB history, and reference-time model.
  • Realtime acquisition, waterfall, audio, and DSP retain priority. Decoder and product workers are bounded and may drop/diagnose backlog rather than wedge a receiver session.
  • RF capture time is authoritative. Processing, arrival, insertion, and replay time must not rewrite observation chronology.
  • A direct, qualified UAT ICAO identity may correlate with the same aircraft seen on 1090ES. TIS-B, ADS-R, non-ICAO track files, vehicles, and fixed beacons retain source/address qualifiers and are never silently coerced into a direct aircraft ICAO identity.
  • FAA enrichment applies only to a qualified ICAO identity. FCC is not an aircraft registry.
  • FIS-B reception time, issue time, validity interval, and expiration are distinct. Replay shows only products RF Sentry had actually received and assembled by the selected reference time.
  • Normal operation requires no Internet service. Received RF products and locally hydrated metadata remain useful offline.
  • One RTL-SDR cannot simultaneously cover 978 and 1090 MHz. Concurrent dual- link reception requires separate receivers/lanes; RF Sentry must not hide a retune/time-sharing compromise.

Decoder/source decision record

  • Primary reference and algorithm source: FlightAware dump978-fa, pinned to an exact reviewed revision before import.
  • License boundary: its BSD-2-Clause UAT code is suitable for adaptation; bundled libfec carries a separate LGPL license and must be documented if imported or linked.
  • Implement the RF Sentry ABI adapter as a contained browser-WASM decoder. Full-rate synchronization, CPFSK discrimination, phase selection, and Reed- Solomon correction remain inside WASM. TypeScript receives corrected, bounded frames and constructs normalized aviation/product observations.
  • Use pinned corrected-message fixtures plus deterministic synthetic CPFSK IQ. Add a small local real-IQ fixture when captured; never commit private or unbounded operator captures.
  • Treat other implementations (including xng-mode-uat, Stratux, and independent decoders) as test oracles/research sources, not runtime network services.

Data architecture

Surveillance identity

Planned address-qualified keys:

  • aircraft:icao:<hex> — direct validated ICAO identity, shared across 1090 and UAT.
  • aircraft:uat:adsb-other:<address> — direct non-ICAO UAT ADS-B address.
  • aircraft:uat:tisb-track:<address>:<site> — site-scoped TIS-B track file.
  • Explicit vehicle/fixed-beacon identities where the qualifier requires them.

Canonical aircraft state is a capture-time projection over immutable protocol observations. Per-field source choice uses freshness, validity, direct versus rebroadcast provenance, and protocol quality; it does not erase the losing observation.

FIS-B products

Ground broadcast uses a separate bounded product substrate rather than being forced into the aircraft table:

  • ground station/site observation;
  • corrected uplink frame;
  • APDU/product fragment;
  • assembled product revision;
  • reception/provenance record.

IndexedDB retains structured product/history records. RAM holds compact current projections for UI/map consumers. Large raster payloads may move to OPFS only if measured NEXRAD storage/copy behavior justifies it.

Implementation checklist

10C.0 — Source qualification and reproducible fixtures

  • [x] Pin the exact upstream UAT algorithm/source revision.
  • [x] Record source, revision, hashes, licenses, and local modifications.
  • [x] Select/import the minimal demodulation and FEC boundary.
  • [x] Add deterministic corrected-message and synthetic-IQ fixtures.
  • [x] Prove Node-hosted artifact fixture decoding before browser integration.

Acceptance: source and licensing are reproducible; valid short/long downlinks and uplinks decode; corrupted frames are corrected within the supported budget or rejected rather than emitted as valid.

Validated 2026-09-28: the generated import-free WASM artifact decoded deterministic CPFSK short/long/uplink fixtures, corrected injected symbol errors, and rejected a short frame beyond its six-symbol correction budget.

10C.1 — Browser-WASM UAT PHY and frame decoder

  • [x] Add allowlisted uat978 build-matrix entry and notice.
  • [x] Accept exact 2,083,333 1/3 complex samples/s through the existing rational channelizer.
  • [x] Implement 978 CPFSK phase discrimination and 36-bit sync detection.
  • [x] Distinguish short/long aircraft frames and ground uplinks.
  • [x] Apply UAT Reed-Solomon correction and publish correction/validity facts.
  • [x] Preserve decoder-block capture/sample/receiver/path provenance.
  • [x] Keep queues, events, memory, and failure behavior bounded.
  • [x] Validate native fixture, WASM artifact, ABI, and channelizer invariance.

Acceptance: manual 978 tuning starts an isolated decoder and produces only FEC-validated, capture-time-normalized frame events without disrupting the receiver, waterfall, audio, or other lanes.

10C.2 — UAT aircraft observations and shared identity

  • [x] Parse UAT basic/long ADS-B aircraft reports.
  • [x] Decode qualified address, callsign, position, altitude, speed, track, vertical rate, emitter/category, mode/status, and available accuracy fields.
  • [x] Normalize direct UAT ADS-B, TIS-B, and ADS-R source/provenance distinctly.
  • [x] Generalize AircraftObservation beyond ADS-B/1090 CPR assumptions.
  • [x] Extend AviationIntelligenceService to ingest UAT without a parallel store or service.
  • [x] Correlate only explicitly ICAO-qualified identities across 1090 and UAT.
  • [x] Retain multi-protocol source summaries and protocol-specific detail.
  • [x] Apply existing FAA metadata only to qualified ICAO identities.
  • [x] Add out-of-order, duplicate/replay, and cross-protocol regressions.

Acceptance: the existing Aviation list/dossier shows UAT, TIS-B, and ADS-R observations with honest provenance; a genuinely shared ICAO aircraft has one identity and retains both protocol histories.

10C.3 — Map and reference-time integration

  • [x] Feed UAT position observations into the existing moving-aircraft map adapter, selection, trail, altitude, and receiver-relative geodesy paths.
  • [x] Preserve protocol/source provenance in aircraft details and map state.
  • [x] Ensure UAT and 1090 observations coexist under per-field freshness rules.
  • [x] Make map/workspace selection navigate the shared aircraft target.
  • [x] Validate live and historical trails at the common reference time.
  • [x] Prove future UAT observations do not leak backward during replay.

Acceptance: UAT aircraft use the existing symbols, trails, globe altitude, selection, investigation, and capture-time replay behavior.

10C.4 — Detection, recommendation, and activation

  • [x] Add a uat978 recommendation/activation target near 978 MHz.
  • [ ] Extend candidate evidence with UAT bandwidth, CPFSK/sync/frame evidence.
  • [x] Keep frequency/band-plan context a prior, never protocol proof.
  • [x] Reuse committed-analysis decoder activation and manual-VFO start paths.
  • [x] Preserve pins, undo, cancellation, and lane scoping.
  • [x] Make dual-receiver 1090/978 operation explicit in UI/diagnostics.

Acceptance: likely UAT activity can be surfaced and explicitly activated via the normal RF Sentry workflow; manual 978 decoding remains available when detection is disabled.

  • [x] Decode/identify ground uplink site/header and APDU framing.
  • [x] Persist bounded uplink/product reception history separately from aircraft state.
  • [ ] Assemble fragments by stable product/revision identity.
  • [ ] Expose station/site, product availability, current-report/service status, and raw corrected detail in an Aviation Broadcasts view.
  • [x] Preserve incomplete/invalid assembly diagnostics without presenting partial products as complete.
  • [x] Add capture-time and received/issued/valid/expires temporal contracts.

Acceptance: live or pinned uplinks populate a bounded ground-broadcast surface with source, time, validity, and assembly state; replay cannot see fragments or products not yet received.

10C.6 — Initial high-value textual FIS-B products

  • [x] Decode Product 413/general text transport.
  • [x] Present METAR/SPECI, TAF, PIREP, and winds/temperatures aloft first.
  • [ ] Add SIGMET/Convective SIGMET/AIRMET and useful NOTAM families as their framing/quality is proven.
  • [ ] Retain raw/product detail and parse diagnostics alongside normalized fields.
  • [ ] Add type/source/validity filters and bounded history.
  • [ ] Hydrate locally served station reference metadata where coordinates are required; do not add a runtime Internet weather dependency.

Acceptance: received text products are readable, filterable, provenance- backed, temporally honest, and remain available offline after reception.

10C.7 — Geographic advisory/map products

  • [ ] Define generic temporal point/polygon/raster aviation overlay contracts.
  • [ ] Map METAR stations and PIREPs when defensible coordinates exist.
  • [ ] Map SIGMET/AIRMET/Convective SIGMET geometry with issue/validity state.
  • [ ] Add independent, persisted layer toggles and decluttering.
  • [ ] Keep map overlays driven by common reference time.

Acceptance: product layers are independently controllable and show only information RF Sentry legitimately knew and that was valid at reference time.

10C.8 — NEXRAD/precipitation

  • [ ] Decode regional NEXRAD products before CONUS mosaics.
  • [ ] Retain product time/coverage/resolution/quality metadata.
  • [ ] Render bounded GPU-backed raster/vector tiles without React-per-cell work.
  • [ ] Measure RAM, IndexedDB, and OPFS behavior before selecting blob storage.
  • [ ] Preserve previous usable products across malformed/incomplete updates.

Acceptance: precipitation is an optional, time-correct, locally received map layer that does not materially disturb realtime SDR operation.

10C.9 — Deployment and live validation (location omitted)

The original site locality is omitted. Recorded outcomes below retain their original execution provenance; no substituted-location rerun is claimed.

  • [x] Build/install using the repository toolchain and appliance runbook.
  • [x] Tune adsb1 to 978 MHz and validate live aircraft frame counts.
  • [x] Validate one UAT aircraft end to end when local traffic permits.
  • [ ] Validate one ground uplink and initial FIS-B product when reception permits; otherwise record fixture-only coverage explicitly.
  • [ ] Run simultaneous 1090 + 978 on distinct receiver lanes.
  • [x] Verify waterfall/audio/DSP/IQ DVR remain healthy.
  • [ ] Verify replay, map, FAA enrichment, and workspace navigation.
  • [ ] Record live reception limitations, antenna/filter constraints, and deliberately deferred product families.

Acceptance: a deployed, usable 978 capability meets the operator-visible target above. Fixture validation never substitutes silently for unavailable local RF traffic.

Test matrix

  • Valid/correctable/uncorrectable short and long aircraft frames.
  • Valid/correctable/uncorrectable ground uplinks.
  • End-to-end receiver-format CU8 through the production rational channelizer, UAT WASM demodulator/FEC/framer, and typed aircraft/uplink interpreter.
  • Sync polarity/phase, chunk-boundary, discontinuity, and retune reset cases.
  • Exact-rational channelizer output across source chunk boundaries.
  • Direct ICAO cross-protocol merge and non-ICAO/TIS-B non-merge cases.
  • Capture-time out-of-order ingestion and replay idempotency.
  • Uplink fragment assembly, replacement, incompleteness, and expiration.
  • Product received/issue/validity/expiration distinctions.
  • Map visibility, trails, selection, and replay as-of behavior.
  • Decoder fault isolation and bounded backlog/drop diagnostics.

Known risks and decision points

  • Local 978/FIS-B reception depends on ground-station geometry and the installed 978/1090 antenna/filter path; lack of live frames is not by itself a decoder failure.
  • Uplink FEC and product assembly are more complex than aircraft downlinks; they require independent fixture/oracle comparison.
  • FIS-B product families have uneven complexity and operator value. Product parsers land incrementally behind the common substrate.
  • NEXRAD can dominate storage and rendering work. It must not delay the first useful surveillance/text-weather milestone.
  • If the audited upstream decoder boundary proves incompatible with the freestanding RF Sentry ABI, use a pinned Emscripten adapter rather than weakening isolation or moving decoding to the Pi.

Accepted outcome and remaining evidence

On 2026-09-28 the operator confirmed live UAT aircraft in the shared Aviation workspace and RF map. The earlier bounded observation produced zero valid UAT frames; it was not positive reception evidence. No received FIS-B weather product was observed in the acceptance checkpoint, so that separate gate remains open. Pinned upstream-derived and generated raw-IQ tests cover the rational channelizer, frame/FEC interpretation, Product 413 text, noise and corrupted-codeword rejection. Those fixtures are not a substitute for live ground-uplink/weather acceptance.