ACARS decoder
Home Page Up ACARS decoder ADS-B dump1090 AIS receiver Cross-compiling Kernel compile Monitoring NTP Wall Clock

 

Installing the multi-channel ACARS decoder

Some brief notes about getting the multi-channel ACARS decoder from Thierry Leconte working on the Raspberry Pi card PC.
 

1 - Get rtl-sdr library installed, install and test the dongle

If you don't already have a working DVB-T dongle installation working.  

(Please be careful when copying the following commands.  I usually try to double-space the parameters along the line, but when I do that for a Web page the HTML non-break-space character sometimes gets inserted, so the following are all single-spaced.  Using copy and paste should therefore work correctly, at the expense of some readability.)

sudo apt-get update
sudo apt-get install git-core
sudo apt-get install git
sudo apt-get install cmake
sudo apt-get install libusb-1.0-0-dev
git clone git://git.osmocom.org/rtl-sdr.git
cd rtl-sdr
mkdir build
cd build
cmake ../ -DINSTALL_UDEV_RULES=ON
make
sudo make install
sudo ldconfig		# Francis Breame reports that this is required
cd ~
sudo cp ./rtl-sdr/rtl-sdr.rules /etc/udev/rules.d/

Now we need to either reboot, or power-down, and plug in the dongle, and restart.

sudo reboot

Run the rtl_test:

rtl_test

But I get an error?

On versions of Raspian Linux later than 3.6.11, you may get an error message at this point:

Found 1 device(s):
0: Generic RTL2832U

Using device 0: Generic RTL2832U

Kernel driver is active, or device is claimed by second instance of librtlsdr.
In the first case, please either detach or blacklist the kernel module
(dvb_usb_rtl28xxu), or enable automatic detaching at compile time.

usb_claim_interface error -6
Failed to open rtlsdr device #0.

This is because a DVB driver was added to the OS so that, er, TV could be received! This interferes with the operation of the DVB-T stick for ADS-B reception, so you need to take the steps outlined here before continuing. Re-run the test:

rtl_test

 

2 - Downloading and compiling the multi-channel ACARS decoder

Updated 2017-Mar-24 thanks to Dick from The Netherlands.  The project has moved from SourceForge to github, hence a substantial change in the instructions for downloading is required.

Make a directory for the ACARS stuff, and change to that directory:

cd ~
mkdir acars
cd acars

The current version is 3.4 and can be found here  https://github.com/TLeconte/acarsdec.  There may be a later version available so it might be worth to check this project on a regular basis.

If you have an older version of acarsdec installed in a directory called “acarsdec” then you first have to remove or (preferably) rename that directory.  To rename the old version to one with (preferably) a version number use this command:

mv acarsdec/ acarsdec-3.4

Now copy/clone the project with this command:

git clone https://github.com/TLeconte/acarsdec.git

Because the source is cloned to your RPI, a new directory named “acarsdec” will be created at the point where you issue the “git clone” command.  So if you run the “git clone” command after the “cd acars” above, you will get a directory acarsdec in the acars directory which now contains the source of the project.

Now change to that directory, run "make" to compile the program, and see what libraries (if any) are missing:

cd acarsdec
make

If you get an error like "No such file or directory" referring to a file sndfile.h or alsa/asoundlib.h, you may then need to update your installation with the commands below, and run the make command once again:

sudo apt-get install libsndfile1-dev
sudo apt-get install libasound2-dev
sudo apt-get install librtlsdr

although if you have also made dump1090 earlier on the same Raspberry Pi, it may have triggered all or parts of that requirement.

Francis Breame notes: However, the last one (sudo apt-get install librtlsdr) gave 'unable to locate package'.  It was fixed by the 
"sudo ldconfig" during rtl installation mentioned above.

 

3 - Running the decoder

You might like to create a simple command to run the decoder, and specify the frequencies you want to use.  Use nano to create a file (e.g. run-acars) containing the one line:

./acarsdec -p -8 -r 0 131.525 131.550 131.725 131.825

