fredclausen/acarshub

Docker container to view and also stream ACARS messages to ACARS.io/Airframes.io.

Uses libacars, the airframe's fork of acarsdec and dumpvdl2 for SDR side of decoding.

Also, we make extensive use of the airframes work to make the messages more 'human-readable' as well as provide more detail for each of the messages.

Builds and runs on amd64, arm64, arm/v7, arm/v6 and 386 architectures.

IMPORTANT NOTE FOR RASPBERRY PI OS 32 BIT USERS

After March 1st, 2022 32 bit Rasperry Pi OS machines may not run ACARS Hub properly. I will be updating the base image of the container to Debian Bullseye and this will cause ACARS Hub to cease working if you are not prepared. Please see this for instructions on how to fix.

Supported tags and respective Dockerfiles

• latest (master branch, Dockerfile)
• Version and architecture specific tags available

Thanks

Thanks to mikenye for his excellent ADSB docker containers from which I shamelessly copied a lot of the ideas for setting up the docker container, as well as his excellent work to move this project from its humble beginnings to what it is now.

Additional thanks goes to the folks over at airframes.io for their tireless work in figuring out what all of these ACARS messages mean and making their work available in usable packages.

I am missing a boat load of people who have provided feed back as this project has progressed, as well as contributed ideas or let me bounce thoughts off of them. You've all molded this project and made it better than I could have done on my own.

Required hardware

You will need an RTLSDR dongle, and if you want to feed both VDLM2 and ACARS you will need two dongles with unique serial numbers.

Up-and-Running with docker run

docker volume create acarshub &&
docker run \
 -d \
 --rm \
 --name acarshub \
 -p 80:80 \
 -e STATION_ID_ACARS="YOURIDHERE" \
 -e FREQS_ACARS="130.025;130.450;131.125;131.550" \
 -e ENABLE_ACARS="true" \
 -v acars_data:/run/acars \
 --device /dev/bus/usb:/dev/bus/usb \
 --mount type=tmpfs,destination=/database,tmpfs-mode=1777 \
fredclausen/acarshub

You should obviously replace STATION_ID_ACARS with a unique ID for your station, as well as frequencies appropriate to your region.

Up-and-Running with Docker Compose

version: '3.8'

volumes:
  acars_data:

services:
  acarshub:
    image: fredclausen/acarshub
    tty: true
    container_name: acarshub
    restart: always
    devices:
      - /dev/bus/usb:/dev/bus/usb
    ports:
      - 80:80
    environment:
      - STATION_ID_ACARS=YOURIDHERE
      - FREQS_ACARS=130.025;130.450;131.125;131.550
      - ENABLE_ACARS=true
    volumes:
      - acars_data:/run/acars
    tmpfs:
      - /database:exec,size=64M

Please keep in mind that this is a barebones configuration to get you started. You will certainly need to set additional configuration options to get ACARS Hub working in the way you want.

Ports

Volumes / Database

It is recommended to give the container a volume so that database and message data is persisted between container restarts/upgrade. If you wish to persist this database between container restarts, mount a volume to /run/acars/.

The database is used on the website for various functions. It is automatically pruned of data older than 7 days old.

The reality of running any kind of database on a Pi is that database performance can be lacking. I have found that a database that has seven days worth of data, on a moderately busy site like mine, can reach file sizes of 17Mb and have 112,000+ rows of data. In other words, an awful lot of data, and with database sizes that large you will see a degradation in search performance. Queries might take a few seconds to execute after you type your search terms on the search page.

If you set DB_SAVEALL to a blank value you will gain back a lot of performance because messages with no informational value won't be stored. The trade-off in disabling saving all messages means you won't have all messages logged which may or may not be important to you.

It is also recommended you use a tmpfs mount to reduce SD card writes.

Environment variables

There are quite a few configuration options this container can accept.

General

Please note that for TAR1090_URL the required format is http[s]://**HOSTNAME** only. So if your tar1090 instance is at IP address 192.168.31.10 with no SSL, the TAR1090_URL would look like http://192.168.31.10

ADSB

