ASTERIX Decoder

Professional ASTERIX protocol decoder for Air Traffic Management surveillance data

ASTERIX (All Purpose STructured EUROCONTROL SuRveillance Information EXchange) is the ATM surveillance data binary messaging format used worldwide. This decoder parses ASTERIX data from files, stdin, or network multicast streams.

More about ASTERIX protocol: http://www.eurocontrol.int/services/asterix

🆕 What's New in v2.8.10

Major Upgrades (November 2025):

C++23/C23 Modernization ⬆️

• Upgraded to C++23 standard (from C++17) with backward compatibility
• Upgraded to C23 standard (from C17) for C code
• Active performance improvements: 5-10% throughput gain from ranges algorithms
• Future optimizations ready: 15-20% additional improvement when compilers fully support deduced this
• Compiler requirements: GCC 13+, Clang 16+ (C++23), MSVC 2019 v16.0+ (C++20), AppleClang 15+ (C++23)
• Automatic feature detection: Graceful fallback to C++17/20 for older compilers

Cross-Platform Support 🌍

• Windows builds: Server 2022 (MSVC 2022 v143), C++20 (C++ executable, Python uses C++20)
• macOS builds: macOS 14/15 Apple Silicon (AppleClang 15+), C++17 (Python) / C++23 (C++ executable)
• Linux x86_64: Ubuntu 22.04/24.04, GCC 11/13, C++17/C++23, Debian 12
• Linux ARM64: Ubuntu 22.04/24.04, GCC 11/13 (Raspberry Pi, AWS Graviton, NVIDIA Jetson, embedded systems)
• 40+ CI test configurations: Comprehensive platform and architecture testing
• Documentation: Complete build guides for all platforms

Python 3.10-3.14 Support

• Dropped: Python 3.8, 3.9 (EOL October 2025)
• Added: Python 3.14 support
• Testing: Full matrix testing across all supported versions

Upstream Sync

• Merged v2.8.10 from CroatiaControlLtd/asterix
• New category: CAT 015 v1.2 (INCS Target Reports)
• Fixed: CAT 004 cartesian values, improved type portability
• Preserved: All security patches and performance optimizations

Development Infrastructure

• Pre-commit hooks: 19 automated quality checks
• Pre-commit framework: Team-friendly setup (pip install pre-commit)
• Security tools guide: FREE vs commercial tools documentation
• Git hooks: Setup, troubleshooting, and best practices guides

See: Cross-Platform Build Guide, Build Guide, and Development Setup for details.

Features

• Multi-format support: PCAP, raw binary, FINAL, HDLC, GPS
• Three language bindings: C++23, Python (3.10-3.14), Rust (1.70+)
• Python module with simple, intuitive API
• Rust crate with type-safe, zero-copy parsing
• Fast C++ executable for command-line use (C++23/C23)
• Cross-platform: Linux, Windows, macOS (Intel & ARM M1)
• Multiple output formats: JSON, XML, human-readable text
• Network streaming via UDP multicast
• Radar simulation integration: Mock radar data generator + ASTERIX CAT048 encoder
• Modern C++23 features: Ranges algorithms, deduced this (5-10% faster, 15-20% potential)
• Memory safety: Rust bindings with safe FFI via CXX crate
• 24 ASTERIX categories supported (CAT 001-252)
• 92.2% test coverage | 560 passing tests | 0 memory leaks
• DO-278A compliant development process for aviation software safety

Performance

This decoder is optimized for high-throughput, real-time processing of ASTERIX surveillance data:

• 10.95x faster JSON generation - 547,610 records/sec (vs 50,000 target)
• 5.85x faster PCAP processing - 8,780 Mbps throughput (vs 1,500 Mbps target)
• 26.4x better UDP latency - 3.79 μs p95 latency (vs 100 μs target)
• 0% packet loss - Perfect reliability under sustained multicast load
• Efficient memory management - Buffer reuse strategies minimize allocations and fragmentation
• Zero-copy operations - Data is processed in-place where possible to reduce memory overhead

Documentation:

• BENCHMARK_RESULTS_2025-10-20.md - Validated performance benchmarks
• PERFORMANCE_OPTIMIZATIONS.md - Detailed optimization strategies and results

Quick Start

Python Module

pip install asterix_decoder

import asterix

# Parse ASTERIX data
with open('capture.pcap', 'rb') as f:
    data = f.read()

parsed = asterix.parse(data)

# Display results
for record in parsed:
    print(asterix.describe(record))

Rust Crate

cargo add asterix-decoder