Use the ppm correction for your dongle after the "-p" - it's shown as "-8" in this example.  If you are unsure, use "0", but do try to use another program to determine what the value should be. Actually, the output from the program doesn't show a different frequency whatever value for "-p" is used.  Make that file executable:

chmod +x run-acars

and run the command-file:

./run-acars
 

Notes

  • The frequencies are suggested for the UK, in Europe or other parts of the world other frequencies may produce more messages.  Thanks to Jon for those suggestions.
     
  • The maximum frequency spread is 1 MHz.
     
  • You can enter the PPM value for your particular dongle using the -p parameter.
     
  • You can get a very good estimate of the PPM for your dongle using the "kalibrate" program.
     
  • It would be a help if there were an indication of tuning accuracy, so the the PPM value could be set without needing another program.
     
  • If your OS is greater than 3.6.11 (uname -a to check), there may be a conflict between the OS installing drivers for the DVB-T stick and the drivers required for operation as an SDR.  If you see a conflict, check here for a solution.
     

Using Kalibrate

Francis Breame notes: I'm sure that you're aware of it, but I'd just mention that for frequency offset, I found the kalibrate program very handy, which uses GSM reception to determine the offset.  In case you think it worth referring to, the instructions are:

mkdir ~/kal
cd ~/kal
sudo apt-get install libtool autoconf automake libfftw3-dev
git clone https://github.com/asdil12/kalibrate-rtl.git
cd kalibrate-rtl
git checkout arm_memory		# Essential for the Raspberry Pi
./bootstrap
./configure
make
sudo make install

Both runs can take some time, so be patient!  You can add -v (verbose) to give an indication that things are happening.

First scan for local channel numbers:

kal -s GSM900 -d 0 -g 40

You should see something like this, but your frequencies and powers will be different, of course:

Using device 0: Generic RTL2832U
Found Elonics E4000 tuner
Exact sample rate is: 270833.002142 Hz
Setting gain: 40.0 dB
kal: Scanning for GSM-900 base stations.
GSM-900:
        chan: 29 (940.8MHz + 33.774kHz) power: 866917.42
        chan: 34 (941.8MHz + 33.892kHz) power: 2521756.20
        chan: 45 (944.0MHz + 568Hz)     power: 941020.93
        chan: 88 (952.6MHz + 35.252kHz) power: 2002022.17

Pick two or more with the highest powers, do multiple runs to calculate the frequency offsets, and take the integer average:

kal -c <channel> -d 0 -g 40

You should see:

kal: Calculating clock frequency offset.
Using GSM-900 channel 34 (941.8MHz)
average         [min, max]      (range, stddev)
+ 34.098kHz     [34053, 34141]  (88, 22.927330)
overruns: 0
not found: 55
average absolute error: -36.205 ppm

You need to take the opposite sign of the absolute error when passing it to acarsdec (you are offsetting the error) - I think!  So use "-p 36" in this case.

Kalibrate on Windows

It seems that on Windows you may need to make an initial estimate of the PPM error from the first step, so that the commands become:

C:\Tools\SDR\kalibrate-win-release>kal -g 42 -s 900
Found 1 device(s):
  0:  ezcap USB 2.0 DVB-T/DAB/FM dongle

Using device 0: ezcap USB 2.0 DVB-T/DAB/FM dongle
Found Rafael Micro R820T tuner
Exact sample rate is: 270833.002142 Hz
Setting gain: 42.0 dB
meh: Scanning for GSM-900 base stations.
GSM-900:
        chan: 19 (938.8MHz + 31.434kHz) power: 133429.06
        chan: 111 (957.2MHz + 29.672kHz)        power: 100942.26

Now make an approximate estimate of the error: -30 kHz at 945 MHz => -0.030/945 => -0.000031 => -31 ppm.  I then did a run against both of the GSM stations which had been discovered:

C:\Tools\SDR\kalibrate-win-release>kal -e -31 -c 19
Found 1 device(s):
  0:  ezcap USB 2.0 DVB-T/DAB/FM dongle

