dumphfdl

dumphfdl is a multichannel HFDL (High Frequency Data Link) decoder.

HFDL (High Frequency Data Link) is a protocol used for radio communications between aircraft and a network of ground stations using high frequency (HF) radio waves. It is used to carry ACARS and AOC messages as well as CPDLC (Controller-Pilot Data Link Communications) and ADS-C (Automatic Dependent Surveillance - Contract). Thanks to the ability of short waves to propagate over long distances, HFDL is particularly useful in remote areas (eg. over oceans or polar regions) where other ground-based communications services are out of range. While many aircraft prefer satellite communications these days, HFDL is still operational and in use.

Features

• Decodes multiple channels simultaneously, up to available CPU power and SDR bandwidth (no fixed channel count limit)
• Interfaces directly with SDR hardware via SoapySDR library (no pipes / virtual audio cables needed)
• Reads prerecorded I/Q data from a file
• Automatically reassembles multiblock ACARS messages and MIAM file transfers
• Supports various outputs and output formats (see below)
• Enriches logged messages with data from external sources:
  • ground station details - from the system table file
  • aircraft data - from Basestation SQLite database
• Extracts aircraft position information from decoded messages and provides a data feed for external plane tracking apps (eg. Virtual Radar Server)
• Produces statistics using Etsy StatsD protocol
• Runs under Linux and MacOS

Supported output formats

• Human readable text
• JSON
• Basestation feed with aircraft positions

Supported output types

• file (with optional daily or hourly file rotation)
• reliable network messaging via ZeroMQ - client and server mode
• TCP connection - client mode
• UDP socket
• Apache Kafka

Example

Supported protocols and message types

• Media Protocol Data Units (MPDU)
• Link Protocol Data Units (LPDU):
  • Logon request / resume
  • Logon confirm / Resume confirm
  • Logoff request
  • Logon denied
  • Unnumbered data / Unnumbered acknowledged data
• Squitter Protocol Data Units (SPDU)
• HF Network Protocol Data Units (HFNPDU) in Direct Link Service mode:
  • System table
  • System table request
  • Performance data
  • Frequency data
  • Enveloped data
  • Delayed echo
• ACARS
• All ACARS applications and protocols supported by libacars library (full list here)

Less important fields from MPDUs (slot sel, N1, N2, H, NF, U(R), UDR), LPDUs (DDR, P) and SPDUs (slock ack codes, priority) are currently skipped over without decoding.

Unsupported protocols

• Reliable Link Service (RLS). It's not actively used.

Things TODO

• Sensitivity and decoding accuracy needs improvement - the amount of CRC errors should be lower.

• CPU usage could possibly be reduced.

Installation

Dependencies

Mandatory dependencies:

• C compiler with C11 support (gcc, clang, AppleClang)
• make
• cmake >= 3.1
• pkg-config
• glib2 >= 2.46
• libconfig++
• libacars >= 2.1.0
• liquid-dsp >= 1.3.0
• fftw3 (preferably multithreaded implementation - libfftw3f_threads)

Optional dependencies:

• SoapySDR (to use software defined radios; not needed for decoding from I/Q files)
• sqlite3 (to enrich messages with aircraft data from a basestation.sqb database)
• statsd-c-client (for Etsy StatsD statistics)
• libzmq 3.2.0 or later (for ZeroMQ networked output)
• google-perftools (for profiling)
• librdkafka 1.8.0 or later (to enable rdkafka output types)

Install necessary dependencies. Most of them are probably packaged in your Linux distribution. Example for Debian / RaspberryPi OS:

sudo apt install build-essential cmake pkg-config libglib2.0-dev libconfig++-dev libliquid-dev libfftw3-dev

Example for MacOS:

sudo brew update
sudo brew install liquid-dsp fftw soapysdr libconfig

Install libacars library:

• download the latest stable release package from here
• unpack the archive
• compile and install the library:

cd libacars-<version_number>
mkdir build
cd build
cmake ../
make
sudo make install
sudo ldconfig       # on Linux only

Refer to libacars's README.md for complete instructions and available compilation options.

SoapySDR support (optional)

While the SoapySDR library might be included in your Linux distribution, it is a good idea to use the latest available version.

