libasterix API Reference Manual

Introduction

libasterix is a library for decoding and encoding data in EUROCONTROL ASTERIX (All Purpose Structured Eurocontrol Surveillance Information EXchange) format. ASTERIX is the standard protocol used in air traffic control systems for exchanging surveillance data, such as radar target reports, multilateration messages, ADS-B reports and SDPS track data.

libasterix is implemented in pure C99 and relies only on the standard C library, so it can be easily ported to desktop, server and embedded platforms.

Features

  • Decode ASTERIX data blocks into data records and data items, either with an explicitly selected UAP (ast_datablock_decode) or with an automatically detected UAP (ast_datablock_smart_decode)
  • Inspect decoded data through generic APIs: item type, size, name, human-readable summary and hexadecimal dump
  • Extract commonly used surveillance keywords (SAC/SIC, time of day, track number, Mode 3/A code, callsign, ICAO 24-bit address, position, flight level, speed, heading, vertical rate, etc.) from any data record through one uniform interface
  • Match data items, data records and data blocks by keywords
  • Modify fields of a decoded data block (e.g. SAC/SIC, time of day) and re-encode it (ast_datablock_modify)
  • Build new data blocks from scratch and encode them into ASTERIX wire format (ast_datablock_encode)
  • Disassemble data records into category-specific C structures for direct field access
  • Convert data items, data records and data blocks among different categories
  • Decode Mode S transponder BDS (Comm-B Data Selector) registers
  • Generate HTML snippets describing data records and data items

Supported Categories

libasterix supports the following categories:

  • CAT001 Monoradar Target Reports
  • CAT002 Radar Service Messages
  • CAT004 Safety Net Messages
  • CAT008 Monoradar Service Messages (obsolete)
  • CAT010 Multilateration Messages
  • CAT015 Service Messages from Monopulse SSR
  • CAT016 Service Messages from PSR
  • CAT019 MLAT Service Messages
  • CAT020 MLAT Target Reports
  • CAT021 ADS-B Messages
  • CAT023 CNS/ATM Ground Station Service Messages
  • CAT034 Monoradar Service Messages
  • CAT048 Monoradar Target Reports
  • CAT062 SDPS Track Messages
  • CAT063 SDPS Service Messages
  • CAT065 SDPS Service Messages (ASM)
  • CAT240 Video Data Messages

User Application Profiles

A User Application Profile (UAP) defines which data items are present in the data records of a category and in which order. Besides the standard UAPs defined by the EUROCONTROL specifications, libasterix ships UAP variants for widely deployed equipments and editions:

  • Standard UAP (AST_UAP_STANDARD)
  • CAT001 plot UAP
  • CAT021 version-specific UAPs (v0.23, v0.26, v2.1, v2.4)
  • Raytheon ASR-10SS proprietary UAP
  • Thales proprietary UAP
  • ManagAir proprietary UAP

Basic Concepts

libasterix models ASTERIX data with the following hierarchy, which maps directly onto the definitions of the ASTERIX specifications:

  • Data Block (ast_datablock_t): one ASTERIX frame on the wire, consisting of a one-octet category, a two-octet length and a payload of one or more data records of the same category
  • Data Record (ast_datarecord_t): a single message inside a data block; the set of data items it carries is described by its FSPEC (Field Specification)
  • Data Item (ast_dataitem_t): a typed field of a data record, identified by a data item type such as I062/080
  • Subfield: an elementary field inside a compound or repetitive data item
  • UAP (ast_uap_t): the profile used to interpret the FSPEC and to lay out the data items of a record

All decoded objects reference the original input buffer; no data is copied during decoding. Category-specific record structures (e.g. ast_datarecord_062_t) can be obtained with the disassemble function of each category for convenient field access.

Using the Library

A typical application follows these steps:

  1. Initialize the library with a license key via ast_library_init
  2. Decode received bytes with ast_datablock_decode (or ast_datablock_smart_decode when the UAP is unknown), then check the valid flag of the returned data block
  3. Iterate over the data records and their data items, and use the generic accessors (ast_dataitem_get_summary, ast_datarecord_get_keyword, ...) to read the content
  4. Optionally modify fields with ast_datablock_modify or build a new data block and serialize it with ast_datablock_encode

Library information (version, revision, build date) is available through ast_library_version and related functions.

Platforms and Compilers

libasterix is tested with the following compilers and platforms:

  • MSVC 2019 on Windows 10/11 on x86/x86_64
  • MSVC 2017 on Windows 7/8.1/10 on x86/x86_64
  • MSVC 2015 on Windows 7/8.1/10 on x86/x86_64
  • CLANG 3.2 on Mac OS X 10.8 on x86_64
  • GCC 4.8.2 on CentOS 7.0 on x86_64
  • GCC 4.6.3 on Debian 7.0 on Raspberry Pi
Warning
libasterix is still under development, and its interface may change without notification. And, the support to some categories, dataitems or subfileds are not implemented yet.

Change Log

Please refer to Change Log.

Example

An example program is included to show how to use libasterix with your application. It demonstrates the decode, match, modify and encode functions.

Please refer to example.c.

Dependencies

Please refer to Dependencies on Third Party Software.

Copyrights

libasterix is a product of SinoATC. You can contact [email protected] for more information.

Copyright 2008-2026 SinoATC