Using device 0: ezcap USB 2.0 DVB-T/DAB/FM dongle
Found Rafael Micro R820T tuner
Exact sample rate is: 270833.002142 Hz
meh: Calculating clock frequency offset.
Using GSM-900 channel 19 (938.8MHz)
average         [min, max]      (range, stddev)
-  84Hz         [-98, -68]      (30, 7.318200)
overruns: 0
not found: 0
average absolute error: -30.910 ppm

C:\Tools\SDR\kalibrate-win-release>kal -e -31 -c 111
Found 1 device(s):
  0:  ezcap USB 2.0 DVB-T/DAB/FM dongle

Using device 0: ezcap USB 2.0 DVB-T/DAB/FM dongle
Found Rafael Micro R820T tuner
Exact sample rate is: 270833.002142 Hz
meh: Calculating clock frequency offset.
Using GSM-900 channel 111 (957.2MHz)
average         [min, max]      (range, stddev)
- 1.012kHz              [-1029, -993]   (35, 9.529743)
overruns: 0
not found: 0
average absolute error: -29.943 ppm

C:\Tools\SDR\kalibrate-win-release>

So the offset value for this dongle is around -30 ppm, and the correction +30 ppm.  Getting one of the more expensive dongles with a TCXO solves the offset and initial drift problems well enough for this use!
 

The Next Steps

Having the messages decoded is all very well, but it would be great to see these messages in Plane Plotter, and with any position reports plotted.  Here's how to do this:

Feeding Plane Plotter

On the Raspberry Pi

Suppose that your Plane Plotter PC has an IP address of 192.168.0.100.  When building the command-line for the Raspberry Pi program include the string:

  -n 192.168.0.100:9742

This might make the command string like something like:

./acarsdec -v -n 192.168.0.100:9742 -p 0 -r 0 131.525 131.550 131.725 131.825

Remember to include your correct Plane Plotter PC's IP address, and the appropriate ppm correction for your own dongle.

On Plane Plotter

Be sure that in the Options, I/O settings, Input data panel, the box UDP/IP from net is checked.

That's all!  The Message View in Plane Plotter will display received ACARS messages - one per line.
 

The next steps

Ideally, rather than using the UDP protocol, it would be better to use TCP as then the receiving Raspberry Pi does not need to be on the same sub-network, and TCP is more appropriate and reliable message protocol for the relatively infrequent ACARS messages.  TCP support may also allow multiple clients getting data from the one Raspberry Pi.  Two things need to happen to make this work:

  1. The program needs to be modified to provide TCP output for Plane Plotter
     
  2. Plane Plotter needs to be updated to accept ACARS messages over TCP, just as it can do with VDL2.  It can already accept UDP messages, though, as described below.

Let's hope the folk involved can make these things happen!
 

The README

Here is the read-me for the download of version 2.3:

Acarsdec is a multi-channels acars decoder with built-in rtl_sdr front end.

Note : The 2.x version is a complete rewrite, very few code line remains from 1.x

Features :

