import test from 'node:test'; import assert from 'node:assert/strict'; import { readFileSync } from 'node:fs'; import { classifyAircraft } from '../data/aircraftClass.js'; import { recordFromDecoderTrack } from '../sources/adsbRecords.js'; import { AdsbStreamDecoder, LOCAL_ADSB_STALE_MS, decodeAdsbMessage, extractAdsbMessages, modeSChecksum, pruneAircraftTracks, updateAircraftTrack, } from './adsbDecoder.js'; function fromHex(value) { return Uint8Array.from(value.match(/../g), (pair) => Number.parseInt(pair, 16), ); } function synthesizeIq( bytes, { floor = 128, high = 255, preambleTail = null } = {}, ) { const sampleCount = 16 + 112 * 2 + 8; const iq = new Uint8Array(sampleCount * 2).fill(128); for (let sample = 0; sample < sampleCount; sample += 1) iq[sample * 2] = floor; const pulse = (sample) => { iq[sample * 2] = high; }; for (const offset of [0, 2, 7, 9]) pulse(offset); if (Number.isFinite(preambleTail)) { for (let sample = 10; sample < 16; sample += 1) iq[sample * 2] = preambleTail; } for (let index = 0; index < 112; index += 1) { const value = (bytes[index >> 3] >> (7 - (index & 7))) & 1; pulse(16 + index * 2 + (value ? 0 : 1)); } return iq.buffer; } test('decodes standard callsign, velocity, and altitude examples', () => { const callsign = decodeAdsbMessage(fromHex('8D4840D6202CC371C32CE0576098')); assert.equal(callsign.callsign, 'KLM1023'); assert.equal(callsign.icao, '4840D6'); const velocity = decodeAdsbMessage(fromHex('8D485020994409940838175B284F')); assert.ok(Math.abs(velocity.speedKt - 159.2) < 0.1); assert.ok(Math.abs(velocity.headingDeg - 182.88) < 0.1); assert.equal(velocity.verticalRateFpm, -832); const position = decodeAdsbMessage(fromHex('8D40621D58C382D690C8AC2863A7')); assert.equal(position.altitudeFt, 38_000); assert.equal(position.cpr.odd, false); }); test('globally decodes a valid even/odd CPR pair and expires tracks at 60 seconds', () => { const tracks = new Map(); const even = decodeAdsbMessage(fromHex('8D40621D58C382D690C8AC2863A7'), { receivedAt: 1_000, }); const odd = decodeAdsbMessage(fromHex('8D40621D58C386435CC412692AD6'), { receivedAt: 1_500, }); updateAircraftTrack(tracks, even); const aircraft = updateAircraftTrack(tracks, odd); assert.ok(Math.abs(aircraft.latitude - 52.26578) < 0.0001); assert.ok(Math.abs(aircraft.longitude - 3.93891) < 0.0001); assert.equal(aircraft.lastPositionAt, 1_500); assert.equal(LOCAL_ADSB_STALE_MS, 60_000); assert.equal( pruneAircraftTracks(tracks, 61_499), 0, 'contact survives below 60 seconds', ); assert.equal( pruneAircraftTracks(tracks, 61_500), 1, 'contact expires at 60 seconds', ); assert.equal(tracks.size, 0); }); test('extracts a CRC-valid Mode S frame from synthetic 2 Msps IQ', () => { const bytes = fromHex('8D4840D6202CC371C32CE0576098'); assert.equal(modeSChecksum(bytes), 0); const frames = extractAdsbMessages(synthesizeIq(bytes), 2_000_000); assert.equal(frames.length, 1); assert.deepEqual(frames[0], bytes); }); test('accepts a valid weak frame above an elevated local noise floor', () => { const bytes = fromHex('8D4840D6202CC371C32CE0576098'); const frames = extractAdsbMessages( synthesizeIq(bytes, { floor: 140, high: 150 }), 2_000_000, ); assert.equal(frames.length, 1); assert.deepEqual(frames[0], bytes); }); test('accepts a real-shaped preamble with energy trailing its final pulse', () => { const bytes = fromHex('8D4840D6202CC371C32CE0576098'); const frames = extractAdsbMessages( synthesizeIq(bytes, { floor: 138, high: 148, preambleTail: 145, }), 2_000_000, ); assert.equal(frames.length, 1); assert.deepEqual(frames[0], bytes); }); test('preserves a Mode S frame split across consecutive USB blocks', () => { const bytes = fromHex('8D4840D6202CC371C32CE0576098'); const iq = new Uint8Array(synthesizeIq(bytes)); const decoder = new AdsbStreamDecoder(); assert.deepEqual(decoder.extract(iq.slice(0, 300).buffer, 2_000_000), []); assert.deepEqual(decoder.extract(iq.slice(300).buffer, 2_000_000), [bytes]); decoder.reset(); assert.deepEqual(decoder.extract(iq.slice(300).buffer, 2_000_000), []); }); test('rejects corrupt frames and unsupported sample rates', () => { const bytes = fromHex('8D4840D6202CC371C32CE0576098'); bytes[5] ^= 0x01; assert.notEqual(modeSChecksum(bytes), 0); assert.equal(decodeAdsbMessage(bytes), null); assert.deepEqual(extractAdsbMessages(synthesizeIq(bytes), 1_024_000), []); }); const AUSTIN_RECEIVER = Object.freeze({ latitude: 30.27, longitude: -97.8 }); const fixtureFrames = readFileSync( new URL('../data/fixtures/adsb-austin-frames.txt', import.meta.url), 'utf8', ) .split('\n') .map((line) => line.trim()) .filter(Boolean) .map((line) => fromHex(line.replace(/^\*|;$/g, ''))); const dump1090 = JSON.parse( readFileSync( new URL( '../data/fixtures/adsb-austin-dump1090-aircraft.json', import.meta.url, ), 'utf8', ), ); // The capture keeps receive order but not receive times, so frames are spaced // 100 ms apart: every even/odd pair then falls inside the 10 s CPR window. function decodeFixture(receiverLocation) { const tracks = new Map(); fixtureFrames.forEach((bytes, index) => { const message = decodeAdsbMessage(bytes, { receivedAt: (index + 1) * 100 }); if (message) updateAircraftTrack(tracks, message, receiverLocation); }); return tracks; } test('real Austin frames decode to the same aircraft, callsigns and positions as dump1090', () => { assert.equal(fixtureFrames.length, 112); const tracks = decodeFixture(AUSTIN_RECEIVER); const heard = [...tracks.keys()].map((icao) => icao.toLowerCase()).sort(); assert.deepEqual(heard, dump1090.aircraft.map((entry) => entry.hex).sort()); for (const oracle of dump1090.aircraft) { const track = tracks.get(oracle.hex.toUpperCase()); if (oracle.flight) assert.equal(track.callsign, oracle.flight.trim(), oracle.hex); if (Number.isFinite(oracle.alt_baro)) assert.equal(track.altitudeFt, oracle.alt_baro, oracle.hex); if (Number.isFinite(oracle.gs)) assert.ok(Math.abs(track.speedKt - oracle.gs) < 0.5, oracle.hex); if (Number.isFinite(oracle.track)) assert.ok(Math.abs(track.headingDeg - oracle.track) < 0.5, oracle.hex); if (Number.isFinite(oracle.baro_rate)) assert.equal(track.verticalRateFpm, oracle.baro_rate, oracle.hex); if (!Number.isFinite(oracle.lat)) continue; assert.ok( Math.abs(track.latitude - oracle.lat) < 0.01, `${oracle.hex} latitude`, ); assert.ok( Math.abs(track.longitude - oracle.lon) < 0.01, `${oracle.hex} longitude`, ); } }); test('receiver-relative CPR positions an even-only aircraft that dump1090 left unpositioned', () => { // SKW3301 (a15c54) sent three airborne positions, all even-parity, so no // global even/odd pair exists. dump1090 ran without a receiver location and // could not position it; with one, the local decode places it near AUS. const skywest = fixtureFrames.filter( (bytes) => decodeAdsbMessage(bytes)?.icao === 'A15C54' && decodeAdsbMessage(bytes).cpr, ); assert.equal(skywest.length, 3); assert.ok( skywest.every((bytes) => decodeAdsbMessage(bytes).cpr.odd === false), ); const located = decodeFixture(AUSTIN_RECEIVER).get('A15C54'); assert.ok(Math.abs(located.latitude - 30.1599) < 0.01); assert.ok(Math.abs(located.longitude + 97.7903) < 0.01); const unlocated = decodeFixture(null); assert.equal(unlocated.get('A15C54').latitude, null); const positioned = [...unlocated.values()] .filter((track) => Number.isFinite(track.latitude)) .map((track) => track.icao.toLowerCase()) .sort(); assert.deepEqual( positioned, dump1090.aircraft .filter((entry) => Number.isFinite(entry.lat)) .map((entry) => entry.hex) .sort(), 'without a receiver location the positioned set matches dump1090 exactly', ); }); // A second real capture over Austin with receive times: 846 extended // squitters from six aircraft, each frame timed by interpolating between the // frames whose decoded position matches a dump1090 fix (dump1090's `t - // seen_pos`), plus dump1090's own positions for the same interval. const timed = JSON.parse( readFileSync( new URL('../data/fixtures/adsb-austin-capture-timed.json', import.meta.url), 'utf8', ), ); function nauticalMiles(a, b) { const toRad = Math.PI / 180; const dLat = (b.lat - a.lat) * toRad; const dLon = (b.lon - a.lon) * toRad; const h = Math.sin(dLat / 2) ** 2 + Math.cos(a.lat * toRad) * Math.cos(b.lat * toRad) * Math.sin(dLon / 2) ** 2; return 2 * 3440.065 * Math.asin(Math.sqrt(h)); } function replayTimed({ inject = null, receiver = timed.receiver } = {}) { const tracks = new Map(); const stats = {}; const accepted = new Map(); for (const [receivedAt, hex] of timed.frames) { const message = decodeAdsbMessage(fromHex(hex), { receivedAt }); if (!message) continue; for (const extra of inject?.(message) || []) { updateAircraftTrack(tracks, extra, receiver, stats); } const track = updateAircraftTrack(tracks, message, receiver, stats); if (message.cpr && track.lastPositionAt === receivedAt) { const key = message.icao.toLowerCase(); if (!accepted.has(key)) accepted.set(key, []); accepted.get(key).push({ at: receivedAt, lat: track.latitude, lon: track.longitude, }); } } return { tracks, stats, accepted }; } function dump1090Final(hex) { const [, lat, lon] = timed.dump1090[hex].fixes.at(-1); return { lat, lon }; } test('identification messages decode to the dump1090 emitter category strings', () => { const { tracks } = replayTimed(); const decoded = Object.fromEntries( Object.keys(timed.dump1090).map((hex) => [ hex, tracks.get(hex.toUpperCase()).category, ]), ); assert.deepEqual(decoded, { '0d0c07': 'A2', a3627d: 'A3', a0b702: 'A7', a5b3a7: 'A3', abe7c5: 'A3', a27e81: 'A1', }); for (const [hex, oracle] of Object.entries(timed.dump1090)) assert.equal(decoded[hex], oracle.category, hex); // Category set D (type code 1) and C (type code 2) follow the same rule. const message = decodeAdsbMessage(fromHex('8D4840D6202CC371C32CE0576098')); assert.equal(message.typeCode, 4); assert.equal(message.category, 'A0'); }); test('145TX, a rotorcraft (A7), classifies as a helicopter', () => { const { tracks } = replayTimed(); const heli = tracks.get('A0B702'); assert.equal(heli.callsign, '145TX'); assert.equal(classifyAircraft({ category: heli.category }), 'helicopter'); assert.equal( classifyAircraft({ category: tracks.get('A27E81').category }), 'light', ); }); test('the speed check refuses none of the capture and every track ends on dump1090', () => { const { tracks, stats, accepted } = replayTimed(); assert.equal(stats.positionsRejected || 0, 0); for (const hex of Object.keys(timed.dump1090)) { const track = tracks.get(hex.toUpperCase()); assert.equal(track.rejectedPositions, 0, `${hex} rejected a fix`); const fixes = accepted.get(hex); assert.ok(fixes.length >= 20, `${hex}: ${fixes.length} fixes`); const delta = nauticalMiles(fixes.at(-1), dump1090Final(hex)); assert.ok(delta < 0.3, `${hex} ends ${delta.toFixed(3)} nm from dump1090`); } }); test("N26VB's 1.0 nm step spans a 27 s reception gap at its reported speed", () => { // The field report read this as a bad decode. The step follows single odd // frames decoded against the receiver location, which dump1090 (run without // one) never positions; the implied speed matches the reported 134 kt. const { tracks, accepted } = replayTimed(); const fixes = accepted.get('a27e81'); let widest = null; for (let index = 1; index < fixes.length; index += 1) { const step = nauticalMiles(fixes[index - 1], fixes[index]); if (!widest || step > widest.step) widest = { step, seconds: (fixes[index].at - fixes[index - 1].at) / 1000, }; } assert.ok(Math.abs(widest.step - 1.0) < 0.05, `${widest.step} nm`); assert.ok(widest.seconds > 25, `${widest.seconds} s`); const impliedKt = widest.step / (widest.seconds / 3600); assert.ok(Math.abs(impliedKt - 134) < 10, `${impliedKt.toFixed(0)} kt`); assert.equal(tracks.get('A27E81').rejectedPositions, 0); }); test('a corrupt even/odd pair is refused and the track stays on dump1090', () => { // Pair a foreign odd frame (ENY3344, 27 nm away) with N26VB's fresh even // frame: the global decode lands far off the track, as a mixed-up pair does. const foreign = timed.frames .map(([, hex]) => decodeAdsbMessage(fromHex(hex))) .find((message) => message?.icao === 'A3627D' && message.cpr?.odd); let injected = 0; const { tracks, stats, accepted } = replayTimed({ inject(message) { if (message.icao !== 'A27E81' || message.cpr?.odd !== false) return []; if (injected >= 2) return []; injected += 1; return [ { ...foreign, icao: 'A27E81', receivedAt: message.receivedAt - 1, cpr: { ...foreign.cpr, receivedAt: message.receivedAt - 1 }, }, ]; }, }); const track = tracks.get('A27E81'); assert.ok(track.rejectedPositions >= 1); assert.equal(stats.positionsRejected, track.rejectedPositions); for (const fix of accepted.get('a27e81')) assert.ok( nauticalMiles(fix, { lat: 30.32, lon: -97.91 }) < 3, 'no accepted fix leaves the track', ); assert.ok( nauticalMiles(accepted.get('a27e81').at(-1), dump1090Final('a27e81')) < 0.3, ); }); test('a lone frame decodes relative to the aircraft own recent position', () => { const tracks = new Map(); const even = decodeAdsbMessage(fromHex('8D40621D58C382D690C8AC2863A7'), { receivedAt: 1_000, }); const odd = decodeAdsbMessage(fromHex('8D40621D58C386435CC412692AD6'), { receivedAt: 1_500, }); updateAircraftTrack(tracks, even); updateAircraftTrack(tracks, odd); // 20 s later the pair has expired and there is no receiver location. const later = decodeAdsbMessage(fromHex('8D40621D58C386435CC412692AD6'), { receivedAt: 20_000, }); const track = updateAircraftTrack(tracks, later, null); assert.equal(track.lastPositionAt, 20_000); assert.ok(Math.abs(track.latitude - 52.26578) < 0.0001); assert.ok(Math.abs(track.longitude - 3.93891) < 0.0001); }); test('three refused global fixes in a row re-anchor the track', () => { const tracks = new Map(); const stats = {}; updateAircraftTrack( tracks, decodeAdsbMessage(fromHex('8D40621D58C382D690C8AC2863A7'), { receivedAt: 1_000, }), ); updateAircraftTrack( tracks, decodeAdsbMessage(fromHex('8D40621D58C386435CC412692AD6'), { receivedAt: 1_500, }), ); // Austin pairs relabelled as this aircraft: global decodes 8,000 km away. const austin = timed.frames .map(([, hex]) => decodeAdsbMessage(fromHex(hex))) .filter((message) => message?.icao === 'A0B702' && message.cpr); const firstOdd = austin.find((message) => message.cpr.odd); const firstEven = austin.find((message) => !message.cpr.odd); let at = 2_000; const feed = (message) => { at += 500; return updateAircraftTrack( tracks, { ...message, icao: '40621D', receivedAt: at, cpr: { ...message.cpr, receivedAt: at }, }, null, stats, ); }; feed(firstEven); let track = feed(firstOdd); assert.equal(track.rejectedPositions, 2); assert.ok(Math.abs(track.latitude - 52.26578) < 0.0001, 'still anchored'); track = feed(firstEven); assert.equal(stats.positionsRejected, 2, 'the third global fix re-anchors'); assert.ok(Math.abs(track.latitude - 30.2) < 0.2, 'moved to the new stream'); assert.equal(track.rejectStreak, 0); }); // Surface position examples from "The 1090MHz Riddle" (J. Sun), surface // position chapter: ICAO C8200A, even 8CC8200A3AC8F009BCDEF2..., odd // 8FC8200A3AB8F5F893096B..., receiver (-43.496, 172.558); published result // (-43.48564, 172.53942). The book prints the parity field as zeros, so the // 24-bit parity is recomputed here to make the frames CRC-valid. function withParity(hex) { const bytes = fromHex(hex); // The Mode S parity is the CRC remainder of the first 88 bits. const parity = modeSChecksum(bytes.slice(0, 11)); bytes[11] = (parity >> 16) & 0xff; bytes[12] = (parity >> 8) & 0xff; bytes[13] = parity & 0xff; assert.equal(modeSChecksum(bytes), 0); return bytes; } const SURFACE_EVEN = withParity('8CC8200A3AC8F009BCDEF2000000'); const SURFACE_ODD = withParity('8FC8200A3AB8F5F893096B000000'); const SURFACE_RECEIVER = { latitude: -43.496, longitude: 172.558 }; test('surface position messages decode movement, track and ground state', () => { // Odd frame ME field, read by hand: TC 00111 (7), MOV 0101011 (43), // S 1, TRK 0001111 (15), T 0, F 1. MOV 39–93 is 15 kt + 1 kt per step // (43 → 19 kt); TRK is in 360/128° steps (15 → 42.1875°). const odd = decodeAdsbMessage(SURFACE_ODD, { receivedAt: 2_000 }); assert.equal(odd.icao, 'C8200A'); assert.equal(odd.typeCode, 7); assert.equal(odd.onGround, true); assert.equal(odd.speedKt, 19); assert.equal(odd.headingDeg, 42.1875); assert.equal(odd.altitudeFt, null, 'no altitude on the surface'); assert.equal(odd.cpr.surface, true); assert.equal(odd.cpr.odd, true); // Even frame: MOV 0101100 (44 → 20 kt), same track. const even = decodeAdsbMessage(SURFACE_EVEN); assert.equal(even.speedKt, 20); assert.equal(even.cpr.odd, false); // A real Schiphol frame with a valid parity (Riddle ground-speed example): // MOV 0101010 (42 → 18 kt), S 1, TRK 0110010 (50 → 140.625°). const schiphol = decodeAdsbMessage(fromHex('8C4841753AAB238733C8CD4020B1')); assert.equal(schiphol.icao, '484175'); assert.equal(schiphol.speedKt, 18); assert.equal(schiphol.headingDeg, 140.625); // MOV 1 is "stopped"; MOV 0 and a track status of 0 carry no value. const stopped = withParity('8CC8200A3810F009BCDEF2000000'); const still = decodeAdsbMessage(stopped); assert.equal(still.speedKt, 0); assert.equal(still.headingDeg, undefined, 'track status 0: no track'); }); test('a surface even/odd pair decodes to the published position and marks the aircraft on the ground', () => { const tracks = new Map(); // Airborne first: the landing must clear the old altitude. const airborne = decodeAdsbMessage(fromHex('8D40621D58C382D690C8AC2863A7')); updateAircraftTrack( tracks, // Its altitude only: the CPR belongs to another aircraft. { ...airborne, icao: 'C8200A', receivedAt: 0, cpr: null }, SURFACE_RECEIVER, ); updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_EVEN, { receivedAt: 1_000 }), SURFACE_RECEIVER, ); const track = updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_ODD, { receivedAt: 2_000 }), SURFACE_RECEIVER, ); assert.ok( Math.abs(track.latitude - -43.48564) < 0.00001, `${track.latitude}`, ); assert.ok( Math.abs(track.longitude - 172.53942) < 0.00001, `${track.longitude}`, ); assert.equal(track.lastPositionAt, 2_000); assert.equal(track.onGround, true); assert.equal(track.altitudeFt, null); assert.equal(track.speedKt, 19); const record = recordFromDecoderTrack(track); assert.equal(record.onGround, true); assert.equal(record.altitudeFt, null); assert.ok(Math.abs(record.lat - -43.48564) < 0.00001); // An airborne position afterwards clears the ground state. const departed = updateAircraftTrack( tracks, { ...airborne, icao: 'C8200A', receivedAt: 3_000, cpr: null }, SURFACE_RECEIVER, ); assert.equal(departed.onGround, false); assert.equal(departed.altitudeFt, 38_000); }); test('a surface track is seeded by a pair; a single frame then decodes against its own fix', () => { // The receiver is not established to be within 45 NM of the aircraft, so a // lone surface frame does not decode against it (even though this one is). const receiver = { latitude: -43.5, longitude: 172.5 }; const tracks = new Map(); let track = updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_EVEN, { receivedAt: 1_000 }), receiver, ); assert.equal(track.lastPositionAt, null, 'no single-frame receiver fix'); // The even/odd pair seeds the track at the published position. track = updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_ODD, { receivedAt: 2_000 }), receiver, ); assert.ok(Math.abs(track.latitude - -43.48564) < 0.00001); assert.ok(Math.abs(track.longitude - 172.53942) < 0.00001); // With no receiver location, the aircraft's own recent fix is the reference // (the other frame of the pair is too old to pair with). track = updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_EVEN, { receivedAt: 40_000 }), null, ); assert.equal(track.lastPositionAt, 40_000); assert.ok(Math.abs(track.latitude - -43.4856) < 0.001); assert.ok(Math.abs(track.longitude - 172.5394) < 0.001); // An own fix the aircraft may have left by 45 NM or more (unknown speed, // four minutes old) is no single-frame reference either. tracks.set('C8200A', { ...track, speedKt: null, category: null }); track = updateAircraftTrack( tracks, decodeAdsbMessage(SURFACE_ODD, { receivedAt: 280_000 }), null, ); assert.equal(track.lastPositionAt, 40_000, 'reference too old to trust'); // Without any reference a lone surface frame is ambiguous: no position. const blind = updateAircraftTrack( new Map(), decodeAdsbMessage(SURFACE_ODD, { receivedAt: 1_000 }), null, ); assert.equal(blind.lastPositionAt, null); assert.equal(blind.onGround, true); }); // "The 1090MHz Riddle", surface position chapter: Schiphol pair of ICAO // 484175, published position about (52.3206, 4.7347). const SCHIPHOL_EVEN = fromHex('8C4841753AAB238733C8CD4020B1'); const SCHIPHOL_ODD = fromHex('8C4841753A9A153237AEF0F275BE'); test('a far receiver never places a lone surface frame; the next valid pair seeds the track', () => { // About 80 NM from the airport: beyond half a surface zone (45 NM). const receiver = { latitude: 51, longitude: 4.375 }; const tracks = new Map(); let track = updateAircraftTrack( tracks, decodeAdsbMessage(SCHIPHOL_EVEN, { receivedAt: 1_000 }), receiver, ); assert.equal(track.lastPositionAt, null, 'no position from one frame'); assert.equal(track.latitude, null, 'never (50.823040, 4.602622)'); track = updateAircraftTrack( tracks, decodeAdsbMessage(SCHIPHOL_ODD, { receivedAt: 2_000 }), receiver, ); assert.equal(track.lastPositionAt, 2_000); assert.equal(track.rejectedPositions, 0, 'the valid pair is accepted'); assert.ok(Math.abs(track.latitude - 52.3206) < 0.002, `${track.latitude}`); assert.ok(Math.abs(track.longitude - 4.7347) < 0.002, `${track.longitude}`); assert.equal(track.onGround, true); });