Download and install the library from here. Then install the driver module for your device. Refer to SoapySDR wiki for a list of all supported modules. Once you are done, verify your installation with:

SoapySDRUtil --info

Inspect the output and verify if your driver of choice is available. Here I have four drivers: airspyhf, remote, rtlsdr, sdrplay:

######################################################
##     Soapy SDR -- the SDR abstraction library     ##
######################################################

Lib Version: v0.8.0-ga8df1c57
API Version: v0.8.0
ABI Version: v0.8
Install root: /usr/local
Search path:  /usr/local/lib/SoapySDR/modules0.8
Module found: /usr/local/lib/SoapySDR/modules0.8/libairspyhfSupport.so (0.2.0-d682533)
Module found: /usr/local/lib/SoapySDR/modules0.8/libremoteSupport.so   (0.5.2-d11da72)
Module found: /usr/local/lib/SoapySDR/modules0.8/librtlsdrSupport.so   (0.3.1-bec4f05)
Module found: /usr/local/lib/SoapySDR/modules0.8/libsdrPlaySupport.so  (0.3.0-8c4e330)
Available factories... airspyhf, remote, rtlsdr, sdrplay

Connect your radio and run:

SoapySDRUtil --probe=driver=<driver_name>

and verify if the device shows up. Example for Airspy HF+:

$ SoapySDRUtil --probe=driver=airspyhf
######################################################
##     Soapy SDR -- the SDR abstraction library     ##
######################################################

Probe device driver=airspyhf

----------------------------------------------------
-- Device identification
----------------------------------------------------
  driver=AirspyHF
  hardware=AirspyHF
  serial=****************

----------------------------------------------------
-- Peripheral summary
----------------------------------------------------
  Channels: 1 Rx, 0 Tx
  Timestamps: NO

----------------------------------------------------
-- RX Channel 0
----------------------------------------------------
  Full-duplex: NO
  Supports AGC: YES
  Stream formats: CF32, CS16, CS8, CU16, CU8
  Native format: CF32 [full-scale=1]
  Antennas: RX
  Full gain range: [0, 54] dB
    LNA gain range: [0, 6, 6] dB
    RF gain range: [-48, 0, 6] dB
  Full freq range: [0.009, 31], [60, 260] MHz
    RF freq range: [0.009, 31], [60, 260] MHz
  Sample rates: 0.768, 0.384, 0.256, 0.192 MSps

SQLite (optional)

Some HFDL messages contain ICAO 24-bit hex code of the aircraft in question. In case you use Planeplotter or Virtual Radar Server or Kinetic Basestation software, you probably have a basestation.sqb SQLite database containing aircraft data (registration numbers, aircraft types, operator, etc). dumphfdl may use this database to enrich logged messages with this data. If you want this feature, install SQLite3 library:

Linux:

sudo apt install libsqlite3-dev
sudo ldconfig

MacOS:

sudo brew install sqlite

Etsy StatsD statistics (optional)

This feature causes the program to produce various performance counters and send them to the StatsD collector.

Install statsd-c-client library:

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

ZeroMQ networked output support (optional)

ZeroMQ is a library that allows reliable messaging between applications to be set up easily. dumphfdl 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.

Linux:

sudo apt install libzmq3-dev

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

MacOS:

brew install zeromq

Apache Kafka networked output support (optional)

Apache Kafka is a populated distributed log that provides topic-based persistent/durable messages. dumphfdl can publish messages to an Apache Kafka cluster. To enable this feature, install the librdkafka library.

Linux:

sudo apt install librdkafka-dev

MacOS:

brew install librdkafka

Compiling dumphfdl

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

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

Configure the build:

mkdir build
cd build
cmake ../

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

-- dumphfdl configuration summary:
-- - SDR drivers:
--   - soapysdr:                requested: ON, enabled: TRUE
-- - Other options:
--   - Etsy StatsD:             requested: ON, enabled: TRUE
--   - SQLite:                  requested: ON, enabled: TRUE
--   - ZeroMQ:                  requested: ON, enabled: TRUE
--   - Profiling:               requested: OFF, enabled: FALSE
--   - Multithreaded FFT:       TRUE
-- Configuring done
-- Generating done

Here you can