- up to six channels decoded simultaneously
- error detection AND correction
- input from sound file (.wav) , alsa sound card or software defined radio (SRD) via a rtl dongle (http://sdr.osmocom.org/trac/wiki/rtl-sdr) 
- could send packet over UDP in planeplotter format

The multi channels decoding is particularly useful with the rtl dongle. It allows to directly listen simultaneously to 4 different frequencies , with a very low cost hardware.

Usage: acarsdec [-v] [-o lv] [-A] [-n ipaddr:port] [-l logfile] -a alsapcmdevice | -f sndfile | -r rtldevicenumber f1 [f2] [f....] 

-v : verbose
-A : don't display uplink messages (ie : only aircraft messages)

-o lv : output format : 0: no log, 1 one line by msg., 2 full (default) 
-l logfile : Append log messages to logfile (Default : stdout).
-n ipaddr:port : send acars messages to addr:port via UDP in planeplotter compatible format

-f sndfile : decode from sound file (ie: a .wav file)

-a alsapcmdevice : decode from soundcard input alsapcmdevice (ie: hw:0,0)

-r rtldevicenumber f1 [f2] [f...] : decode from rtl dongle number "rtldevicenumber" receiving at VHF frequencies "f1" and optionaly "f2" to "f6" in Mhz (ie : -r 0 131.525 131.725 131.825 ). Frequencies must be in the same Megahertz.
-g gain : set rtl preamp gain in tenth of db (ie -g 90 for +9db). By default use maximum gain
-p ppm : set rtl ppm frequency correction



Examples :

Decoding from multichannel wav file :
acarsdec -f test.wav 

Decoding from sound card with short output :
acarsdec -o1 -a hw:0,0

Decoding from rtl dongle number 0 on 3 frequencies , sending aircraft messages only to 192.168.1.1 on port 9742
and no other loging :
acarsdec -A -n 192.168.1.1:9742 -o0 -r 0 131.525 131.725 131.825


Compilation :
acarsdec must compile directly on any modern Linux distrib.
It has been tested on x86_64 with fedora 19 and on RaspberryPI (only rtl source tested)

It depends of 3 external libraries :
- libsndfile for sound file input (rpm package libsndfile-devel on fedora)
- libasound for sound card input (rpm package alsa-lib-devel on fedora)
- librtlsdr for software radio rtl dongle input (http://sdr.osmocom.org/trac/wiki/rtl-sdr)

If you don't have or don't need one of these libs, edit CFLAGS and LDFLAGS in Makefile.
Ie for rtl decoding only :
CFLAGS= -Ofast -ftree-vectorize -funroll-loops -D WITH_RTL -pthread
LDLIBS= -lm -pthread -lrtlsdr


Testing :
acarsdec-2.2.tar include a test.wav file. It's a 4 channels audio file that contains 7 acars messages.

./acarsdec -o1 -f test.wav
#2 .PH-BXR KL1681 5V S53A 
#4 .LN-DYY DY083J Q0 S46A 
#2 .LN-DYY DY083J Q0 S47A 
#1 .F-GTAE AF7728 H1 D65C 
#1 .LN-DYY _d S53A 
#3 .G-DBCK BA031T _d S64A 
#3 .G-DBCK BA031T Q0 S63A 

.. and here's the program's own help for version 2.3 (yes, it says 2.2 in the output!):

Need at least one of -a|-f|-r options
Acarsdec 2.2 Copyright (c) 2014 Thierry Leconte

Usage: acarsdec [-v] [-o lv] [-A] [-n ipaddr:port] [-l logfile] -a alsapcmdevice | -f sndfile | [-g gain] [-p ppm] -r rtldevicenumber f1 [f2] ... [f6]

-v : verbose
-A : don't display uplink messages (ie : only aircraft messages)

-o lv : output format : 0: no log, 1 one line by msg., 2 full (default)
-l logfile : Append log messages to logfile (Default : stdout).
-n ipaddr:port : send acars messages to addr:port on UDP in planeplotter compatible format

-f sndfile : decode from sound file (ie: a .wav file)
-a alsapcmdevice : decode from soundcard input alsapcmdevice (ie: hw:0,0)
-r rtldevicenumber f1 [f2] ... [f6] : decode from rtl dongle number rtldevicenumber receiving at VHF frequencies f1 and optionaly f2 to f6 in Mhz (ie : -r 0 131.525 131.725 131.825 )
-g gain : set rtl preamp gain in tenth of db (ie -g 90 for +9db). By default use AGC
-p ppm : set rtl ppm frequency correction

For any input source , up to 4 channels could be simultanously decoded

Good luck!
 

Using other operating systems

It may be possible to run this code on other variants of Linux.  Please note:

- a USB 2.0 hi-speed port is required.  USB 1.1 is not fast enough.

 
Copyright © David Taylor, Edinburgh   Last modified: 2017 Mar 24 at 16:15