acars-decoding-library/API Manual.md at main · ibosoftnet/acars-decoding-library

Ibosoft ACARS Decoder API Manual

Overview

This library provides a shared ACARS decoder for JavaScript and Python using a common spec file: ibosoft-acars-spec.json.

Function

Name: iboDecodeAcarsMsg
Signature: iboDecodeAcarsMsg(Direction, Label, Message)
Returns:
- invalid-label: If Label is not supported by the spec or not ASCII.
- invalid-data: If data is invalid (out of bounds length, non-ASCII message, missing/invalid spec).
- Decoded output: Message Format: [Name] Decode: [Lines...]

Label and Message must be ASCII. Direction must be one of: up (uplink), dn (downlink). If a specific field fails validation, that line is output as [INVALID DATA]. If a field has a fixed table (e.g., alternate service flags), unknown values output [INVALID DATA].

Spec File

The spec file is mandatory and must be available as ibosoft-acars-spec.json in the same folder as the library. Formats are split into uplink-formats and downlink-formats.

Label List File

A required label-list.csv file provides metadata about supported ACARS labels. This file contains label names and is used by the decoder to provide human-readable message format names.

CSV Format:

direction: Message direction (up = uplink, dn = downlink)
label: Label code (case-sensitive, preserves special characters like :;, :}, _d, etc.)
decodability: Decoding status of the label
- decodable: Supported and decoded by this library
- non-decodable: Valid ACARS label but not currently decoded by this library
- reserved: Reserved for specific purposes (e.g., data loading, logbook)
- not-used: Unassigned or not-used label codes
mfi: MFI support flag (true = supports Message Function Identifier, false = does not support MFI)
name: Human-readable message name
description: Optional description field for additional notes (currently empty, reserved for manual documentation)

Example:

direction,label,decodability,mfi,name,description
up,51,decodable,false,Ground GMT Update,
dn,Q2,decodable,false,ETA Report,
up,A1,non-decodable,true,Oceanic Clearance,
up,53,reserved,false,Reserved Spare,
up,A2,not-used,true,Unassigned,

Notes:

CSV follows standard format with quoted fields containing commas or special characters
Labels are case-sensitive and preserve exact formatting (e.g., _d, _DEL, SQ, :;)
MFI flag indicates whether the label supports Message Function Identifier in the ACARS protocol
Fields with quotes in content are escaped using double quotes (e.g., """Free Text"" to ATC")
Decodability status helps identify which labels are implemented in the decoder

Config File

Optional config.json file can be placed in the same folder to control parsing behavior:

parseDownlinkSequence (default: true): Parse 4-character Downlink Message Sequence Number
parseFlightIdentifier (default: true): Parse 6-character Flight Identifier

If config.json is missing or invalid, both settings default to true. If your decoder software provides messages without sequence/flight identifier, set the corresponding config to false.

Formats

Uplink Message Formats (alphabetical)

51

Name: Ground GMT Update
Direction: Uplink
GMT Time HH:MM:SS start 0 length 6

52

Name: Ground UTC Update
Direction: Uplink
Date GG August 2025 start 0 length 6
Day Of Week start 6 length 1
UTC HH:MM:SS start 7 length 6 Year uses two digits when source year is two digits.

:;

Name: Data Transceiver Autotune
Direction: Uplink
Frequency MHz (start 0, length 6)
Seconds (start 6, length 4, optional)

RA

Name: Command/Response Uplink
Direction: Uplink
Free Text (start 0, to end)

SQ

Name: Uplink Squitter
Direction: Uplink

Version 00 fields (spec start/length are 0-based):

Version (start 0, length 2)
Datalink Service Provider (start 2, length 2)
Free Text (start 4, to end)

Version 01 fields (spec start/length are 0-based):

Version (start 0, length 2)
Datalink Service Provider (start 2, length 2)
IATA Station ID (start 4, length 3)
ICAO Station ID (start 7, length 4)
Station Number ID (start 11, length 1)
Free Text (start 12, to end)

Version 02 fields (spec start/length are 0-based):

Version (start 0, length 2)
Datalink Service Provider (start 2, length 2)
IATA Station ID (start 4, length 3)
ICAO Station ID (start 7, length 4)
Station Number ID (start 11, length 1)
Latitude (start 12, length 5)
Longitude (start 17, length 6)
Alternate Services (start 23, ends before '/')
Free Text (after '/'; optional)

SQ Datalink Service Providers

AS: Honeywell
XA: ARINC
JD: AVICOM Japan
XB: Brazil
XA: ADCC China
XS: SITA VHF
XA: AEROTHAI
TS: Test DSP

If the provider code is not listed, the decoder outputs: Other DSP Identifier (xx)

SQ Alternate Service Flags

V: VDL Mode 2 AOA Only
A: VDL Mode 2 ATN Only
B: VDL Mode 2 AOA and ATN

When alternate services are present, output lines are:

Alternate Service(s) Name:
Alternate Service(s) Freq: kHz
Ground Stations: (only if present)

Downlink Message Formats (alphabetical)

Common Downlink Message Sequence Number (first 4 characters, when parseDownlinkSequence=true in config):

Originator (character 1)
Message Number 00-99 (characters 2-3)
Block Sequence Character A-Z (character 4)

Common Flight Identifier (next 6 characters after sequence, when parseFlightIdentifier=true in config):

Flight Identifier (characters 5-10 or 1-6 depending on parseDownlinkSequence setting)

Note: Field start positions in this manual assume both sequence and flight identifier have been parsed. If config disables parsing, adjust start positions accordingly (+4 for sequence, +6 for flight identifier).

Originator codes:

C: CFDIU
D: DFDAU
F: FMC
L: CMU
M: CMU (AOC Applications)
S: System Control
O: OAT
1: Cabin Terminal 1
2: Cabin Terminal 2
3: Cabin Terminal 3
4: Cabin Terminal 4
5: User Terminal
6: User Terminal
7: User Terminal
8: User Terminal
U: User Defined
E: EICAS/ECAM/EFIS
Q: SDU
J: ATSU/ADSU
T: HF Data Radio

00

Name: Emergency Situation Report (Aircraft Hijack)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Free Text (start 0, to end; optional)

51

Name: Ground GMT Request
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes

52

Name: Ground UTC Request
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes

57

Name: Aircrew Initiated Position Report, Alternate Format
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Current Position (start 0, length 5)
Time (start 11, length 4)
Flight Level (start 15, length 3)
Next Report Point (start 18, length 5)
Time Over (start 23, length 4)
Fuel On Board (start 27, length 4)
Static Air Temp Sign (start 31, length 1)
Static Air Temp (start 32, length 2)
Wind Direction (start 34, length 3)
Wind Speed (start 37, length 3)
Sky Condition (start 40, length 8; optional)
Turbulence (start 48, length 8; optional)
Cruising Speed (start 56, length 5; optional)
Free Text (start 61, to end; optional)

5V

Name: VDL Switch Advisory
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes

HX

Name: Undelivered Uplink Report
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Additional Addresses (start 0, to '.'; optional)
Free Text (after '.'; optional)

Q0

Name: Link Test
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes

Q1

Name: Departure/Arrival Reports (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OUT Time (start 3, length 4)
OFF Time (start 7, length 4)
ON Time (start 11, length 4)
IN Time (start 15, length 4)
Fuel Quantity (start 19, length 4)
Destination Station (start 23, length 3)
Free Text (start 26, to end; optional)

Q2

Name: ETA Report
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
ETA Hours (start 3, length 2)
ETA Minutes (start 5, length 2)
Fuel Quantity (start 7, length 4)
Free Text (start 11, to end; optional)

Q3

Name: Clock Update Advisory
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Clock Time Before Reset (start 0, length 4)
Clock Time After Reset (start 4, length 4)

Q7

Name: Delay Message
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Free Text (start 0, to end; optional)

QA

Name: OUT/Fuel Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OUT Time (start 3, length 4)
Boarded Fuel (start 7, length 5)
Fuel Quantity (start 12, length 4)
Free Text (start 16, to end; optional)

QB

Name: OFF Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OFF Time (start 3, length 4)
Free Text (start 7, to end; optional)

QC

Name: ON Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
ON Time (start 3, length 4)
Free Text (start 7, to end; optional)

QD

Name: IN/Fuel Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
IN Time (start 3, length 4)
Fuel Quantity (start 7, length 4)
Captain/First Officer Identifier (start 11, length 1)
Free Text (start 12, to end; optional)

Captain/First Officer Identifier:

1: Captain Landing
2: First Officer Landing
3: Captain Take Off, First Officer Landing
4: First Officer Take Off, Captain Landing
5: Captain Take Off, Captain Landing
6: First Officer Take Off, First Officer Landing
7: Captain Take Off, Autoland
8: First Officer Take Off, Autoland

QE

Name: OUT/Fuel/Destination Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OUT Time (start 3, length 4)
Boarded Fuel (start 7, length 5)
Fuel Quantity (start 12, length 4)
Destination Station (start 16, length 3)
Free Text (start 19, to end; optional)

QF

Name: OFF/Destination Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OFF Time (start 3, length 4)
Destination Station (start 7, length 3)
Free Text (start 10, to end; optional)

QG

Name: OUT/Return IN Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OUT Time (start 3, length 4)
Return IN Time (start 7, length 4)
Free Text (start 11, to end; optional)

QH

Name: OUT Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 3)
OUT Time (start 3, length 4)
Free Text (start 7, to end; optional)

QK

Name: Landing Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
ON Time (start 3, length 4)
Departure Station (start 7, length 3)
Free Text (start 10, to end; optional)

QL

Name: Arrival Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
IN Time (start 3, length 4)
Fuel Quantity (start 7, length 4)
Captain/First Officer Identifier (start 11, length 1)
Departure Station (start 12, length 3)
Category of Landing (start 15, length 1)
Free Text (start 16, to end; optional)

QM

Name: Arrival Information Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Destination Station (start 0, length 3)
Fuel Quantity (start 3, length 4)
Departure Station (start 7, length 3)
Category of Landing (start 10, length 1)
Free Text (start 11, to end; optional)

QN

Name: Diversion Report (IATA Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Previous Destination Station (start 0, length 3)
New Destination Station (start 3, length 3)
Spacer (start 6, length 1; optional)
ETA at Diversion Station (start 7, length 4)
Fuel Quantity (start 11, length 4)
Flight Segment Originating Station (start 15, length 3)
Free Text (start 18, to end; optional)

QP

Name: Out Report (ICAO Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 4)
Destination Station (start 4, length 4)
OUT Time (start 8, length 4)
Fuel Onboard Quantity (start 12, length 4)
Boarded Fuel (start 16, length 5)
Free Text (start 21, to end; optional)

QQ

Name: OFF Report (ICAO Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 4)
Destination Station (start 4, length 4)
OFF Time (start 8, length 4)
Free Text (start 12, to end; optional)

QR

Name: ON Report (ICAO Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 4)
Destination Station (start 4, length 4)
ON Time (start 8, length 4)
Free Text (start 12, to end; optional)

QS

Name: IN Report (ICAO Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 4)
Destination Station (start 4, length 4)
IN Time (start 8, length 4)
Fuel Onboard Quantity (start 12, length 4)
Captain/First Officer Identifier (start 16, length 1)
Landing Category (start 17, length 1)
Free Text (start 18, to end; optional)

Captain/First Officer Identifier:

1: Captain Landing
2: First Officer Landing
3: Captain Take Off, First Officer Landing
4: First Officer Take Off, Captain Landing
5: Captain Take Off, Captain Landing
6: First Officer Take Off, First Officer Landing
7: Captain Take Off, Autoland
8: First Officer Take Off, Autoland

QT

Name: OUT/Return IN Report (ICAO Airport Code)
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Departure Station (start 0, length 4)
Destination Station (start 4, length 4)
OUT Time (start 8, length 4)
Return IN Time (start 12, length 4)
Fuel Onboard Quantity (start 16, length 4)
Free Text (start 20, to end; optional)

RB

Name: Command/Response Downlink
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Message Priority (start 0, length 2; optional)
IATA Address (start 2, length 7; optional)
Space (start 9, length 1; optional)
Tilde Character (start 10, length 1; optional)
RB Function Indicator (start 11, length 1; optional, values: 2, 3, or 4)
Free Text (start 12, to end; optional)

SA

Name: Media Advisory
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes
Version (start 0, length 1)
Establishment/Loss Flag (start 1, length 1)
Media Identification (start 2, length 1)
UTC Time Stamp (start 3, length 6)
Current Media Status (start 9, to '/'; optional, list of codes)
Free Text (after '/'; optional)

Establishment/Loss Flag:

E: Media Established
L: Media Lost

Media Identification:

V: VHF-ACARS
S: Default Satcom
H: HF
G: Global Star Satcom
C: ICO Satcom
2: VDL Mode 2
X: Inmarsat Aero H/H+/I/L
I: Iridium Satcom

Current Media Status lists one or more media codes; each code is mapped and joined with commas.

_d

Name: General Response
Direction: Downlink
Has Downlink Sequence: Yes
Has Flight Identifier: Yes

Note: The actual ACARS label for this message is _DEL where DEL is the ASCII DEL character (0x7F). Due to text encoding and JSON limitations, this library uses _d as a representation. When feeding messages to this decoder, use _d for _DEL messages.

FilesExpand file tree

API Manual.md

Latest commit

History