Dump1090

A simple ADS-B (Automatic Dependent Surveillance - Broadcast) receiver, decoder and web-server.<nl> It requires a RTL-SDR USB-stick (the librtlsdr interface is built-in).

This Mode S decoder is based on the original Dump1090 by Salvatore Sanfilippo which is here.<nl> Most of the text below is written by him. In this README.md file, I've mostly fixed the MarkDown and added some more references and screen-shots. But in the source-code I've done a lot of changes.

ADS-B basics:

• A YouTube video explaining it's basics and motivation.
• A detailed technical description by professor Junzi Sun.
• Or as a PDF in this repo.

The main features of Dump1090 are:

• Robust decoding of weak messages, with Dump1090 many users observed improved range compared to other popular decoders.
• Network support: TCP port 30003 stream (MSG5 ...), Raw packets and HTTP.
• An embedded Mongoose HTTP server that displays the currently detected aircrafts on an OpenStreet Map.<nl> Hopefully WebSocket support is coming soon (JScript and Json transfer is rather chatty).
• Decoders for 2.0 MS/s, 2.4 MS/s (default) and 8 MS/s are built-in. 8 MS/s is for SDRPlay only.
• Single and two bit errors correction using the 24 bit CRC.
• Ability to decode DF11, DF17 messages (Downlink Format).
• Ability to decode formats like DF0, DF4, DF5, DF16, DF20 and DF21 where the checksum is XORed with the ICAO address by brute forcing the checksum field using recently seen ICAO addresses.
• Decode raw IQ samples from file (using the --infile bin-file command line option).
• Decode CSV data from file (using the --infile csv-file command line option).
• Interactive command-line-interface mode where aircrafts currently detected are shown as a list refreshing as more data arrives. Planes that haven't been seen last 60 seconds are removed from the list (key/value interactive-ttl = sec to change).
• In --interactive mode, the planes entering or leaving can be spoken out using SAPI5.<nl> Ref. speech-enable = true in the config-file.
• CPR (Compact Position Reporting) coordinates decoding and track calculation from velocity.
• TCP server streaming and receiving raw data to/from connected clients <nl> (options --net or --net-only).
• Many command-line options are now in the dump1090.cfg file. See below.

Building

This project can be built in 3 ways; using CMake, GNU-make or MSBuild / Visual-Studio. The shell could not matter; CMD, TakeCommand, Cmder or PowerShell should work. <br> Assuming you have downloaded (or git clone-d) this package to c:\dev\Dump1090, then cd c:\dev\Dump1090\src.

Building with CMake:

• CMake >= 3.24 is required.
• Visual Studio 2022 (or newer) with C++ workload is required.
• Steps:
  • Create a build directory and configure the project using CMake:

    mkdir build
    cd build
    cmake .. -G "Visual Studio 17 2022" -A x64
    

  • Build it:

    cmake --build . --config Release
    

  • After building, the executable will be placed in the parent directory:

    c:\dev\Dump1090\dump1090.exe
    

Building with GNU-Make:

• c:\dev\Dump1090\src> make -f Makefile.Windows CC=cl (or CC=clang-cl).
• or for MinGW-w64, type:
• c:\dev\Dump1090\src> make -f Makefile.MinGW.

Building with Visual Studio tools:

• c:\dev\Dump1090\src> msbuild -p:Configuration=Release -p:Platform="x86" Dump1090.sln.
• or start the Visual Studio IDE, open Dump1090.sln, right-click and Build Solution. <nl> The project may have to be retargeted. Devenv would do this automatically and print <nl> Configuration 'Release|x64': changing Platform Toolset to 'v143' (was 'v142') when finished.

[!TIP] Before running dump1090.exe for the first time, please run setup.exe to properly set up geolocation. <br> To rebuild it, do cd tools, and run .\generate-setupfile.bat (ensure Rust is installed)

Normal usage