use asterix_decoder::{init_default, parse, ParseOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize ASTERIX with default config
    init_default()?;

    // Read and parse ASTERIX data
    let data = std::fs::read("capture.pcap")?;
    let records = parse(&data, ParseOptions::default())?;

    // Display results
    for record in records {
        println!("Category {}: {} items", record.category, record.items.len());
    }

    Ok(())
}

Pre-built Packages

Download pre-built packages from GitHub Releases:

Platform	Package Type	C++ Standard	Python	Rust	Installation
Ubuntu 22.04/24.04	.deb	C++23 (GCC 13+)	3.10-3.14	1.70+	sudo dpkg -i asterix_*.deb
Ubuntu 20.04	.deb	C++17 (GCC 11)	3.10-3.14	1.70+	sudo dpkg -i asterix_*.deb
Debian 11/12	.deb	C++23 (GCC 13+)	3.10-3.14	1.70+	sudo dpkg -i asterix_*.deb
RHEL/Rocky 9	.rpm	C++23 (GCC 13+)	3.10-3.14	1.70+	sudo rpm -i asterix-*.rpm
Fedora 40	.rpm	C++23 (GCC 14)	3.10-3.14	1.70+	sudo rpm -i asterix-*.rpm
Linux ARM64	.deb/.tar.gz	C++23 (GCC 13+)	3.10-3.14	1.70+	Raspberry Pi, AWS Graviton, NVIDIA Jetson
Windows 10/11	.zip/.msi/.exe	C++20 (MSVC 2022)	3.10-3.14	1.70+	MSI (WiX), EXE (NSIS), ZIP (portable)
macOS 13+ (Intel)	.tar.gz/.pkg	C++23 (AppleClang 15+)	3.10-3.14	1.70+	See BUILD Guide
macOS 14+ (M1/M2)	.tar.gz/.pkg/.dmg	C++23 (AppleClang 15+)	3.10-3.14	1.70+	See BUILD Guide

Language-Specific Packages:

• Python: pip install asterix_decoder (PyPI)
• Rust: cargo add asterix-decoder (crates.io)
• C++: Pre-built binaries above or build from source

Build from Source

C++ executable:

# Create build directory (out-of-source build)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel
cmake --install build

# Run the executable
./install/bin/asterix --help

Python module:

python setup.py install

Rust crate:

cd asterix-rs
cargo build --release
cargo test

Migration Note: GNU Make build files were removed in v2.8.10. All builds now use CMake as the unified cross-platform build system.

Dependencies:

• C++23 compatible compiler (upgraded from C++17):
  • GCC 13.0+ (recommended for full C++23 support)
  • Clang 16.0+ (recommended for full C++23 support)
  • MSVC 2022 v17.4+ / Visual Studio 2022 version 17.4+
  • AppleClang 15.0+ / Xcode 15+
• Rust: 1.70+ (for Rust bindings)
• Linux/macOS: libexpat-devel (XML parsing)
• Windows: See BUILD_WINDOWS.md

Note: The project uses C++23 features with automatic fallback to C++17/20 when C++23 is not available. For best performance, use a C++23-capable compiler.

Documentation

• Build & Installation Guide: docs/BUILD.md - Multi-platform build instructions
• Complete Documentation: montge.github.io/asterix - Full documentation site
• Language Bindings Comparison: LANGUAGE_BINDINGS_COMPARISON.md - Feature comparison, performance, use cases
• Rust Bindings: RUST_BINDINGS_INDEX.md - Complete Rust documentation
• Contributing Guide: CONTRIBUTING.md
• Architecture Overview: CLAUDE.md - Technical architecture
• Packaging Status: PACKAGING_AND_CI_STATUS.md
• ASTERIX Specifications: asterix-specs-converter/
• API Documentation: ReadTheDocs (placeholder - setup pending)

Supported ASTERIX Categories

24 Categories Fully Supported (v2.8.10):

