# antirez/dump1090 architecture

> Architecture diagram of the GitHub repository antirez/dump1090, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antirez/dump1090
- Repository: https://github.com/antirez/dump1090

## Overview

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**.

Main entry points: [`dump1090.c`](https://github.com/antirez/dump1090/blob/master/dump1090.c) (dump1090.c), [`anet.c`](https://github.com/antirez/dump1090/blob/master/anet.c) (anet.c/h), [`gmap.html`](https://github.com/antirez/dump1090/blob/master/gmap.html) (gmap.html), [`tools/debug.html`](https://github.com/antirez/dump1090/blob/master/tools/debug.html) (debug.html)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_rtl["RTLSDR<br/>hardware input"]
  node_ifile["IQ file/stdin<br/>sample input"]
  node_net_in["Raw ingest<br/>network input"]
end

subgraph group_core["Decoder core"]
  node_dump1090["dump1090.c<br/>main decoder<br/>[dump1090.c]"]
  node_sample_rx["Sample Rx<br/>2 MHz IQ pipeline"]
  node_detect{{"Packet detect<br/>demodulator"}}
  node_repair{{"CRC repair<br/>error handling"}}
  node_decode["Message decode<br/>DF decoder"]
  node_aircraft[("Aircraft table<br/>state store")]
  node_track["Track/CPR<br/>tracking"]
  node_refpos(("Reference avg<br/>position reference"))
end

subgraph group_outputs["Outputs"]
  node_stdout["Stdout<br/>cli output"]
  node_interactive["Terminal UI<br/>live display"]
  node_sbs["SBS TCP<br/>protocol output"]
  node_raw_out["Raw stream<br/>protocol output"]
  node_httpd["HTTP server<br/>embedded server"]
end

subgraph group_assets["Assets"]
  node_gmap["gmap.html<br/>web map UI<br/>[gmap.html]"]
  node_debugui["debug.html<br/>debug UI<br/>[debug.html]"]
end

subgraph group_support["Support"]
  node_anet["anet.c/h<br/>socket helper<br/>[anet.c]"]
  node_makefile["Makefile<br/>build"]
end

node_rtl -->|"IQ samples"| node_sample_rx
node_ifile -->|"file/stdin"| node_sample_rx
node_net_in -->|"raw frames"| node_decode
node_sample_rx -->|"stream"| node_detect
node_detect -->|"candidate packets"| node_repair
node_repair -->|"messages"| node_decode
node_decode -->|"updates"| node_aircraft
node_aircraft -->|"state"| node_track
node_aircraft -->|"airborne fixes"| node_refpos
node_refpos -->|"surface reference"| node_track
node_dump1090 -->|"controls"| node_rtl
node_dump1090 -->|"selects"| node_ifile
node_dump1090 -->|"listens"| node_net_in
node_dump1090 -->|"prints"| node_stdout
node_dump1090 -->|"renders"| node_interactive
node_dump1090 -->|"serves"| node_sbs
node_dump1090 -->|"streams"| node_raw_out
node_dump1090 -->|"hosts"| node_httpd
node_dump1090 -->|"reads state"| node_aircraft
node_httpd -->|"serves page"| node_gmap
node_httpd -->|"serves page"| node_debugui
node_httpd -->|"JSON/data"| node_aircraft
node_dump1090 -->|"uses"| node_anet
node_httpd -->|"sockets"| node_anet
node_sbs -->|"sockets"| node_anet
node_raw_out -->|"sockets"| node_anet
node_dump1090 -->|"built by"| node_makefile

click node_dump1090 "https://github.com/antirez/dump1090/blob/master/dump1090.c"
click node_gmap "https://github.com/antirez/dump1090/blob/master/gmap.html"
click node_debugui "https://github.com/antirez/dump1090/blob/master/tools/debug.html"
click node_anet "https://github.com/antirez/dump1090/blob/master/anet.c"
click node_makefile "https://github.com/antirez/dump1090/tree/master/Makefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rtl,node_ifile,node_net_in toneBlue
class node_dump1090,node_sample_rx,node_detect,node_repair,node_decode,node_aircraft,node_track,node_refpos toneAmber
class node_stdout,node_interactive,node_sbs,node_raw_out,node_httpd toneMint
class node_gmap,node_debugui toneRose
class node_anet,node_makefile toneIndigo
```

## Components

### Inputs

Sample, frame, and hardware ingestion boundaries

- **RTLSDR**: hardware input · Direct radio-sample input path from SDR hardware
- **IQ file/stdin**: sample input · Offline sample-stream input used instead of hardware
- **Raw ingest**: network input · Network-fed raw Mode S frame input on the raw socket port

### Decoder core

Demodulation, message decode, and aircraft tracking

- [dump1090.c](https://github.com/antirez/dump1090/blob/master/dump1090.c): main decoder · Single-process receiver and coordinator for ingestion, decoding, state tracking, and fan-out · `dump1090.c`
- **Sample Rx**: 2 MHz IQ pipeline · Reads and buffers incoming I/Q samples before detection
- **Packet detect**: demodulator · Finds Mode S preambles and message shapes in the sample stream
- **CRC repair**: error handling · Applies CRC-based bit correction and aggressive recovery heuristics
- **Message decode**: DF decoder · Decodes Mode S downlink formats and ICAO-verified messages into aircraft fields
- **Aircraft table**: state store · In-memory table of observed aircraft and their decoded attributes
- **Track/CPR**: tracking · Computes velocity tracks and CPR position decoding, including surface position logic
- **Reference avg**: position reference · Derives a reference location by averaging successful airborne positions for surface decoding

### Outputs

Human and network fan-out channels

- **Stdout**: cli output · Raw text or hex output for command-line consumption
- **Terminal UI**: live display · Interactive aircraft list shown in the terminal
- **SBS TCP**: protocol output · BaseStation/SBS formatted output stream on TCP port 30003
- **Raw stream**: protocol output · Raw packet streaming output on TCP port 30002
- **HTTP server**: embedded server · Serves live aircraft data and coordinates the browser UI

### Assets

Embedded UI and debug pages

- [gmap.html](https://github.com/antirez/dump1090/blob/master/gmap.html): web map UI · Static browser map front end for live aircraft visualization · `gmap.html`
- [debug.html](https://github.com/antirez/dump1090/blob/master/tools/debug.html): debug UI · Visualization page for inspecting decoder packet frames · `tools/debug.html`

### Support

Build, docs, and helper code

- [anet.c/h](https://github.com/antirez/dump1090/blob/master/anet.c): socket helper · Network abstraction used by TCP server and client plumbing · `anet.c`
- [Makefile](https://github.com/antirez/dump1090/tree/master/Makefile): build · Builds the monolithic executable · `Makefile`

## Connections

- RTLSDR → Sample Rx: IQ samples · Direct hardware capture feeds the sample-processing pipeline
- IQ file/stdin → Sample Rx: file/stdin · Offline sample input replaces hardware capture
- Raw ingest → Message decode: raw frames · Network-fed raw Mode S frames can bypass RF demodulation
- Sample Rx → Packet detect: stream · Buffered I/Q samples are searched for Mode S preambles
- Packet detect → CRC repair: candidate packets · Detected packets are checked and repaired when possible
- CRC repair → Message decode: messages · Recovered packet bits are turned into structured Mode S messages
- Message decode → Aircraft table: updates · Decoded identities, altitude, velocity, and position update aircraft state
- Aircraft table → Track/CPR: state · Tracking derives motion and position from accumulated aircraft history
- Aircraft table → Reference avg: airborne fixes · Successful airborne positions contribute to the reference location
- Reference avg → Track/CPR: surface reference · Reference averaging enables surface position decoding
- dump1090.c → RTLSDR: controls · Main program manages hardware acquisition
- dump1090.c → IQ file/stdin: selects · Main program selects file/stdin input mode
- dump1090.c → Raw ingest: listens · Main program accepts raw network ingest
- dump1090.c → Stdout: prints · Main program can emit raw decoded output to stdout
- dump1090.c → Terminal UI: renders · Main program drives the live terminal list
- dump1090.c → SBS TCP: serves · Main program exposes SBS/BaseStation TCP output
- dump1090.c → Raw stream: streams · Main program exposes raw packet output
- dump1090.c → HTTP server: hosts · Main program embeds the web server when networking is enabled
- dump1090.c → Aircraft table: reads state · UI and output channels consume the current aircraft table
- HTTP server → gmap.html: serves page · The HTTP server delivers the live map front end
- HTTP server → debug.html: serves page · The HTTP server can also expose the debug visualization asset
- HTTP server → Aircraft table: JSON/data · Browser clients read live aircraft data from the server
- dump1090.c → anet.c/h: uses · Socket helper layer underpins TCP and server plumbing
- HTTP server → anet.c/h: sockets · Embedded server depends on network abstraction helpers
- SBS TCP → anet.c/h: sockets · TCP output uses the helper layer
- Raw stream → anet.c/h: sockets · Raw streaming output uses the helper layer
- dump1090.c → Makefile: built by · Makefile builds the monolithic application