@squawk/mode-s 0.1.0

package/README.md

@@ -0,0 +1,243 @@
+<h1><img src="../../../assets/squawk-logo.svg" alt="squawk logo" width="48" height="48" style="vertical-align: middle">&nbsp; @squawk/mode-s</h1>
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../../LICENSE.md) [![npm](https://img.shields.io/npm/v/@squawk/mode-s)](https://www.npmjs.com/package/@squawk/mode-s) ![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)
+
+Decodes raw Mode-S/ADS-B messages: downlink format and CRC extraction, CPR
+position, airborne velocity, aircraft identification, altitude (both the
+ADS-B position-message field and legacy Gillham-coded surveillance replies),
+squawk identity, emergency status, ACAS/TCAS Resolution Advisories, target
+state and status, aircraft operational status, and Enhanced Surveillance
+Comm-B registers (selected vertical intention, track and turn, heading and
+speed). Transport-agnostic - it operates on already-framed message bytes and
+has no opinion about where they came from (a live Beast feed, a logged
+capture, or any other source). For a Beast binary parser and live TCP client
+built on top of this package, see [`@squawk/beast`](../beast).
+
+Part of the [@squawk](https://www.npmjs.com/org/squawk) aviation library suite. See all packages on npm.
+
+## Installation
+
+```bash
+npm install @squawk/mode-s
+```
+
+## Usage
+
+### Decoding a whole message
+
+`decodeModeSMessage` is the main entry point - it reads the downlink format,
+validates the CRC, and routes to the right per-type decoder, returning a
+single discriminated result.
+
+```typescript
+import { decodeModeSMessage } from '@squawk/mode-s';
+
+const decoded = decodeModeSMessage(rawMessageBytes); // 7 or 14 raw bytes
+if (decoded?.kind === 'extendedSquitterPosition') {
+  console.log(decoded.icaoHex, decoded.latCpr, decoded.lonCpr, decoded.altitudeFt);
+}
+```
+
+`bytes`' length must match what its downlink format implies (7 bytes for a
+short message, 14 for long) or the message is rejected outright - a length
+mismatch means the buffer is truncated or corrupted, not a genuine message
+of that format.
+
+DF17/18 (extended squitter) messages are only decoded when their CRC checks
+out exactly - a corrupted squitter reports as undecodable rather than
+returning plausible-looking wrong data. DF18 is further gated on its control
+field: CF=0/1/2/5/6 share DF17's type-code-coded ME layout and decode the
+same way; CF=3 (TIS-B coarse format) uses a different field layout this
+package does not decode, and CF=4/7 carry no per-aircraft state. Every
+decoded DF17/18 message carries `messageSource`, so a consumer can tell a
+real, direct ICAO address from an anonymous or ground-derived one rather
+than losing that distinction after the gate:
+
+```typescript
+const decoded = decodeModeSMessage(rawMessageBytes);
+if (decoded?.kind === 'extendedSquitterPosition' && decoded.messageSource !== 'icaoDirect') {
+  // decoded.icaoHex may not be a registered ICAO address (anonymousDirect/anonymousTisb),
+  // or the position may be ground-derived rather than heard directly (icaoTisb/adsr)
+}
+```
+
+DF0/4/5/20/21 (Mode-S surveillance replies) are targeted responses whose CRC
+is XORed with the responding aircraft's ICAO address rather than being a
+plain checksum, so their `candidateIcaoHex` needs cross-checking against an
+address already known from squitter traffic before it can be trusted - this
+package doesn't perform that cross-check itself. DF20/21 (`'commBAltitudeReply'`/`'commBIdentityReply'`)
+carry the same altitude/squawk payload as DF4/5 plus a 56-bit MB field,
+decoded into `commBRegisters` - see
+[Enhanced Surveillance Comm-B registers](#enhanced-surveillance-comm-b-registers).
+
+### Resolving CPR position
+
+Airborne and surface position messages carry raw CPR-encoded lat/lon
+fields, not a directly usable position - resolving them needs either a
+paired even/odd frame or a nearby reference position, and pairing state
+(tracking the most recent even and odd frame per aircraft) is the caller's
+responsibility, not this package's:
+
+```typescript
+import { decodeAirborneCprPair, decodeAirborneCprWithReference } from '@squawk/mode-s';
+
+// From a paired even + odd frame (global decode, no reference needed)
+const position = decodeAirborneCprPair(evenFrame, oddFrame, 'even');
+
+// From a single frame plus a known-nearby reference (e.g. the aircraft's
+// last known position, or the receiver's own location for a new aircraft)
+const position2 = decodeAirborneCprWithReference('even', frame, referencePosition);
+```
+
+`decodeSurfaceCprPair` / `decodeSurfaceCprWithReference` are the equivalents
+for on-ground traffic (type codes 5-8), which additionally need a reference
+position to resolve the correct hemisphere and longitude quadrant.
+
+An airborne position message with type code 0 signals that no position fix
+is currently available - `latCpr`/`lonCpr` are undefined in that case even
+though `altitudeFt` may still be populated.
+
+### ACAS / TCAS Resolution Advisories
+
+An active Resolution Advisory reaches `decodeModeSMessage` two ways: DF16
+(a targeted air-air surveillance reply, replacing DF0 while an RA is active)
+and a DF17/18 type-code-28 subtype-2 message (the same report broadcast over
+ADS-B so aircraft without interrogation capability can still see it).
+
+```typescript
+const decoded = decodeModeSMessage(rawMessageBytes);
+if (decoded?.kind === 'longAirAirSurveillanceReply' && decoded.resolutionAdvisory?.active) {
+  console.log(decoded.resolutionAdvisory.advisoryType); // e.g. 'climb', 'crossingDescend', 'increaseClimb'
+}
+```
+
+`advisoryType` names the RA per RTCA DO-185B Table 2-16 (`climb`, `descend`,
+`crossingClimb`, `crossingDescend`, `increaseClimb`, `increaseDescent`,
+`reduceClimb`, `reduceDescent`, `doNotClimb`, `doNotDescend`,
+`reversalToClimb`, `reversalToDescend`), derived from the report's
+corrective/sense/rate/crossing/reversal flags - all of which are also
+exposed individually on `AcasResolutionAdvisoryReport`, along with the
+Resolution Advisory Complement flags (`doNotPassBelow`/`doNotPassAbove`;
+`doNotTurnLeft`/`doNotTurnRight` are decoded for completeness but TCAS II
+issues vertical RAs only, so they are expected to always be false). `advisoryType`
+is undefined when no RA is currently active, or for the one flag combination
+DO-185B leaves undefined (positive + preventive).
+
+`threat` identifies what the RA is responding to, discriminated by
+`threat.threatType`:
+
+```typescript
+if (decoded.resolutionAdvisory?.threat.threatType === 'icaoAddress') {
+  console.log(decoded.resolutionAdvisory.threat.threatIcaoHex);
+}
+```
+
+`'none'` carries no further fields; `'icaoAddress'` carries `threatIcaoHex`;
+`'altitudeRangeBearing'` carries `threatAltitudeFt`/`threatRangeNm`/`threatBearingDeg`
+(each independently undefined if that specific field is unavailable).
+
+### Target state and status
+
+A type-code-29 ADS-B message reports what the aircraft's flight management
+system is currently targeting - selected altitude, selected heading, and
+which autopilot modes are engaged - not the aircraft's actual state:
+
+```typescript
+const decoded = decodeModeSMessage(rawMessageBytes);
+if (decoded?.kind === 'extendedSquitterTargetStateAndStatus') {
+  console.log(
+    decoded.targetStateAndStatus.selectedAltitudeFt,
+    decoded.targetStateAndStatus.selectedHeadingDeg,
+  );
+}
+```
+
+Each field is independently undefined when its source data isn't available -
+`selectedAltitudeSource` further distinguishes an MCP/FCU-selected altitude
+from an FMS-selected one. `autopilotEngaged`/`vnavModeActive`/`altitudeHoldModeActive`/`approachModeActive`/`lnavModeActive`
+are reported together (all defined or all undefined) since they share a
+single status bit; `tcasOperational` has its own independent status.
+
+### Aircraft operational status
+
+A type-code-31 ADS-B message reports the transmitting aircraft's ADS-B
+version, surveillance integrity/accuracy figures, and heading reference -
+metadata about the quality of the aircraft's other broadcasts rather than
+its position or state:
+
+```typescript
+const decoded = decodeModeSMessage(rawMessageBytes);
+if (decoded?.kind === 'extendedSquitterOperationalStatus') {
+  console.log(
+    decoded.operationalStatus.adsbVersion,
+    decoded.operationalStatus.navAccuracyCategoryPosition,
+  );
+}
+```
+
+`capabilityClassCode`/`operationalModeCode` are exposed as their raw 16-bit
+values rather than individually decoded sub-fields. `nicBaro` is only
+populated for an airborne report on ADS-B version 1+; `silSupplementPerHour`
+is only populated on version 2, where SIL changes from "per sample" to a
+choice between per-sample and per-hour.
+
+### Enhanced Surveillance Comm-B registers
+
+DF20/21's 56-bit MB field can carry any of several "Enhanced Surveillance"
+Comm-B registers (BDS 4,0 selected vertical intention, BDS 5,0 track and
+turn report, BDS 6,0 heading and speed report), but unlike a DF17/18 ME
+field's type code, nothing in the message itself declares which one. This
+package validates the MB field's bytes against each register's expected
+structure (status-bit consistency, reserved bits, physically-plausible
+ranges) and returns every register that plausibly matches - usually exactly
+one, occasionally none, and occasionally more than one when the bytes are
+genuinely ambiguous (BDS 5,0 and 6,0 are the pair most likely to overlap):
+
+```typescript
+const decoded = decodeModeSMessage(rawMessageBytes);
+if (decoded?.kind === 'commBAltitudeReply') {
+  for (const register of decoded.commBRegisters) {
+    if (register.bdsCode === '5,0') {
+      console.log(register.rollAngleDeg, register.trueTrackDeg, register.groundSpeedKt);
+    }
+  }
+}
+```
+
+`inferCommBRegisters(mb)` is also exported directly for callers working with
+a raw MB field outside of `decodeModeSMessage`'s DF20/21 dispatch.
+
+### Mode A/C
+
+Mode A/C predates Mode-S and carries no ICAO address, so it has no natural
+key in an ICAO-hex-indexed tracking model - it's decoded here, but
+deliberately not part of `decodeModeSMessage`'s dispatch:
+
+```typescript
+import { decodeModeAc } from '@squawk/mode-s';
+
+const reply = decodeModeAc(twoRawBytes);
+console.log(reply.squawk, reply.identActive, reply.altitudeFt);
+```
+
+## API
+
+- `decodeModeSMessage(bytes)` - decodes a raw 7 or 14 byte Mode-S message into a discriminated `DecodedModeSMessage`.
+- `decodeModeAc(bytes)` - decodes a raw 2-byte Mode A/C reply.
+- `parseModeSFrame(bytes)`, `extractDownlinkFormat(bytes)`, `computeCrc24(bytes)` - lower-level envelope parsing, used internally by `decodeModeSMessage`.
+- `decodeAirborneCprPair`, `decodeAirborneCprWithReference`, `decodeSurfaceCprPair`, `decodeSurfaceCprWithReference`, `cprNumLongitudeZones` - CPR position resolution.
+- `decodeAirborneVelocity(me)` - airborne velocity/heading from a type-19 ME field.
+- `decodeIdentification(me)` - callsign and category from a type 1-4 ME field.
+- `decodeIdentityCode(idField)` - 4-digit octal squawk from a 13-bit identity field (shared by DF5/21 and ADS-B emergency status).
+- `decodeAltitudeCode(altitudeCode)`, `decodeAdsbPositionAltitude(field)`, `decodeAdsbGnssAltitude(field)` - altitude decoding.
+- `decodeSurfaceMovement(field)` - ground speed from a surface position message's movement field.
+- `decodeEmergencyState(rawState)` - emergency/priority state from an ADS-B aircraft status message.
+- `decodeAcasResolutionAdvisory(payload)` - ACAS/TCAS Resolution Advisory report from a DF16 MV field or a type-code-28 subtype-2 ME field.
+- `decodeTargetStateAndStatus(me)` - target state and status from a type-29 ME field.
+- `decodeAircraftOperationalStatus(me)` - operational status from a type-31 ME field.
+- `inferCommBRegisters(mb)` - every Enhanced Surveillance Comm-B register (BDS 4,0/5,0/6,0) a DF20/21 MB field plausibly holds.
+- `decodeSelectedVerticalIntention(mb)`, `decodeTrackAndTurnReport(mb)`, `decodeHeadingAndSpeedReport(mb)` - decode a single Comm-B register directly, given its BDS code is already known.
+
+Every decoder that can fail to produce a result returns `undefined` rather
+than throwing - a message that doesn't decode cleanly (unsupported type,
+failed CRC, reserved value) is an expected outcome, not an exceptional one.

package/dist/acas.d.ts

@@ -0,0 +1,14 @@
+import type { AcasResolutionAdvisoryReport } from './types/index.js';
+/**
+ * Decodes an ACAS/TCAS Resolution Advisory report (BDS 3,0 content), shared
+ * by DF16's MV field and a DF17/18 type-code-28 subtype-2 ME field - both
+ * carry the same 48 bits of content starting at bit 8 of the 7-byte buffer
+ * (DF16's MV reserves its first byte for a register-identifier convention;
+ * TC28/ST2's ME uses that same first byte for its type-code-and-subtype
+ * header instead - either way, content starts at bit 8).
+ *
+ * @param payload - The 7-byte field: DF16's MV, or a type-code-28 subtype-2 ME.
+ * @returns The decoded report, or undefined if the Threat Type Indicator is the reserved value (not a legitimate report).
+ */
+export declare function decodeAcasResolutionAdvisory(payload: Uint8Array): AcasResolutionAdvisoryReport | undefined;
+//# sourceMappingURL=acas.d.ts.map

package/dist/acas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acas.d.ts","sourceRoot":"","sources":["../src/acas.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,4BAA4B,EAG7B,MAAM,kBAAkB,CAAC;AA4D1B;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,UAAU,GAClB,4BAA4B,GAAG,SAAS,CAuC1C"}

package/dist/acas.js

@@ -0,0 +1,90 @@
+import { decodeAltitudeCode } from './altitude.js';
+import { extractBits, formatHexAddress } from './bits.js';
+/** Reserved Threat Type Indicator value - not a legitimate report. */
+const TTI_RESERVED = 3;
+/** Decodes the threat-identity data (bits 28-55) per the Threat Type Indicator, `threatTypeIndicator`. */
+function decodeThreat(payload, threatTypeIndicator) {
+    if (threatTypeIndicator === 1) {
+        return {
+            threatType: 'icaoAddress',
+            threatIcaoHex: formatHexAddress(extractBits(payload, 30, 24)),
+        };
+    }
+    if (threatTypeIndicator === 2) {
+        const rangeRaw = extractBits(payload, 43, 7);
+        const bearingRaw = extractBits(payload, 50, 6);
+        return {
+            threatType: 'altitudeRangeBearing',
+            threatAltitudeFt: decodeAltitudeCode(extractBits(payload, 30, 13)),
+            threatRangeNm: rangeRaw > 0 ? (rangeRaw - 1) / 10 : undefined,
+            threatBearingDeg: bearingRaw > 0 ? 6 * (bearingRaw - 1) + 3 : undefined,
+        };
+    }
+    return { threatType: 'none' };
+}
+function decodeAdvisoryType(active, corrective, downwardSense, increasedRate, senseReversal, altitudeCrossing, positive) {
+    if (!active) {
+        return undefined;
+    }
+    if (!corrective) {
+        // Preventive: DO-185B defines no positive-preventive RA type.
+        if (positive) {
+            return undefined;
+        }
+        return downwardSense ? 'doNotClimb' : 'doNotDescend';
+    }
+    if (senseReversal) {
+        return downwardSense ? 'reversalToDescend' : 'reversalToClimb';
+    }
+    if (increasedRate) {
+        return downwardSense ? 'increaseDescent' : 'increaseClimb';
+    }
+    if (!positive) {
+        return downwardSense ? 'reduceClimb' : 'reduceDescent';
+    }
+    if (downwardSense) {
+        return altitudeCrossing ? 'crossingDescend' : 'descend';
+    }
+    return altitudeCrossing ? 'crossingClimb' : 'climb';
+}
+/**
+ * Decodes an ACAS/TCAS Resolution Advisory report (BDS 3,0 content), shared
+ * by DF16's MV field and a DF17/18 type-code-28 subtype-2 ME field - both
+ * carry the same 48 bits of content starting at bit 8 of the 7-byte buffer
+ * (DF16's MV reserves its first byte for a register-identifier convention;
+ * TC28/ST2's ME uses that same first byte for its type-code-and-subtype
+ * header instead - either way, content starts at bit 8).
+ *
+ * @param payload - The 7-byte field: DF16's MV, or a type-code-28 subtype-2 ME.
+ * @returns The decoded report, or undefined if the Threat Type Indicator is the reserved value (not a legitimate report).
+ */
+export function decodeAcasResolutionAdvisory(payload) {
+    const threatTypeIndicator = extractBits(payload, 28, 2);
+    if (threatTypeIndicator === TTI_RESERVED) {
+        return undefined;
+    }
+    const active = extractBits(payload, 8, 1) === 1;
+    const corrective = extractBits(payload, 9, 1) === 1;
+    const downwardSense = extractBits(payload, 10, 1) === 1;
+    const increasedRate = extractBits(payload, 11, 1) === 1;
+    const senseReversal = extractBits(payload, 12, 1) === 1;
+    const altitudeCrossing = extractBits(payload, 13, 1) === 1;
+    const positive = extractBits(payload, 14, 1) === 1;
+    return {
+        active,
+        advisoryType: decodeAdvisoryType(active, corrective, downwardSense, increasedRate, senseReversal, altitudeCrossing, positive),
+        corrective,
+        downwardSense,
+        increasedRate,
+        senseReversal,
+        altitudeCrossing,
+        positive,
+        doNotPassBelow: extractBits(payload, 22, 1) === 1,
+        doNotPassAbove: extractBits(payload, 23, 1) === 1,
+        doNotTurnLeft: extractBits(payload, 24, 1) === 1,
+        doNotTurnRight: extractBits(payload, 25, 1) === 1,
+        terminated: extractBits(payload, 26, 1) === 1,
+        multipleThreat: extractBits(payload, 27, 1) === 1,
+        threat: decodeThreat(payload, threatTypeIndicator),
+    };
+}

package/dist/altitude.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Decodes a 13-bit Mode-S altitude code (the AC field of DF0/4/16/20
+ * surveillance replies) to feet, per ICAO Annex 10 Vol. IV / RTCA DO-260.
+ *
+ * The field supports two encodings, selected by the Q bit: a 25-foot
+ * linear encoding (Q=1), or a 100-foot Gillham (Gray code) encoding
+ * (Q=0) - the legacy scheme shared with Mode-C. Bit layout, MSB first:
+ * `C1 A1 C2 A2 C4 A4 M B1 Q B2 D2 B4 D4`.
+ *
+ * @param altitudeCode - The raw 13-bit AC field, 0-8191.
+ * @returns Altitude in feet, or undefined if the field is all-zero (altitude unknown), reports the rare M (metric) encoding, or contains an invalid Gillham value.
+ */
+export declare function decodeAltitudeCode(altitudeCode: number): number | undefined;
+/**
+ * Decodes the 12-bit altitude field of an ADS-B airborne position message
+ * (type codes 9-18, barometric altitude). The field omits the M bit that
+ * {@link decodeAltitudeCode}'s 13-bit AC field carries, so it is
+ * re-inserted (always 0 - the M encoding never appears in ADS-B position
+ * messages) before delegating to the shared Gillham/linear decoder.
+ *
+ * @param positionAltitudeField - The raw 12-bit altitude field from bits 8-19 of an airborne position ME field.
+ * @returns Altitude in feet, or undefined if unavailable.
+ */
+export declare function decodeAdsbPositionAltitude(positionAltitudeField: number): number | undefined;
+/**
+ * Decodes the GNSS altitude field of an ADS-B airborne position message
+ * (type codes 20-22). Unlike barometric altitude, this field is a plain
+ * 12-bit integer in meters - no Gillham or linear-code decoding involved.
+ *
+ * @param gnssAltitudeField - The raw 12-bit altitude field from bits 8-19 of a GNSS-altitude position ME field.
+ * @returns Altitude in feet.
+ */
+export declare function decodeAdsbGnssAltitude(gnssAltitudeField: number): number;
+//# sourceMappingURL=altitude.d.ts.map

package/dist/altitude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"altitude.d.ts","sourceRoot":"","sources":["../src/altitude.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAyD3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG5F;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/altitude.js

@@ -0,0 +1,99 @@
+import { bitAt } from './bits.js';
+/** 13-bit field width shared by the altitude (AC) and identity (ID) fields. */
+const FIELD_WIDTH = 13;
+/**
+ * Converts an unsigned Gillham code (a reflected Gray-code variant) to a
+ * plain binary integer via the standard Gray-to-binary fold.
+ */
+function grayToBinary(value, bitWidth) {
+    let result = value;
+    for (let shift = 1; shift < bitWidth; shift *= 2) {
+        result ^= result >> shift;
+    }
+    return result;
+}
+/**
+ * Decodes a 13-bit Mode-S altitude code (the AC field of DF0/4/16/20
+ * surveillance replies) to feet, per ICAO Annex 10 Vol. IV / RTCA DO-260.
+ *
+ * The field supports two encodings, selected by the Q bit: a 25-foot
+ * linear encoding (Q=1), or a 100-foot Gillham (Gray code) encoding
+ * (Q=0) - the legacy scheme shared with Mode-C. Bit layout, MSB first:
+ * `C1 A1 C2 A2 C4 A4 M B1 Q B2 D2 B4 D4`.
+ *
+ * @param altitudeCode - The raw 13-bit AC field, 0-8191.
+ * @returns Altitude in feet, or undefined if the field is all-zero (altitude unknown), reports the rare M (metric) encoding, or contains an invalid Gillham value.
+ */
+export function decodeAltitudeCode(altitudeCode) {
+    if (altitudeCode === 0) {
+        return undefined;
+    }
+    const bitOf = (pos) => bitAt(altitudeCode, pos, FIELD_WIDTH);
+    const mBit = bitOf(6);
+    const qBit = bitOf(8);
+    if (mBit === 0 && qBit === 1) {
+        // 25-foot linear encoding: drop the M and Q bits, the remaining 11 bits
+        // form the value - the top 6 bits (C1A1C2A2C4A4), then B1, then the
+        // bottom 4 bits (B2D2B4D4).
+        const topSixBits = (altitudeCode >> 7) & 0x3f;
+        const bottomFourBits = altitudeCode & 0xf;
+        const n = (topSixBits << 5) | (bitOf(7) << 4) | bottomFourBits;
+        return n * 25 - 1000;
+    }
+    if (mBit === 0 && qBit === 0) {
+        const c1 = bitOf(0);
+        const a1 = bitOf(1);
+        const c2 = bitOf(2);
+        const a2 = bitOf(3);
+        const c4 = bitOf(4);
+        const a4 = bitOf(5);
+        const b1 = bitOf(7);
+        const b2 = bitOf(9);
+        const d2 = bitOf(10);
+        const b4 = bitOf(11);
+        const d4 = bitOf(12);
+        // Re-order into an 8-bit 500 ft Gillham counter and a 3-bit 100 ft
+        // Gillham counter, per ICAO Annex 10 Vol. IV / DO-260.
+        const gray500 = (d2 << 7) | (d4 << 6) | (a1 << 5) | (a2 << 4) | (a4 << 3) | (b1 << 2) | (b2 << 1) | b4;
+        const gray100 = (c1 << 2) | (c2 << 1) | c4;
+        const n500 = grayToBinary(gray500, 8);
+        let n100 = grayToBinary(gray100, 4);
+        if (n100 === 0 || n100 === 5 || n100 === 6) {
+            return undefined;
+        }
+        if (n100 === 7) {
+            n100 = 5;
+        }
+        if (n500 % 2 === 1) {
+            n100 = 6 - n100;
+        }
+        return n500 * 500 + n100 * 100 - 1300;
+    }
+    // M = 1: rare, non-standard meter-based encoding. Not decoded.
+    return undefined;
+}
+/**
+ * Decodes the 12-bit altitude field of an ADS-B airborne position message
+ * (type codes 9-18, barometric altitude). The field omits the M bit that
+ * {@link decodeAltitudeCode}'s 13-bit AC field carries, so it is
+ * re-inserted (always 0 - the M encoding never appears in ADS-B position
+ * messages) before delegating to the shared Gillham/linear decoder.
+ *
+ * @param positionAltitudeField - The raw 12-bit altitude field from bits 8-19 of an airborne position ME field.
+ * @returns Altitude in feet, or undefined if unavailable.
+ */
+export function decodeAdsbPositionAltitude(positionAltitudeField) {
+    const altitudeCode = ((positionAltitudeField >> 6) << 7) | (positionAltitudeField & 0x3f);
+    return decodeAltitudeCode(altitudeCode);
+}
+/**
+ * Decodes the GNSS altitude field of an ADS-B airborne position message
+ * (type codes 20-22). Unlike barometric altitude, this field is a plain
+ * 12-bit integer in meters - no Gillham or linear-code decoding involved.
+ *
+ * @param gnssAltitudeField - The raw 12-bit altitude field from bits 8-19 of a GNSS-altitude position ME field.
+ * @returns Altitude in feet.
+ */
+export function decodeAdsbGnssAltitude(gnssAltitudeField) {
+    return Math.round(gnssAltitudeField * 3.28084);
+}

package/dist/bits.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Extracts an unsigned integer from `bitLength` bits starting at `bitOffset`
+ * (0-indexed from the MSB of `bytes`), crossing byte boundaries as needed.
+ *
+ * JavaScript's bitwise operators work on 32-bit signed integers, so a raw
+ * Mode-S ME field (56 bits) can't be treated as one shifted integer the way
+ * a language with arbitrary-precision integers can. This reads bit by bit
+ * instead, safe for any field up to 31 bits - comfortably more than any
+ * single field this package decodes.
+ *
+ * @param bytes - The byte array to read from.
+ * @param bitOffset - Index of the first bit to read, 0-indexed from the MSB of `bytes[0]`.
+ * @param bitLength - Number of bits to read.
+ * @returns The extracted value as an unsigned integer.
+ */
+export declare function extractBits(bytes: Uint8Array, bitOffset: number, bitLength: number): number;
+/**
+ * Extracts a single bit directly from an already-extracted integer field,
+ * at `bitPosition` (0-indexed from the MSB of a `fieldWidth`-bit field).
+ * For fields already narrow enough to fit safely in a plain 32-bit
+ * bitwise op (comfortably true for anything this package decodes, e.g. a
+ * 13-bit identity or altitude code) - {@link extractBits}'s byte-array
+ * form exists to cross byte boundaries within a much wider ME field, which
+ * a single already-extracted small field never needs to do.
+ *
+ * @param value - The field's value, e.g. a 13-bit integer in [0, 8191].
+ * @param bitPosition - Index of the bit to read, 0-indexed from the MSB.
+ * @param fieldWidth - Total width of the field in bits.
+ * @returns The bit at that position, 0 or 1.
+ */
+export declare function bitAt(value: number, bitPosition: number, fieldWidth: number): number;
+/**
+ * Formats a 24-bit value (an ICAO address, a recovered CRC-XOR address, or
+ * any other 24-bit identifier this package handles) as 6 uppercase hex
+ * digits, zero-padded.
+ *
+ * @param value - The 24-bit value, 0-16777215.
+ * @returns The value as 6 uppercase hex digits.
+ */
+export declare function formatHexAddress(value: number): string;
+//# sourceMappingURL=bits.d.ts.map

package/dist/bits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bits.d.ts","sourceRoot":"","sources":["../src/bits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAW3F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/dist/bits.js

@@ -0,0 +1,55 @@
+/**
+ * Extracts an unsigned integer from `bitLength` bits starting at `bitOffset`
+ * (0-indexed from the MSB of `bytes`), crossing byte boundaries as needed.
+ *
+ * JavaScript's bitwise operators work on 32-bit signed integers, so a raw
+ * Mode-S ME field (56 bits) can't be treated as one shifted integer the way
+ * a language with arbitrary-precision integers can. This reads bit by bit
+ * instead, safe for any field up to 31 bits - comfortably more than any
+ * single field this package decodes.
+ *
+ * @param bytes - The byte array to read from.
+ * @param bitOffset - Index of the first bit to read, 0-indexed from the MSB of `bytes[0]`.
+ * @param bitLength - Number of bits to read.
+ * @returns The extracted value as an unsigned integer.
+ */
+export function extractBits(bytes, bitOffset, bitLength) {
+    let value = 0;
+    for (let i = 0; i < bitLength; i++) {
+        const bitPos = bitOffset + i;
+        const byteIndex = bitPos >> 3;
+        const bitInByte = 7 - (bitPos & 7);
+        const byte = bytes[byteIndex] ?? 0;
+        const bit = (byte >> bitInByte) & 1;
+        value = (value << 1) | bit;
+    }
+    return value;
+}
+/**
+ * Extracts a single bit directly from an already-extracted integer field,
+ * at `bitPosition` (0-indexed from the MSB of a `fieldWidth`-bit field).
+ * For fields already narrow enough to fit safely in a plain 32-bit
+ * bitwise op (comfortably true for anything this package decodes, e.g. a
+ * 13-bit identity or altitude code) - {@link extractBits}'s byte-array
+ * form exists to cross byte boundaries within a much wider ME field, which
+ * a single already-extracted small field never needs to do.
+ *
+ * @param value - The field's value, e.g. a 13-bit integer in [0, 8191].
+ * @param bitPosition - Index of the bit to read, 0-indexed from the MSB.
+ * @param fieldWidth - Total width of the field in bits.
+ * @returns The bit at that position, 0 or 1.
+ */
+export function bitAt(value, bitPosition, fieldWidth) {
+    return (value >> (fieldWidth - 1 - bitPosition)) & 1;
+}
+/**
+ * Formats a 24-bit value (an ICAO address, a recovered CRC-XOR address, or
+ * any other 24-bit identifier this package handles) as 6 uppercase hex
+ * digits, zero-padded.
+ *
+ * @param value - The 24-bit value, 0-16777215.
+ * @returns The value as 6 uppercase hex digits.
+ */
+export function formatHexAddress(value) {
+    return value.toString(16).padStart(6, '0').toUpperCase();
+}

package/dist/comm-b.d.ts

@@ -0,0 +1,37 @@
+import type { CommBRegister, HeadingAndSpeedReport, SelectedVerticalIntention, TrackAndTurnReport } from './types/index.js';
+/**
+ * Decodes a BDS 4,0 (Selected Vertical Intention) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 4,0.
+ * @returns The decoded selected vertical intention.
+ */
+export declare function decodeSelectedVerticalIntention(mb: Uint8Array): SelectedVerticalIntention;
+/**
+ * Decodes a BDS 5,0 (Track and Turn Report) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 5,0.
+ * @returns The decoded track and turn report.
+ */
+export declare function decodeTrackAndTurnReport(mb: Uint8Array): TrackAndTurnReport;
+/**
+ * Decodes a BDS 6,0 (Heading and Speed Report) register.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply, already known (or inferred via {@link inferCommBRegisters}) to be BDS 6,0.
+ * @returns The decoded heading and speed report.
+ */
+export declare function decodeHeadingAndSpeedReport(mb: Uint8Array): HeadingAndSpeedReport;
+/**
+ * Infers which "Enhanced Surveillance" Comm-B register(s) a DF20/21 MB
+ * field plausibly holds, and decodes each. Unlike DF17/18's type-code-coded
+ * ME field, a Comm-B MB field carries no self-declared register identifier
+ * for BDS 4,0/5,0/6,0 - this package would rather report every plausible
+ * candidate (via structural and range validation, matching pyModeS's own
+ * approach to this exact ambiguity) than silently guess a single wrong
+ * answer. In practice this is usually unambiguous; BDS 5,0 and 6,0 are the
+ * pair most likely to both pass validation for the same bytes.
+ *
+ * @param mb - The 7-byte MB field of a DF20/21 Comm-B reply.
+ * @returns Every register this MB field plausibly holds - empty if none, one if unambiguous, more than one if genuinely ambiguous.
+ */
+export declare function inferCommBRegisters(mb: Uint8Array): CommBRegister[];
+//# sourceMappingURL=comm-b.d.ts.map

package/dist/comm-b.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comm-b.d.ts","sourceRoot":"","sources":["../src/comm-b.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AA6E1B;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,EAAE,EAAE,UAAU,GAAG,yBAAyB,CAkBzF;AA6CD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,UAAU,GAAG,kBAAkB,CA0B3E;AAoDD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,UAAU,GAAG,qBAAqB,CAoBjF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,UAAU,GAAG,aAAa,EAAE,CAYnE"}