Category	Version	Description
CAT 001	v1.2	Monoradar Target Reports
CAT 002	v1.0	Monoradar Target Messages
CAT 004	v1.12	Safety Net Messages
CAT 008	v1.0	Monoradar Derived Weather Information
CAT 010	v1.1	Monoradar Service Messages
CAT 011	v1.2	Monoradar Alert Messages
CAT 015	v1.2	NEW! INCS Target Reports (Added v2.8.10)
CAT 019	v1.3	Multilateration System Status
CAT 020	v1.10	Multilateration Target Reports
CAT 021	v2.6	ADS-B Target Reports
CAT 023	v1.3	CNS/ATM Ground Station Status
CAT 025	v1.5	CNS/ATM Service Status Reports
CAT 030	v6.2	ARTAS FPSDI (Final Processing + Safety Data Interface)
CAT 031	v6.2	ARTAS Picture Integrity
CAT 032	v7.0	ARTAS Miniplan
CAT 034	v1.27	Monoradar Service Messages
CAT 048	v1.21	Monoradar Target Reports
CAT 062	v1.18	System Track Data
CAT 063	v1.3	Sensor Status Messages
CAT 065	v1.3	SDPS Service Status Messages
CAT 205	v1.0	Area Proximity Warnings
CAT 240	v1.3	Radar Video Transmission
CAT 247	v1.2	Fixed Transponder Information
CAT 252	v7.0	ARTAS Operational Service Configuration

Coverage: 24 of 127 standard ASTERIX categories (19%) Latest Addition: CAT 015 v1.2 (INCS Target Reports) - Added in v2.8.10

See ASTERIX_CATEGORY_SUPPORT_MATRIX.md for complete category analysis, version gaps, and implementation priorities. Configuration files available in asterix/config/.

Usage Examples

Command Line

# Parse PCAP file to human-readable text
asterix -P -f capture.pcap

# Parse with JSON output
asterix -P -j -f capture.pcap > output.json

# Parse with extensive JSON (includes descriptions)
asterix -P -je -f capture.pcap > detailed.json

# Receive multicast stream (format: mcast_addr:interface_ip:port)
asterix -i 232.1.1.11:192.168.1.100:21111

# Parse raw ASTERIX file
asterix -f data.ast

# Parse FINAL format
asterix -F -f data.final

# Parse HDLC format
asterix -H -f data.hdlc

Output Format Options:

• Default: Human-readable text
• -l, --line: One line per item (parsable)
• -j, --json: Compact JSON (one object per line)
• -jh, --jsonh: Human-readable JSON (formatted)
• -je, --json-extensive: Extensive JSON with descriptions
• -x, --xml: Compact XML
• -xh, --xmlh: Human-readable XML

Python API

Basic parsing:

import asterix

# Parse ASTERIX data
data = b'\x30\x00\x30\xfd...'  # Raw ASTERIX bytes
parsed = asterix.parse(data)
print(parsed)

Incremental parsing for large streams:

offset = 0
blocks_to_read = 10

while True:
    parsed, offset = asterix.parse_with_offset(data, offset, blocks_to_read)
    if not parsed:
        break

    for record in parsed:
        process(record)

Get human-readable descriptions:

# Get description for a specific value
description = asterix.describe(category=48, item='010', field='SAC', value=7)
print(description)

Load custom category definitions:

# Load additional or custom ASTERIX category XML
asterix.init('/path/to/custom_asterix_cat.xml')

Rust API

Basic parsing:

use asterix_decoder::{init_default, parse, ParseOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_default()?;

    let data = vec![0x30, 0x00, 0x30, 0xfd]; // Raw ASTERIX bytes
    let records = parse(&data, ParseOptions::default())?;

    for record in records {
        println!("{:?}", record);
    }
    Ok(())
}

Incremental parsing for large streams:

use asterix_decoder::{parse_with_offset, ParseOptions};

let mut offset = 0;
let blocks_to_read = 10;

loop {
    let result = parse_with_offset(&data, offset, blocks_to_read, ParseOptions::default())?;

    if result.records.is_empty() {
        break;
    }

    for record in result.records {
        process_record(record);
    }

    offset = result.bytes_consumed;
}

Get human-readable descriptions:

use asterix_decoder::describe;

// Get description for a specific value
let description = describe(48, "010", "SAC", 7)?;
println!("{}", description);

Load custom category definitions:

use asterix_decoder::Parser;

// Create parser with custom category
let parser = Parser::new()
    .add_category("/path/to/custom_asterix_cat.xml")?
    .build()?;

More Examples

Python examples - asterix/examples/:

• read_raw_bytes.py - Parse from byte array
• read_raw_file.py - Parse from file
• read_pcap_file.py - Parse PCAP capture
• read_final_file.py - Parse FINAL format
• multicast_receive.py - Receive multicast stream
• multicast_send_receive.py - Full multicast demo
• xml_parser.py - Work with XML definitions

Rust examples - asterix-rs/examples/:

• parse_raw.rs - Parse from byte array
• parse_file.rs - Parse from file
• parse_pcap.rs - Parse PCAP capture with incremental parsing
• incremental_parsing.rs - Efficient stream processing
• json_export.rs - Export to JSON
• describe_category.rs - Query category metadata
• stream_processing.rs - Real-time stream processing

