szpajder / libacars

A library for decoding various ACARS message payloads

libacars

libacars is a library for decoding ACARS message contents.

Current stable version: 2.2.0 (released August 21, 2023)

Supported message types

• FANS-1/A ADS-C (Automatic Dependent Surveillance - Contract)
• FANS-1/A CPDLC (Controller-Pilot Data Link Communications)
• MIAM (Media Independent Aircraft Messaging)
• Media Advisory (Status of data links: VDL2, HF, Satcom, VHF ACARS)
• OHMA (diagnostic messages exchanged with Boeing 737MAX aircraft)

Installation

Binary packages

64-bit Windows binary packages of stable releases are provided in the Releases section.

Unzip the archive into any directory. You should be able to run example programs directly from bin subdirectory.

Building from source

Requirements:

• c11-capable C compiler
• cmake 3.1 or later
• zlib 1.2 (optional)
• libxml2 (optional)

The project should build and run correctly on the following platforms:

• Linux i686 and x86_64 (gcc)
• MacOS (clang)
• Windows (mingw or msvc)

Installing dependencies

• libacars needs zlib for MIAM and OHMA message decompression. If zlib is not present, decompression code will be disabled and compressed messages will be left undecoded. Therefore it is recommended to install zlib development package first. On Debian/Raspbian distros it is named zlib1g-dev:

apt install zlib1g-dev

• ACARS and MIAM CORE messages sometimes contain XML documents. libacars may optionally pretty-print these documents, ie. add proper formatting and indentation. To enable this feature, you need libxml2 library:

apt install libxml2-dev

• OHMA messages contain JSON-encoded data. libacars may optionally pretty-print these messages. This feature requires Jansson library:

apt install libjansson-dev

Compiling libacars (Linux)

• Option 1: To run stable and tested code, download the latest stable release tarball from Releases section and unpack it:

unzip libacars-x.y.z.zip
cd libacars-x.y.z

• Option 2: To run the latest development code which has not yet made it into a stable release, clone the source repository and checkout the unstable branch:

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

master branch is always in sync with the latest stable release. unstable branch is where the latest cutting-edge code goes first.

• Configure the build:

mkdir build
cd build
cmake ../

• Inspect the configuration summary in the cmake output and verify if all the dependencies have been detected properly:

-- libacars configuration summary:
-- - zlib:              requested: ON, enabled: TRUE
-- - libxml2:           requested: ON, enabled: TRUE
-- - jansson:           requested: ON, enabled: TRUE

• Compile and install:

make
sudo make install
sudo ldconfig

The library will be installed to /usr/local/lib (or /usr/local/lib64). Header files will land in /usr/local/include/libacars-2/libacars.

Compiling libacars (Mac)

Install dependencies and tools with brew:

brew install cmake zlib libxml2 jansson

Then follow the above instructions for Linux. Just skip the final sudo ldconfig step.

Advanced compilation options

The following options may be used when invoking cmake:

• -DCMAKE_BUILD_TYPE=Debug - enables debugging support.

• -DCMAKE_BUILD_TYPE=Release - disables debugging support (the default).

• -DEMIT_ASN_DEBUG=ON - enables debugging output of ASN.1 decoders (very verbose). This option requires -DCMAKE_BUILD_TYPE=Debug, otherwise it will do nothing.

• -DZLIB=FALSE - forcefully disables zlib support. It will not be used even if zlib is available.

• -DLIBXML2=FALSE - disables libxml2 support.

• -DJANSSON=FALSE - disables Jansson support.

Example applications

Example apps are provided in examples subdirectory:

• decode_acars_apps - reads messages from command line or from a file and decodes all ACARS applications supported by the library.

• adsc_get_position - illustrates how to extract position-related fields from decoded ADS-C message.

• cpdlc_get_position - illustrates how to extract position-related fields from CPDLC position reports.

Apps will be compiled together with the library. make install installs them to /usr/local/bin. Run each program with -h option for usage instructions.

API documentation

Refer to the following documents:

• doc/PROG_GUIDE.md - libacars Programmer's Guide
• doc/API_REFERENCE.md - libacars API Reference

Applications using libacars

• dumpvdl2, a VDL-2 decoder
• vdlm2dec, a VDL-2 decoder
• acarsdec, an ACARS decoder
• JAERO, a Satcom ACARS decoder

Credits and thanks

I hereby express my gratitude to everybody who helped with the development and testing of libacars. Special thanks go to:

• Fabrice Crohas
• Dick van Noort
• acarslogger
• Michał Miszewski

Licenses

libacars, Copyright (c) 2018-2023 Tomasz Lemiech [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Contains code from the following software projects:

• Rocksoft^tm Model CRC Algorithm Table Generation Program V1.0 by Ross Williams

• asn1c, Copyright (c) 2003-2017 Lev Walkin [email protected] and contributors. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Packaged releases for Windows include zlib library in binary DLL form. zlib data compression library, (C) 1995-2017 Jean-loup Gailly and Mark Adler.

// vim: textwidth=80

libacars's Issues

where is the development package

i need the development package to compile a program and i need libacars.h

- #MD tokens

Hi,

First of all, thanks for your great work!

It seems that with the latest version(s) of libacars some messages that jaero attempts to decode are not decoded. When building and running against an older version of libacars they are correctly decoded. The messages that fail seem to be these that start with the "- #MD" token, for example this H1:

• #MD/A6 PIKCPYA.ADS.66168A07040B000C000D010E011000D9FB

When I strip off the first part of the message in jaero and pass "/PIKCPYA.ADS.66168A07040B000C000D010E011000D9FB" it works fine.
Now this is of course easy enough but since it seems this was not issue in earlier versions of libacars I just want to check with you if you think this needs to be done in jaero or if perhaps it is an issue in libacars.

Additionally, in longer messages, additional "- #MD" tokens can be found. I could only get these to decode by stripping away these tokens in jaero. Same question there I guess, should the client take care of stripping these off the message before attempting to decode?

Many thanks!

Jeroen

reassemble bug

Hi,I found a reassemble bug Under specific condition.
Here is the example log

{"timestamp":1630031299.3498211,"station_id":"test-01","channel":1,"freq":127.275,"level":-11,"error":0,"mode":"2","label":"C1","block_id":"M","ack":false,"tail":"B-xxxx","text":"msg example 1-1","end":true,"assstat":"in progress"}
{"timestamp":1630031306.879694,"station_id":"test-01","channel":1,"freq":127.275,"level":-11,"error":0,"mode":"2","label":"C1","block_id":"N","ack":false,"tail":"B-xxxx","text":"msg example 1-2","end":true,"assstat":"in progress"}
{"timestamp":1630031314.1785741,"station_id":"test-01","channel":1,"freq":127.275,"level":-11,"error":0,"mode":"2","label":"C1","block_id":"O","ack":false,"tail":"B-5528","text":"msg example 1-3","end":true,"assstat":"in progress"}
{"timestamp":1630031320.9381371,"station_id":"test-01","channel":1,"freq":127.275,"level":-11,"error":0,"mode":"2","label":"A4","block_id":"P","ack":false,"tail":"B-xxxx","text":"/WUHDCYA.FS1/FSM 0228 210827 ZXXXX\r\nCXA1111 CDA REJECTED\r\nCLEARANCE CANCELLED\r\nREVERT TO VOICE PROCEDURES\r\n1A01","assstat":"skipped"}

not msg lost, another type msg(label A4) started at block_id P after msg block_id O (label C1),but label C1 series not finished at this time, but after block_id P send will be out of sequence from reassemble

{"timestamp":1630031327.961997,"station_id":"test-01","channel":1,"freq":127.275,"level":-11,"error":0,"mode":"2","label":"C1","block_id":"Q","ack":false,"tail":"B-xxxx","text":"msg example 1-4","end":true,"assstat":"out of sequence"}

now
static uint32_t acars_key_hash(void const *key) {
acars_key *k = (acars_key *)key;
uint32_t h = la_hash_string(k->addr, LA_HASH_INIT);
h = la_hash_string(k->label, h);
h = la_hash_string(k->msn, h);
return h;
}

but I can't remove label from the code. I think maybe libacars can add another one identifies to make sure to the address msg is continuously ,not require prev_seq_num is continuously.

thanks a lot.

Archival file format ...?

As this library grows and supports more message types, it might be nice to be able to go back to archived data and re-run a decoder on previously not-decoded messages (cf your comment about being "lazy" :) about AFN messages in the closed issue). What would you think about adding an archive output format that could "save" what has been demodulated for later analysis but an as-yet-unreleased decoder?

Notes on building on a Mac ...

These are general notes that could be added to the README.md file. They assume that the command line Xcode is setup; but not much else.

The cmake command is needed.

