antirez/dump1090

1. Overall shape

- This repo is a single-process, monolithic C application centered on dump1090.c.

- The executable ingests Mode S/ADS-B data, decodes it, maintains aircraft state, and fans that state out through several output channels.

2. Primary input boundary

- The decoder can read from RTLSDR hardware directly, or from IQ sample files / stdin via --ifile.

- It can also accept network-fed raw Mode S frames on a raw input socket (--net, port 30001 in the README’s detailed section), making it usable as both a receiver and an aggregation hub.

3. Signal-processing and packet detection

- The core pipeline starts with 2 MHz IQ sample processing, looking for Mode S preambles and message shapes in the sample stream.

- This layer performs demodulation, packet detection, and error handling, including CRC-based bit correction and an “aggressive” mode that tolerates more decoding ambiguity at higher CPU cost.

4. Message decoding subsystem

- After packet detection, the program decodes multiple Mode S downlink formats, notably DF11 and DF17, plus several others using ICAO checksum brute forcing.

- This is where the repository turns raw RF data into structured aircraft messages like identity, altitude, velocity, and position.

5. Stateful aircraft tracking

- Decoded messages are aggregated into an in-memory aircraft table representing currently observed aircraft.

- The tracker computes tracks from velocity, performs CPR position decoding, and handles surface position decoding for aircraft on the ground.

6. Position reference strategy

- Surface-position decoding depends on a reference location.

- Instead of requiring user-configured receiver coordinates, the program derives a reference by averaging successfully decoded airborne positions, which is an important architectural choice because it couples surface decoding to already-decoded airborne traffic.

7. Output fan-out

- The same decoded stream is exposed through multiple interfaces:

- stdout / raw hex output for simple CLI consumption,

- an interactive terminal mode for a live aircraft list,

- SBS/BaseStation format on TCP port 30003,

- raw packet streaming on port 30002,

- and raw packet ingest on port 30001.

- This makes the binary both a decoder and a protocol bridge.

8. Embedded web/UI layer

- With networking enabled, Dump1090 includes an embedded HTTP server that serves a live map view of detected aircraft.

- The repo includes gmap.html, indicating the browser UI is a static page backed by live server data, with Google Maps as the visual front end.

9. Debug and visualization tooling

- The tools/debug.html asset supports a debug visualization mode that renders packet frames produced by the decoder.

- This is separate from the normal operational UI and is aimed at understanding the demodulation/detection pipeline.

10. Network abstraction

- anet.c and anet.h are a small socket/network helper layer used by the server and client plumbing.

- Architecturally, this is the boundary between the decoder core and the operating system’s TCP/IP interfaces.

11. Test and sample data

- testfiles/modes1.bin is a bundled sample IQ capture used to exercise the decoder without hardware.

- This confirms the project is intended to be testable offline, with file input standing in for RF capture.

12. Build and deployment

- The repo is intentionally minimal: Makefile builds the executable, and there are no large framework dependencies.

- The project is BSD-licensed and designed as a compact, understandable C codebase rather than a layered platform.

13. Architectural summary

- The key diagram should show a single decoder pipeline in the center:

- IQ samples / network frames in,

- demodulation + CRC/error repair,

- message decode,

- aircraft state update,

- then parallel outputs to terminal, TCP sockets, and embedded web UI.

- The important boundaries are RF/sample ingestion, decoder/state management, and multi-protocol output serving.