Since the uncompressed aircraft-database.csv file is too big to be allowed here on Github, it will automatically be downloaded and unzipped from OpenSky. On first run of dump1090.exe, this will print:

 Force updating 'c:\dev\Dump1090\aircraft-database.csv' since it does not exist.
 Force updating 'c:\temp\dump1090\aircraft-database-temp.zip' from 'https://opensky-network.org/datasets/metadata/aircraftDatabase.zip'
 Got 24162 kB.
 Copied 'c:\temp\dump1090\aircraft-database-temp.csv' -> 'c:\dev\Dump1090\aircraft-database.csv'
 Deleting 'c:\dev\Dump1090\aircraft-database.csv.sqlite' to force a rebuild in 'aircraft_CSV_load()'
 using Sqlite file: "c:\dev\Dump1090\aircraft-database.csv.sqlite".
 Loading 'c:\dev\Dump1090\aircraft-database.csv' could take some time.
 Creating SQL-database 'c:\dev\Dump1090\aircraft-database.csv.sqlite'... 518999
 Created 519998 records

To capture traffic directly from your RTL-SDR device and show the captured traffic on standard output, just run the program without options at all:

c:\dev\Dump1090> dump1090

To use a SDRplay device, the option --device must be used. Like:

c:\dev\Dump1090> dump1090 --device sdrplay0

To use a remote RTLTCP device (defaults to port 1234), use:

c:\dev\Dump1090> dump1090 --device tcp://host1

or:

c:\dev\Dump1090> dump1090 --device tcp://host2:2345

But these devices does not work correctly yet.

Example output:

Tuned to 1090.000 MHz. Gain reported by device: AUTO.
*8d479e84580fd03d66d139c1cd17;
CRC: c1cd17 (ok)
DF 17: ADS-B message.
  Capability     : 5 (Level 2+3+4 (DF0,4,5,11,20,21,24,code7 - is on airborne))
  ICAO Address   : 479e84
  Extended Squitter  Type: 11
  Extended Squitter  Sub : 0
  Extended Squitter  Name: Airborne Position (Baro Altitude)
    F flag   : even
    T flag   : non-UTC
    Altitude : 2125 feet
    Latitude : 7859 (not decoded)
    Longitude: 53561 (not decoded)
...

To only output hexadecimal messages:

c:\dev\Dump1090> dump1090 --raw

Example output:

Tuned to 1090.000 MHz. Gain reported by device: AUTO.
*8d47c1abea040830015c087c6a4b;
*8d479e84990c5607200c8319b311;
*8d479e84580fd04278cda6bd6d32;
...

To run the program in interactive mode: c:\dev\Dump1090> dump1090 --interactive

To run the program in interactive mode, with network support and connecting to your browser to http://localhost:8080, use this command:

c:\dev\Dump1090> dump1090 --interactive --net

It will present live traffic to the Web-browser:

and the Windows Legacy Console:

or with tui = curses in the dump1090.cfg file and started as c:\dev\Dump1090> dump1090 --interactive inside Windows Terminal and a suitable background image:

In this interactive mode there is a more compact output. Where the screen is refreshed up to 4 times per second displaying all the recently seen aircrafts with some additional information such as call-sign, registration-number, country, altitude, speed, heading and position. Most items are extracted from the received Mode S packets. <nl> Except for:

• Cntry (2 letter ISO3166) taken from the official range of ICAO address/country mapping.
• RSSI (logarithmic Received Signal Strength Indicator) is calculated from the 4 last messages.

If a config-setting homepos = latitude,longitude setting is defined, the distance to the place gets calculated. I.e. the Dist column above. E.g. a homepos = 60.3016821,5.3208769 for Bergen/Norway. Find your location on FreeMapTools.

Otherwise a location = true setting will try to get this position from the Windows Location API.

The program supports another Web-root implementation (than the default ./web_root/gmap.html) using the web-page = <HTML-file> key/value. Running with web-page = %~dp0\web_root-Tar1090\index.html in the dump1090.cfg file and starting:

c:\dev\Dump1090> dump1090 --interactive

will show a much more advanced Web-page thanks to Tar1090 and data from Tar1090-DB: **

Building with a packed Web-filesystem is also possible. Then all web-pages are built into a web-pages.dll file. <nl> Ref. USE_PACKED_WEB = 1 in Makefile.Windows and a web-page = web-pages.dll;N in the config-file.

The default