Radar integration examples - examples/radar_integration/:

• basic_mock_radar.py - Simple radar plot generation and ASTERIX encoding
• aircraft_scenario.py - Multi-aircraft simulation scenario
• encode_and_decode.py - Round-trip validation with error analysis

Radar Simulation Integration

This project includes tools for integrating radar simulation data with ASTERIX encoding/decoding:

Mock Radar Data Generator

Generate synthetic radar plots for testing without requiring proprietary radar simulation software:

from mock_radar import MockRadar, generate_aircraft_scenario
from asterix_encoder.cat048 import encode_cat048

# Create mock radar sensor
radar = MockRadar(lat=52.5, lon=13.4, alt=100.0)

# Generate synthetic radar plots
plots = radar.generate_plots(num_targets=10, add_noise=True)

# Encode to ASTERIX CAT048 binary format
asterix_data = encode_cat048(plots, sac=0, sic=1)

# Decode and validate
import asterix
decoded = asterix.parse(asterix_data)

Features

• Mock radar generator - Physics-based synthetic radar plots (range, azimuth, SNR, Doppler)
• ASTERIX CAT048 encoder - Convert radar plots to ASTERIX binary format
• Round-trip validation - Verify encoding accuracy and data preservation
• Scenario generators - Multi-aircraft scenarios, approach patterns, custom trajectories
• CI/CD integration - Automated testing with synthetic data
• RadarSimPy compatibility - Integration pattern for licensed users

Documentation

• Integration Guide: docs/INTEGRATION_RADAR_SIMULATION.md - Complete radar simulation integration guide
• Examples: examples/radar_integration/ - Working code examples
• RadarSimPy Findings: .local/integration/RADARSIMPY_FINDINGS.md - Investigation report

Use Cases

• Testing ASTERIX encoder/decoder without real radar hardware
• Algorithm development and validation
• Synthetic test data generation for CI/CD pipelines
• Integration with commercial radar simulators (RadarSimPy for licensed users)
• Educational demonstrations of radar-to-ASTERIX workflows

Development

Setup Development Environment

# Clone repository
git clone https://github.com/montge/asterix.git
cd asterix

# Install Python development dependencies
pip install -e .

Run Tests

# Python tests
python -m unittest

# Rust tests
cd asterix-rs
cargo test --all-features

# C++ integration tests
cd install/test
./test.sh

# Memory leak tests (requires valgrind)
cd install/test
./valgrind_test.sh

# Rust benchmarks
cd asterix-rs
cargo bench

Build System

Requirements:

• C++ Standard (platform-specific):
  • Linux: C++23 (GCC 13+, Clang 16+) - full feature set
  • macOS: C++17/C++23 (AppleClang 15+) - Python uses C++17 for compatibility
  • Windows: C++20 (MSVC 2022 v16.0+) - MSVC doesn't fully support C++23 yet, so C++20 is used
• CMake 3.20+
• libexpat library for XML parsing

CMake Build Commands:

# Configure and build (out-of-source build)
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

# Install to install/ directory
cmake --install build

# Debug build
cmake -B build-debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build-debug --parallel

# Clean build artifacts
rm -rf build build-debug

# Run tests
cd build && ctest

Why CMake:

• ✅ Cross-platform (Linux, Windows, macOS)
• ✅ Out-of-source builds (keeps source tree clean)
• ✅ Better dependency management (pkg-config, vcpkg)
• ✅ Modern IDE integration (VS Code, CLion, Visual Studio)
• ✅ Already required by Python and Rust bindings
• ✅ Unified build system across all platforms