$ brew install cmake
Updating Homebrew...
...
==> Pouring cmake--3.20.2.big_sur.bottle.tar.gz
==> Summary
🍺  /usr/local/Cellar/cmake/3.20.2: 6,468 files, 69.6MB
...
$

Then the build is easy (as per the present README.md file).

$ git clone [email protected]:szpajder/libacars.git
Cloning into 'libacars'...
...
$ cd libacars/
$ mkdir build
$ cd build/
$ cmake ../
-- The C compiler identification is AppleClang 12.0.0.12000032
...
-- Found ZLIB: /Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk/usr/lib/libz.tbd (found version "1.2.11")
-- Found LibXml2: /Library/Developer/CommandLineTools/SDKs/MacOSX11.1.sdk/usr/lib/libxml2.tbd (found version "2.9.4")
-- libacars configuration summary:
-- - zlib:              requested: ON, enabled: TRUE
-- - libxml2:           requested: ON, enabled: TRUE
-- Configuring done
-- Generating done
...
$ make
...
[100%] Built target decode_acars_apps
$

The install on a Mac does not need ldconfig. (dyld exists; but not needed).

$ sudo make install
Password: ...
...
Install the project...
...
-- Installing: /usr/local/lib/libacars-2.2.dylib
-- Installing: /usr/local/lib/libacars-2.dylib
...
$

Using the code in https://github.com/szpajder/libacars/blob/master/doc/PROG_GUIDE.md we can prove this install works.