The ACARS Hub website contains the ability to display ADSB targets along side ACARS messages. To enable this feature you need to have an available aircraft.json file generated from readsb and available on tar1090webserverurl/data/aircraft.json. Mike Nye's tar1090 is the recommended container to run to easily get this data. By turning this on you will get a map that shows the ADSB targets picked up by your readsb instance and enable you to click on planes to see what messages they've sent.

The following options will set the options for ADSB

If you run Mike's tar1090 container on the same machine as ACARS Hub then the default value for ADSB_URL is fine. If you don't, the formatting for ADSB_URL should be the full URL path to aircraft.json from your readsb source.

If you desire enhanced ADSB and ACARS message matching and thus show coloured aircraft icons on Live Map, and are running Mike's tar1090 container, you can enable the following option:

- TAR1090_ENABLE_AC_DB=true

In the configuration options for tar1090. Setting this will include additional aircraft information in the aircraft.json file that is not normally part of the ADSB broadcast, such as the aircraft's tail number and aircraft type. Please enable this with caution: there is increased memory usage in the tar1090 container so RAM constrained systems should be cautious enabling this.

ACARS

VDLM2

• If you were previously running ACARS Hub and the vdlm2dec decoder you may see a "drop" in message rate in your stats. This is normal and is a result of vdlm2dec not doing any filtering and dumpvdl2 doing filtering. If you disable the filter you will see an increase in SD card writes so use with caution.

RTL Device assignment

You have two options that can be used interchangeably to assign RTLSDR devices in the container. The first method is most likely what most users will want

Method 1: Auto-assignment of SDRs

The container will auto-assign frequencies to an SDR based on the number of available SDRs and what decoder you've set up for that frequency. You can use both Method 1 and Method 2 to assign SDRs in the container, but ensure the serials used in one method are not used in the other.

Example: SERIAL=00012507,2,-10,160;00012095,0,280,160

Method 2: Assign Specific Frequencies to a Specific SDR

If you wish to not have frequencies auto-assigned use this method. You can use both Method 1 and Method 2 to assign SDRs in the container, but ensure the serials used in one method are not used in the other. For each SDR you want to specify the frequency assignment/decoder, use one value from each of the following tables:

For frequency assignment, use the following:

Configuring the SDR options

To format the SDR configuration correctly, the container expects the following options:

• SDR serial
• PPM correction
• Gain (see below for options there)
• RTL Multiplier - for setting the bandwidth, used by ACARS only

If you don't wish to set the value for a certain option, you can skip it by leaving it blank

So if your serial for the SDR was 00012095, you had no PPM correction, and a gain of 28.0 and wanted to use the default RTL Multiplier: SERIAL=00012095,,28.0,

If you have more than one SDR being auto-assigned (NOT APPLICABLE to Method 2 above), separate each SDR with a ;

Example: SERIAL=00012095,,28.0,;00012507,2,A460

• The ACARS Decoder supports AGC/Automatic Gain Control. To enable, prepend the gain value with an A. Additionally, you will need to set the gain value for VDLM. See below.
• If you are not using ACG and wish to set the gain manually, use dBm format: 28.0
• If you are using Auto-Assignment of the SDRs and wish to use ACG if the decoder is being used for ACARS, but want a specific value for VDLM, pre-pend the value with an A: A46.0
• For the sample rate, use 192 for 2.4 MS/s and 160 for 2.0MS/s (default)

Viewing the messages

The container implements a basic web interface, listening on port 80, which will show messages as they are received.

If QUIET_LOGS is disabled, received messages are also logged to the container log.

Which frequencies should you monitor?

The ACARS.io/Airframes.io website has a great list of community derived frequencies that aircraft typically will broadcast ACARS/VDLM on, and what regions those are applicable to. The values provided in the example docker-compose/docker run example above are frequencies I have found to be good in the United States, with a decent level of traffic. I imagine the list is not complete, and could be refined better.

Some notes about frequencies:

• acarsdec and dumpvdl2 are limited to monitoring 8 frequencies apiece
• The spread of frequencies for each decoder has to be within 2 Mhz.

Logging

