dumpvdl2

dumpvdl2 is a VDL Mode 2 message decoder and protocol analyzer.

Current stable version: 2.6.0 (released February 7, 2026)

Features

• Runs under Linux (tested on: x86, x86-64, ARM) and MacOS (not tested very well, feedback welcome)
• Supports following SDR hardware:
  • RTLSDR (via rtl-sdr library)
  • Mirics SDR (via libmirisdr-4)
  • SDRPlay RSP (native support through official driver version 2 and 3)
  • SoapySDR (via soapy-sdr project)
  • prerecorded IQ data from a file
• Decodes multiple VDL2 channels simultaneously
• Automatically reassembles multiblock ACARS messages, MIAM file transfers, fragmented X.25, CLNP and COTP packets.
• Supports various outputs and output formats (see below)
• Enriches logged messages with ground station details read from a text file (MultiPSK format)
• Enriches logged messages with aircraft data read from Basestation SQLite database
• Supports message filtering by type or direction (uplink, downlink)
• Can store raw frames in a binary file for later decoding or archiving purposes.
• Produces decoding statistics using Etsy StatsD protocol

Supported output formats

• Human readable text
• JSON
• Single-line ACARS format accepted by Planeplotter
• Custom binary format (suitable for storing raw frames)

Supported output types

• file (with optional daily or hourly file rotation)
• reliable network messaging via ZeroMQ
• UDP socket

Example

Supported protocols

• Aviation Link Control (AVLC)
• ACARS over AVLC
• ISO 8208 / X.25 DTE-DCE Interface
• ISO 8473 / X.233 Connectionless Network Protocol (CLNP)
• ISO 8073 / X.224 Connection Oriented Transport Protocol (COTP)
• ISO 8327 / X.225 Session Protocol
• ISO 8650 / X.227 Association Control Service Element (ACSE)
• ISO 9542 End System to Intermediate System (ES-IS)
• ISO 10747 Inter-Domain Routing Protocol (IDRP)
• ATN-B1 Context Management
• ATN-B1 Controller-Pilot Data Link Communications, version 1 (CPDLC)
• ATN-B2 Automatic Dependent Surveillance - Contract, version 2 (ADS-C)
• All applications and protocols handled by libacars library (full list here)

Installation

Dependencies

Mandatory dependencies:

• gcc
• make
• cmake
• pkg-config
• git (unless you intend to use only packaged releases of dumpvdl2 and all dependencies)
• glib2
• libacars 2.1.0 or later

Optional dependencies:

• SDR device drivers:
  • librtlsdr
  • libmirisdr-4
  • SDRPlay binary driver
  • SoapySDR
• Dependencies for optional features:
  • sqlite3 (for enriching messages with aircraft data read from SQB database)
  • statsd-c-client (for Etsy StatsD statistics)
  • libprotobuf-c 1.3.0 or later (for binary format support)
  • libzmq 3.2.0 or later (for ZeroMQ networked output)

Install necessary dependencies (unless you have them already). Example for Debian / Raspbian:

sudo apt install build-essential cmake git libglib2.0-dev pkg-config

Install libacars library - either:

• download a stable release package from here
• or clone the source repository with:

cd
git clone https://github.com/szpajder/libacars
cd libacars

Compile and install the library:

mkdir build
cd build
cmake ../
make
sudo make install
sudo ldconfig

RTLSDR support (optional)

To use RTL dongles, install librtlsdr library (unless you have it already). Raspbian has a packaged version:

apt install librtlsdr-dev

If your distribution does not provide a package, then clone the source repository and compile manually:

apt install libtool autoconf libusb-1.0-0-dev
cd
git clone git://git.osmocom.org/rtl-sdr.git
cd rtl-sdr/
autoreconf -i
./configure
make
sudo make install
sudo ldconfig
sudo cp $HOME/rtl-sdr/rtl-sdr.rules /etc/udev/rules.d/rtl-sdr.rules

Mirics support (optional)

libmirisdr-4 is an open-source alternative to SDRPlay binary driver (Mirics is the chipset brand which SDRPlay RSPs are based on). However, as of December 2017, it works properly with RSP1 only. For other RSP types (RSP2, RSP/1A) gain control does not work too well, so the native closed source driver is a better option (see next section). libmirisdr-4 is a good choice for RSP1 and various Mirics-based DVB-T dongles which are detected as RSP1 device. An advantage over RSP binary API is lower CPU utilization in dumpvdl2 thanks to a lower sampling rate.

Install libmirisdr-4 library:

apt install libusb-1.0-0-dev
cd
git clone https://github.com/f4exb/libmirisdr-4.git
cd libmirisdr-4
./build.sh
cd build
sudo make install
sudo ldconfig
sudo cp $HOME/libmirisdr-4/mirisdr.rules /etc/udev/rules.d/mirisdr.rules

SDRPLAY RSP support (optional)

Download and install API/hardware driver package from here. Make sure you have selected the right hardware platform before downloading, otherwise the installer will fail. dumpvdl2 supports both version 2 and 3 of the driver. Version 3 is needed for newer devices (like RSPdx). Older hardware works with both versions. You can have both versions installed simultaneously and choose either one when running the program.

SoapySDR support (optional)

Download and install the SoapySDR library from here. Then install the driver module for your device. Refer to SoapySDR wiki for a list of all supported modules.

Note: The device must support a sampling rate of 2100000 samples per second to work correctly with dumpvdl2. It is therefore not possible to use devices which only support predefined, fixed sampling rates (notably Airspies). This limitation will be removed in a future release of dumpvdl2.

SQLite (optional)

VDL2 message addressing is based on ICAO 24-bit hex codes (same as ADS-B). dumpvdl2 may use your basestation.sqb database to enrich logged messages with aircraft data (registration number, operator, type, etc). If you want this feature, install SQLite3 library:

sudo apt install libsqlite3-dev
sudo ldconfig

Etsy StatsD statistics (optional)

Install statsd-c-client library from https://github.com/romanbsd/statsd-c-client:

cd
git clone https://github.com/romanbsd/statsd-c-client.git
cd statsd-c-client
make
sudo make install
sudo ldconfig

Binary input/output format support (optional)

dumpvdl2 can write raw AVLC frames into a binary file. Each frame is stored together with its metadata (ie. timestamp of reception, channel frequency, signal level, noise level, etc). Frames stored in such a file can be later read back and decoded as if they were just received from the air. To enable this feature, install protobuf-c library. On Debian/Rasbian Buster just do this:

sudo apt install libprotobuf-c-dev

It won't work on Debian/Raspbian versions older than Buster, since protobuf-c library shipped with these is too old.

ZeroMQ networked output support (optional)

ZeroMQ is a library that allows reliable messaging between applications to be set up easily. dumpvdl2 can publish decoded messages on a ZeroMQ socket and other apps can receive them over the network using reliable transport (TCP). To enable this feature, install libzmq library:

sudo apt install libzmq3-dev

It won't work on Debian/Raspbian versions older than Buster, since libzmq library shipped with these is too old.

Compiling dumpvdl2

• Download a stable release package from here and unpack it...
• ...or clone the repository:

cd
git clone https://github.com/szpajder/dumpvdl2.git
cd dumpvdl2

Configure the build:

mkdir build
cd build
cmake ../

cmake attempts to find all required libraries and SDR drivers. If a mandatory dependency is not installed, it will throw out an error. Missing optional dependencies cause relevant features to be disabled. At the end of the process cmake displays a short configuration summary, like this:

-- dumpvdl2 configuration summary:
-- - SDR drivers:
--   - librtsdr:                requested: ON, enabled: TRUE
--   - mirisdr:                 requested: ON, enabled: TRUE
--   - sdrplay v2:              requested: ON, enabled: TRUE
--   - sdrplay v3:              requested: ON, enabled: TRUE
--   - soapysdr:                requested: ON, enabled: TRUE
-- - Other options:
--   - Etsy StatsD:             requested: ON, enabled: TRUE
--   - SQLite:                  requested: ON, enabled: TRUE
--   - ZeroMQ:                  requested: ON, enabled: TRUE
--   - Raw frame output:        requested: ON, enabled: TRUE
-- Configuring done

Here you can verify whether all the optional components that you need were properly detected and enabled. Then compile and install the program:

make
sudo make install

The last command installs the binary named dumpvdl2 to the default bin directory (on Linux it's /usr/local/bin). To display a list of available command line options, run:

/usr/local/bin/dumpvdl2 --help

or just dumpvdl2 --help if /usr/local/bin is in your PATH.

Build options

Build options can be configured with -D option to cmake, for example:

cmake -DRTLSDR=FALSE ../

causes RTLSDR support in dumpvdl2 to be disabled. It will not be compiled in, even if librtlsdr library is installed.

Disabling optional features:

• -DRTLSDR=FALSE
• -DMIRISDR=FALSE
• -DSDRPLAY=FALSE
• -DSOAPYSDR=FALSE
• -DSQLITE=FALSE
• -DETSY_STATSD=FALSE
• -DRAW_BINARY_FORMAT=FALSE
• -DZMQ=FALSE

Setting build type:

• -DCMAKE_BUILD_TYPE=Debug - builds the program without opt