Documentation
¶
Overview ¶
Package adsb decodes Mode S downlink frames captured at 1090 MHz — both short-form (56-bit) surveillance replies and long-form (112-bit) extended squitter / ADS-B frames.
Wrap-vs-native judgement ¶
Native. The Mode S frame format and the ADS-B Extended Squitter sub-message family are fully published (ICAO Annex 10 Vol IV + RTCA DO-260 + EUROCAE ED-102). The CRC-24 generator (G(x) = 0x1FFF409) is a textbook bit-walking polynomial division. Type-code dispatch is a static switch over a 5-bit field. Pasting a hex blob captured by dump1090 / readsb / a Flipper-adjacent SDR feed is enough — no vendor SDK, no protocol negotiation, no hardware path.
What this package covers ¶
- Frame envelope: Downlink Format (DF, 5 bits) detection with a documented name table covering all 32 DF slots (DF0 / DF4 / DF5 / DF11 / DF16 / DF17 / DF18 / DF19 / DF20 / DF21 / DF24+ Comm-D extended length).
- Frame length validation: short (56 bits = 7 bytes) for DF0/4/5/11; long (112 bits = 14 bytes) for DF16-22 and DF24+.
- ICAO 24-bit aircraft address extraction for DF11/17/18 (where the AA field is in the clear; for other DFs the address is XOR-overlaid with the parity field — left to callers to recover via re-interrogation).
- Mode S CRC-24 validation (polynomial 0xFFF409, init 0, no reflection) — computes the expected parity field over the data portion and compares to the transmitted parity. Surfaces both the captured PI and the computed value for diffing.
- DF17 (ADS-B) Type Code dispatch covering the operationally important sub-types: TC 1-4 (Aircraft Identification with 8-character callsign decoded from the 6-bit AIS / IA-5 alphabet and emitter category lookup), TC 5-8 (Surface Position with movement decode, ground track, and raw CPR), TC 9-18 / 20-22 (Airborne Position with altitude decode from the 12-bit Q-bit field, raw CPR latitude/longitude, and odd/even frame flag), TC 19 (Airborne Velocity: subtype 1/2 ground speed and heading, subtype 3/4 airspeed and magnetic heading, vertical rate with source flag), TC 28 (Aircraft Status: emergency code / squawk), TC 29 (Target State and Status), TC 31 (Aircraft Operation Status).
What this package does NOT cover (deliberately out of scope) ¶
- CPR (Compact Position Reporting) lat/lon resolution: global resolution requires pairing an even-frame and an odd-frame from the same aircraft within ~10 seconds; this decoder exposes the raw 17-bit CPR values + the odd/even flag so a higher-level workflow / Spec can do the pairing. Local-CPR resolution (against a reference position) is intentionally deferred until the receiving side has somewhere to put the reference; otherwise the output would be misleading.
- DF1/2/3/6-10/12-15/22/23 reserved slot bodies — the DF name is reported but no body decode is attempted because no civil aviation traffic uses these slots in practice (and the bodies have no published civilian spec).
- Comm-B BDS register decoding for DF20/21 — only the DF envelope is decoded; the BDS payload requires a register-by-register decoder (BDS 1,7 / 4,0 / 4,4 / 5,0 / 6,0 etc.) which is a separate ~600 LoC effort.
- TIS-B (DF18) imitation-of-other-format payload variants: DF18 is decoded as if it were DF17, which is correct for the most common CF=0/CF=1 case. CF=2..7 sub-formats (ADS-R, fine TIS-B) are out of scope.
- Live demodulation from raw I/Q samples — frames must be pre-decoded to hex by an upstream demodulator (dump1090 --raw output, for instance).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ADSB ¶
type ADSB struct {
TC int `json:"tc"`
TCName string `json:"tc_name"`
Identification *Identification `json:"identification,omitempty"`
AirbornePosition *AirbornePosition `json:"airborne_position,omitempty"`
AirborneVelocity *AirborneVelocity `json:"airborne_velocity,omitempty"`
SurfacePosition *SurfacePosition `json:"surface_position,omitempty"`
}
ADSB carries the decoded Extended Squitter ME field (DF17 / DF18). Only one of the sub-pointers is set per frame — the one that matches the Type Code.
type AirbornePosition ¶
type AirbornePosition struct {
SurveillanceStatus int `json:"surveillance_status"`
AltitudeSource string `json:"altitude_source"`
AltitudeFt int `json:"altitude_ft,omitempty"`
AltitudeValid bool `json:"altitude_valid"`
CPRFormat int `json:"cpr_format"`
CPRLatRaw int `json:"cpr_lat_raw"`
CPRLonRaw int `json:"cpr_lon_raw"`
}
AirbornePosition is the decoded TC 9-18 / 20-22 Airborne Position message. Latitude/longitude are not resolved here — the caller pairs an even + odd frame for a global CPR solve. Altitude is decoded from the 12-bit field with the Q-bit (25-ft vs 100-ft resolution).
type AirborneVelocity ¶
type AirborneVelocity struct {
Subtype int `json:"subtype"`
SubtypeName string `json:"subtype_name"`
GroundSpeedKts *int `json:"ground_speed_kts,omitempty"`
GroundTrackDeg *float64 `json:"ground_track_deg,omitempty"`
AirspeedKts *int `json:"airspeed_kts,omitempty"`
AirspeedIsIAS bool `json:"airspeed_is_ias,omitempty"`
MagneticHeadingDeg *float64 `json:"magnetic_heading_deg,omitempty"`
VerticalRateFPM int `json:"vertical_rate_fpm"`
VerticalRateSource string `json:"vertical_rate_source"`
}
AirborneVelocity is the decoded TC 19 Airborne Velocity message. Subtypes 1/2 carry ground speed + ground track; subtypes 3/4 carry airspeed + magnetic heading.
type Frame ¶
type Frame struct {
HexInput string `json:"hex_input"`
BitCount int `json:"bit_count"`
DF int `json:"df"`
DFName string `json:"df_name"`
CA *int `json:"ca,omitempty"`
CAName string `json:"ca_name,omitempty"`
ICAOAddress string `json:"icao_address,omitempty"`
CRC string `json:"crc"`
CRCExpected string `json:"crc_expected"`
CRCValid bool `json:"crc_valid"`
ADSB *ADSB `json:"adsb,omitempty"`
}
Frame is the decoded view of a single Mode S downlink frame.
func Decode ¶
Decode parses a hex-encoded Mode S frame into a structured Frame view. Accepts ':', '-', '_', whitespace as separators and a leading '0x' prefix.
func DecodeBytes ¶
DecodeBytes parses a 7-byte (short) or 14-byte (long) Mode S frame into a Frame.
type Identification ¶
type Identification struct {
Category int `json:"category"`
CategoryName string `json:"category_name"`
Callsign string `json:"callsign"`
}
Identification is the decoded TC 1-4 Aircraft Identification message: 8-character callsign + emitter category.
type SurfacePosition ¶
type SurfacePosition struct {
Movement int `json:"movement"`
GroundSpeedKts *float64 `json:"ground_speed_kts,omitempty"`
GroundTrackDeg *float64 `json:"ground_track_deg,omitempty"`
GroundTrackValid bool `json:"ground_track_valid"`
CPRFormat int `json:"cpr_format"`
CPRLatRaw int `json:"cpr_lat_raw"`
CPRLonRaw int `json:"cpr_lon_raw"`
}
SurfacePosition is the decoded TC 5-8 Surface Position message — for aircraft on the ground.
Source Files