Note: The C++ executable and CMake builds use C++23 on Linux/macOS (with automatic fallback to C++17/20 on older compilers), and C++20 on Windows/MSVC (MSVC doesn't fully support C++23 yet). Python module builds use C++17 on macOS, C++20 on Windows, and C++23 on Linux for optimal compiler compatibility while maintaining feature parity where possible.

CI/CD Pipeline

All commits are automatically tested across:

• Python versions: 3.10, 3.11, 3.12, 3.13, 3.14
• C++ standards: C++17 (legacy), C++23 (modern)
• Platforms:
  • Linux x86_64: Ubuntu 22.04/24.04, Debian 11/12, RHEL/Rocky 8/9, Fedora 40
  • Linux ARM64: Ubuntu 22.04/24.04 (Raspberry Pi, AWS Graviton)
  • Windows: Windows Server 2022 (MSVC 2022 v143)
  • macOS: macOS 14/15 (Apple Silicon ARM64)
• Build systems: CMake (generates Makefiles, Ninja, Visual Studio projects)
• Compilers: GCC 11/13, Clang 16+, MSVC 2019/2022, AppleClang 15+
• Quality checks: Coverage analysis, memory checks (Valgrind), static analysis (cppcheck, CodeQL)
• Security: CodeQL scanning for C++ and Python, compiler hardening flags

See PACKAGING_AND_CI_STATUS.md for detailed CI/CD status.

Security Features

This project implements defense-in-depth security practices:

Compiler Hardening (FREE tools, enabled by default):

• -fstack-protector-strong - Stack buffer overflow protection
• -D_FORTIFY_SOURCE=2 - Runtime buffer overflow detection (GCC/glibc, NOT commercial Fortify)
• -Wl,-z,relro,-z,now - Full RELRO (prevents GOT overwrite attacks)

Automated Security Scanning:

• - Semantic code analysis for C++ and Python
• - Automated dependency updates
• cppcheck - Static analysis in CI pipeline
• Pre-commit hooks - Detect hardcoded secrets, insecure patterns

Vulnerability Fixes:

• 41 CVEs resolved (4 critical/high, 37 medium/low)
• Integer overflow protections (CWE-190)
• Buffer overflow fixes (CWE-120, CWE-823)
• Input validation hardening (CWE-129)

Optional Commercial Tools (not required, but supported if available):

• HP Fortify SCA - Enterprise static application security testing
• Coverity - Advanced static analysis
• Valgrind - Memory leak detection (free, included in CI)

See SECURITY_AUDIT_REPORT.md for detailed security analysis.

Project Status

• Version: 2.8.10 (synced with upstream CroatiaControlLtd/asterix)
• Standards: C++23, C23 (backward compatible to C++17/C17)
• Test Coverage: 92.2% (560 tests, 100% passing)
• Platforms: Linux x86_64, Linux ARM64, Windows, macOS (Intel & ARM M1)
• Python Support: 3.10, 3.11, 3.12, 3.13, 3.14
• CI/CD: 50+ test configurations across all platforms and architectures
• Security: CodeQL enabled, 41 vulnerabilities fixed, 0 known active vulnerabilities
• Dependencies: Dependabot monitoring active (all PRs merged)
• Compliance: DO-278A AL-3 process in progress
• Packaging: DEB, RPM, ZIP, TGZ (MSI/DMG coming soon)
• Performance: +5-10% active improvement (C++20 ranges), +15-20% potential (C++23 deduced this)

ASTERIX Specification Updates

Specification Sources

ASTERIX category definitions are obtained and maintained from multiple sources:

Primary Source (Upstream Community):

• Repository: asterix-specs by Zoran Bosnjak
• Online Catalog: https://zoranbosnjak.github.io/asterix-specs/
• Format: JSON (converted to XML for this project)
• Converter: asterix-specs-converter/asterixjson2xml.py
• Update Frequency: Monitor upstream for new category versions

Original Authority:

• EUROCONTROL: http://www.eurocontrol.int/services/asterix
• Format: PDF specifications (unstructured)
• Note: Community JSON specs are structured versions of these PDFs

Conversion Pipeline:

EUROCONTROL PDF → Community .ast/.json → Our .xml (via asterixjson2xml.py)

How to Update Specifications

To update specifications:

cd asterix-specs-converter

# Update all specifications
python3 update-specs.py

# Convert single category
curl https://zoranbosnjak.github.io/asterix-specs/specs/cat062/cats/cat1.18/definition.json | \
  python3 asterixjson2xml.py > specs/asterix_cat062_1_18.xml

See asterix-specs-converter/README.md for details.

Contributing

Contributions are welcome! Please see our contributing guidelines (coming soon).

Before submitting PRs:

1. Ensure all tests pass: python -m unittest
2. Run integration tests: cd install/test && ./test.sh
3. Check code coverage remains above 90%
4. Follow existing code style (C++ and Python)
5. Add tests for new functionality
6. Update documentation as needed

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See LICENSE for details.

Credits

Originally developed by: Croatia Control Ltd. Current maintainer: @montge

For questions about the ASTERIX protocol or this tool, feel free to contact the original author: Damir Salantic

Support

• Report Issues: GitHub Issues
• Discussions: GitHub Discussions
• PyPI Package: asterix_decoder

---

Star this repository if you find it useful!