• All processes are logged to the container's stdout. If QUIET_LOGS is disabled, all received aircraft messages are logged to the container log as well. General logging can be viewed with docker logs [-f] container.

A note about data sources used for the web site

A brief primer on some terms:

• All ACARS/VDLM broadcasts that have a callsign appended to the message will use a two letter airline code

• IATA is a two letter airline identification code. Many airlines don't actually have an IATA code and use their own internal code.

• ICAO is an international standard, unique-across-the-world three letter airline code.

In order to make the website more usable, I have included a database used by the container to convert the two airline codes used in the messages from IATA to ICAO codes, and to show their long-form name. This data was found from public, free sources. The data had some errors in it, some of which was due to the age of the data, and some of it is due to airlines not always using the correct IATA codes in their broadcoast messages.

My observations are US centric, but from what I have seen there are "errors" you might notice in the converted callsigns.

• US Airlines that have acquired airlines as part of mergers (for instance, American Airlines/AA/AAL, who has, among others, merged with America West/US/AWE) would show up as their legacy callsign if the aircraft being picked up was part of the airline that was merged in to the bigger airline. I've selectively fixed some of these errors because the IATA code of the legacy airline was not in use by anyone else.

• Some airlines (UPS and FedEx, particularlly, among others) don't use their designated IATA callsigns period, or seem to be using contracted planes which are using an alternative two letter airline code in their message.

• There are three IATA code regions that cover the world. If an airline flies only in one region, and another flies in a separate region, those airlines are allowed to use the same IATA code. The airline code generated from the database might use the wrong IATA code because of this.

So what this means is you will occasionally see callsigns on the web front end that are wrong. The above mentioned UPS will show up BHSxxxx/BahamasAir which is obviously not right, at least for my part of the world. I am hesitant to "fix" too many of these "errors" in the database because this container is being used all around the world.

The end result of this is that in messages where the airline code is improperly mapped the Flight Aware link generated will lead to the wrong flight. The TAIL link generated should be correct.

The Fix

If you add in the ENV variable IATA_OVERRIDE you can change your local web site to display the correct airline for your region.

Formatting is as follows: IATA|ICAO|Airline Name

If you have multiple airlines you wish to override, you add in a ; between them, such as the following: UP|UPS|United Parcel Service;US|AAL|American Airlines

For anyone in the US, I suggest adding IATA_OVERRIDE=UP|UPS|United Parcel Service to start out with.

If there are airlines you notice that are wrong because the data used is wrong (IATA codes do change over time as airlines come and go), or airlines that are missing from the database that do have an IATA code, submit a PR above and I'll get it in there!

Accessing ACARS/VDLM data with external programs

If you wish to access the JSON data that the decoders acarsdec and dumpvdl2 generate with an external program, such as FlightAirMap or Plane Plotter, expose the following ports in your docker-compose configuration:

• Port 80 for the web site
• Port 14444 for TCP VDLM2 Plane Plotter
• Port 15555 for UDP VDLM2 JSON
• Port 15550 for UDP ACARS JSON

Note about Plane Plotter export format

This is currently untested in those programs, so specific set up instructions for those programs are not available. If this format does not work (ie, it needs ACARS Hub to connect to it rather that it connect to ACARS Hub) please open an issue and let me know.

Additionally this format does not export ACARS at all and only supports VDLM2.

YAML Configuration for Ports

    ports:
      - 80:80
      - 15550:15550
      - 15555:15555
      - 14444:14444

And then you will be able to connect to yourpisipaddress:15555, yourpisipaddress:15550, or youripaddress:14444 respectively, in whatever program can decode ACARS/VDLM JSON.

Website tips and tricks

• On the Live Message page pressing the p key on your keyboard will pause the message updates so you can catch up. Pressing p again will cause the page to refresh again and display messages as they come in.
• On the search page enter your search terms and then press enter to start the search.

Future improvements

ACARS decoding appears to be in active development, and as such, I expect a lot of movement in data-visualization and presentation to happen. This container will follow those developments and add in functionality as it appears.

Getting Help

You can log an issue on the project's GitHub or visit the discord server.