feat(sdr): local receivers — browser RTL-SDR, Local ADS-B layer and decoder feeds (#732)

Adds a Local ADS-B layer fed by your own receivers: a browser WebUSB
RTL-SDR (with FM listening) and local 1090/978 MHz decoder feeds
(LOCAL_RECEIVER_FEEDS, local and private addresses only). Local aircraft
draw in magenta with class, silhouettes, 3D models, trails and a position
sanity filter; the click card names the band and input that heard them.

Builds on Sameh Khamis's SDR prototype and the initial GEV port by
Mazeyar Moeini Feizabadi (#134); the decoder-feed design follows the
notes on #57. Closes #57.

Co-authored-by: Sameh Khamis <[email protected]>
Co-authored-by: Mazeyar Moeini Feizabadi <[email protected]>
This commit is contained in:
authored and GitHub committed 2026-09-23 16:00:53 -05:00
1 parent 143cffd7ca
commit 1fc795577a
78 files changed
+12267 -108

No files matched your search

+141
View File
@@ -0,0 +1,141 @@
import { localReceiverFeedName } from './feedNames.js';
import { LAYER_SOURCE } from './policy.js';
/**
* Layers-panel status for Local ADS-B, from its two inputs: the browser
* WebUSB receiver and the server's decoder feeds. Pure; no DOM or Cesium.
*/
export const FEED_SOURCE = 'Decoder feeds';
export const COMBINED_SOURCE = 'WebUSB + decoder feeds';
function plural(count, one, many) {
return count === 1 ? one : many;
}
/**
* Describe the feeds that are not live, grouped by status, e.g.
* "feed 978 unreachable" or "feeds 1090, 978 stale".
* @param {object[]} feeds Feed statuses from the route.
* @returns {string}
*/
export function describeFeedProblems(feeds) {
const byStatus = new Map();
for (const feed of feeds) {
if (feed?.status === 'live') continue;
const status = feed?.status || 'unreachable';
if (!byStatus.has(status)) byStatus.set(status, new Set());
byStatus.get(status).add(localReceiverFeedName(feed, feeds));
}
return [...byStatus]
.map(([status, names]) => {
const list = [...names];
return `${plural(list.length, 'feed', 'feeds')} ${list.join(', ')} ${status}`;
})
.join(' · ');
}
/** Whether the server reported at least one configured feed. */
export function feedsConfigured(feedState) {
return Boolean(
feedState?.configured === true &&
Array.isArray(feedState.feeds) &&
feedState.feeds.length,
);
}
function webUsbStatus(receiver, heard, feedState) {
if (receiver.status === 'error')
return { status: 'error', error: receiver.message };
if (receiver.status === 'connecting' || receiver.status === 'tuning')
return { loading: true, loadingLabel: 'opening receiver' };
if (
feedState?.polling &&
feedState.configured === null &&
!receiver.connected
)
return { loading: true, loadingLabel: 'checking decoder feeds' };
if (!receiver.webUsbSupported)
return {
status: 'idle',
statusMessage: 'WebUSB needs desktop Chrome or Edge',
};
if (!receiver.connected)
return { status: 'idle', statusMessage: 'connect a receiver in Radio' };
if (receiver.mode !== 'adsb')
return { status: 'idle', statusMessage: 'receiver is in FM mode' };
const rate = Number.isFinite(receiver.messagesPerSecond)
? `${receiver.messagesPerSecond} msg/s`
: 'listening';
return { status: 'streaming', loadingLabel: `${heard} heard · ${rate}` };
}
/**
* Status fields of `getStats()` for the Local ADS-B row.
*
* Without configured feeds this is exactly the WebUSB status. With feeds:
* "2 feeds live · 14 heard" when every feed is live. While any input is
* producing (the browser receiver streaming, or a feed live) the row stays
* nominal and names the other feeds as a trailing note, e.g. "3 heard · USB
* 5.8 msg/s · feed 1090 stale": a decoder stopped so the browser can take the
* dongle is not a fault. With nothing producing, every readable feed stale is
* STALE and anything else is an error.
* @param {object} options
* @param {object} options.receiver WebUSB receiver snapshot.
* @param {object|null} options.feedState Feed poller snapshot.
* @param {number} options.heard Merged aircraft heard in the last 60 s.
* @returns {object} status / statusMessage / loading / loadingLabel / error /
* stale / source.
*/
export function localAdsbStatus({ receiver, feedState, heard }) {
if (!feedsConfigured(feedState))
return {
source: LAYER_SOURCE,
...webUsbStatus(receiver, heard, feedState),
};
const usbActive = Boolean(receiver.connected && receiver.mode === 'adsb');
const source = usbActive ? COMBINED_SOURCE : FEED_SOURCE;
const live = feedState.feeds.filter((feed) => feed.status === 'live');
const problems = [describeFeedProblems(feedState.feeds)].filter(Boolean);
if (usbActive && receiver.status === 'error') problems.push('USB error');
const rate =
usbActive &&
receiver.status !== 'error' &&
Number.isFinite(receiver.messagesPerSecond)
? ` · USB ${receiver.messagesPerSecond} msg/s`
: '';
const heardText = `${heard} heard`;
if (!problems.length) {
return {
source,
status: 'streaming',
loadingLabel: `${live.length} ${plural(live.length, 'feed', 'feeds')} live · ${heardText}${rate}`,
};
}
const problemText = problems.join(' · ');
const usbProducing = usbActive && receiver.status !== 'error';
if (!live.length && !usbProducing) {
// Decoders that stopped but still serve their last aircraft.json are
// stale, not down: only an unreachable or unusable feed is an error.
const readable = feedState.feeds.filter(
(feed) => feed.status !== 'invalid',
);
if (readable.length && readable.every((feed) => feed.status === 'stale'))
return {
source,
status: 'stale',
stale: true,
statusMessage: `${problemText} · ${heardText}`,
};
return {
source,
status: 'error',
error: heard > 0 ? `${problemText} · ${heardText}` : problemText,
};
}
return {
source,
status: 'streaming',
loadingLabel: `${heardText}${rate} · ${problemText}`,
};
}