$cat > /tmp/deacars.c 
...
^D
$ cc -o /tmp/deacars -L/usr/local/lib/ -I/usr/local/include/libacars-2 /tmp/deacars.c -lacars-2
$ /tmp/deacars
Decoded message:
ACARS:
 Reassembly: unknown
 Reg: .SP-LDE Flight: LO02DM
 Mode: 2 Label: 23 Blk id: 3 More: 0 Ack: ! Msg num: M09A
 Message:
  ONN01LO02DM/**292041ELLXEPWA20410028

$

Hope that helps. Thank you for the project.

JAERO shuts down after a couple of minutes when running with libacars 1.2.0

Hi ,just tried your latest libacars.dll (1.2.0) in latest JAERO 1.0.4.10 and using I7 win10/64bit, JAERO runs fine decoding voice but shuts down after a couple of minutes decoding data, I am recieving L-band from Alphasat . I swopped out the libacars .dll with the previous version and JAERO runs constantly with no problems apart from no MIAM decodes.......sorry ...
Cheers
Dave G7gqw

Media Advisory frame with too many available link indicators results in unterminated string

Parsing of Media Advisory frame with 10 or more available link indicators results in unterminated string available_links in la_media_adv_msg struct (missing \0). This can lead to unexpected (and potentially funny) program behavior when the string is used later in the program.

For example, in decode_acars_apps it causes reading past end of the buffer, until next null character is found (which is at the end of text string). This results in parsing the whole message as letter codes of available links and printing them as a long list.

Example that illustrates the problem:

./decode_acars_apps d SA '0EV123456VVVVVVVVVV/HERE IS THE TEXT MESSAGE THAT IS NOT A LIST OF AVAILABLE LINKS'

Support for sub label?

Some ACARS packets, specifically ones with H1 labels, should have sub labels. Add support for decoding and storing the sub label.

(See: http://www.cosmic.com.au/acarsanalyser/v3/DataRes/MsgLabelsData.asp#sublabel for examples of sub labels)

Question: do docs contain misinformation about the CRC-16 polynomial?

the docs say

The following commands enable these capabilities:
set arinc on
which applies the polynomial: x^16+x^15+x^l3+x^5+x^3+x^1+1

(which corresponds to 0xa02b without leading 1)

set International Telephone and Telegraph Consultative Committee (ccitt) on
which applies the polynomial: x^16+x^12+x^5+1

But in la_crc16_arinc in fact is

name	id	size	polynomial	init	xor_out	reflect_in	reflect_out	check_value
IBM-3740	crc16_ibm3740	16	0x1021	0xffff	0x0	0	0	0x29b1

Do the docs contain an error that has found its way into multiple tables of CRC polynomials?

undecoded messages

First thanks for this lib and your work to include it in acarsdec

I have a question:
I see in acars this kind of message:
#M1B/BA SOUCAYA.CC1.I-NDMJ60412240491075DA
That is perfectly decoded by libacars

But I see too messages that really look like FANS-1/A messagebut that are not decoded:
'#M1B/B0 SOUCAYA.AFN/FMHNOS492,.I-NDMJ,,182449/FRP0A481`

It could be normal, I don't really know ARINC 622

Shared lib calls exit

libacar call exit when compiled as shared lib. This is bad.

This library package calls exit() or _exit(), probably in a non-fork()
context. Doing so from a library is strongly discouraged - when a library
function calls exit(), it prevents the calling program from handling the
error, reporting it to the user, closing files properly, and cleaning up any
state that the program has. It is preferred for the library to return an
actual error code and let the calling program decide how to handle the
situation.

Please correct it.

Assembling of CPDLC messages

Hi,
A nice additional feature would be if libacars could automatic assemble CPDLC messages / replace the placeholders, eg.:
REQUEST DIRECT TO [position] => REQUEST DIRECT TO GAMLI

Is something like this planned?

Thanks

Buffer overflow in la_media_adv_parse()

By parsing Media Advisory frame with text message longer than 254 characters, it is possible to overflow text buffer in la_media_adv_msg leading to program crash or other insecure behavior.

The problem is caused by using strcpy() in la_media_adv_parse() without checking the size of input.

Example frame that triggers the buffer overflow:

d SA 0EV133800/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

This potentially may be exploited over radio link.

CPDLC encoding build failure

I am trying to encode an uplink UM106MaintainSpeed message using the following sample code

#include <stdint.h>
#include <string.h>
#include <math.h>
#include <libacars/asn1/FANSATCUplinkMessage.h>
#include <libacars/asn1/FANSATCUplinkMsgElementId.h>
#include <libacars/asn1/FANSATCUplinkMsgElementIdSequence.h>
#include <libacars/asn1/FANSSpeed.h>
#include <libacars/libacars.h>
#include <libacars/cpdlc.h>


void build() {
    FANSATCUplinkMessage_t um;
    um.aTCMessageheader.msgIdentificationNumber = 15;
    um.aTCMessageheader.msgReferenceNumber = NULL;
    um.aTCMessageheader.timestamp->hours = 9;
    um.aTCMessageheader.timestamp->minutes = 25;
    um.aTCMessageheader.timestamp->seconds = 35;
    um.aTCuplinkmsgelementId.present = FANSATCUplinkMsgElementId_PR_uM106Speed,
    um.aTCuplinkmsgelementId.choice.uM106Speed.present = FANSSpeed_PR_speedIndicated;
    um.aTCuplinkmsgelementId.choice.uM106Speed.choice.speedIndicated = 200;
    um.aTCuplinkmsgelementid_seqOf = NULL;

    la_proto_node *node = la_proto_node_new();
    //LA_NEW(la_cpdlc_msg, msg);
    la_cpdlc_msg msg;
    msg.data = &um;
    node->data = &msg;
    node->td = &la_DEF_cpdlc_message;
    msg.asn_type = &asn_DEF_FANSATCUplinkMessage;

    unsigned char output[50];
    uper_encode_to_buffer(&asn_DEF_FANSATCUplinkMessage, node, output, 50);
}

int main(int argc, char **argv) {
    build();
}

I added this file to the examples directory and updated the CMakeLists.txt EXAMPLE_BINARIES set

I get the following compile error when running make

MakeFiles/cpdlc_maintain_speed.dir/cpdlc_maintain_speed.c.o: In function `build':
cpdlc_maintain_speed.c:(.text+0x8a): undefined reference to `asn_DEF_FANSATCUplinkMessage'
cpdlc_maintain_speed.c:(.text+0xa4): undefined reference to `asn_DEF_FANSATCUplinkMessage'
cpdlc_maintain_speed.c:(.text+0xb0): undefined reference to `uper_encode_to_buffer'
collect2: error: ld returned 1 exit status
make[2]: *** [examples/cpdlc_maintain_speed] Error 1
make[1]: *** [examples/CMakeFiles/cpdlc_maintain_speed.dir/all] Error 2
make: *** [all] Error 2

Are there other changes needed to be made to build this code ?

Builds just fine on Raspberry Pi 3/armhf

Not an issue, just to let you know that it says in the README that it should build on both Linux i686 and x86_64 - I just built it on a Raspberry Pi 3 with both zlib and libxml2-dev, and it works perfectly :-)

Unable to use on Arch Linux Arm

pkg_check_modules(LIBACARS libacars-2>=2.0.0) not detects compiled library from stable release.