Skip to content

README.md

Latest commit

 

History

History
304 lines (225 loc) · 9.08 KB

README.md

File metadata and controls

304 lines (225 loc) · 9.08 KB
Raw

zephyr-ccsds

zephyr-ccsds is a standalone Zephyr module providing reusable CCSDS packet, routing, transfer frames & channel coding (BCH & Reed-Solomon) & COP-1 flow control.

It also provides:

  • CFDP file transfer
  • SDLS authentication & encryption in both TM & TC using GCM&GMAC
  • SDLS EP key management

It provides a UDP adapter for demo purposes.

Why this is Interesting

zephyr-ccsds provides a selectively complete "classic" CCSDS protocol implementation targeted natively to Zephyr RTOS, allowing deployment to extreme resource-constrained platforms such as MCU (STM32, ESP32-S3)

The project is intended for spacecraft flight software, payload processors, intelligent instruments and ground-based simulation environments that require CCSDS communications without imposing a complete framework.

Why Zephyr?

Zephyr is increasingly being adopted for embedded systems requiring a richer driver ecosystem, modern tooling, broader hardware support than associated with traditional embedded RTOSes. Work is underway within the Zephyr community to support safety-oriented use cases.

What's in scope?

The implemented CCSDS subset is intentionally "traditional", e.g. it does not attempt to tunnel IP protocols over CCSDS. It uses CFDP for file transfer and SLDS & EP for security. This is with a view to interoperability with existing ground systems, modems, transponders and operational practices used throughout the CCSDS ecosystem.

flowchart TB
    APP["Mission
Payload
Application"]

    subgraph ZC["zephyr-ccsds"]
        CFDP["CFDP
File Transfer"]
        SP["Space Packets"]
        SDLS["SDLS + EP
Authentication
Encryption
Key Management"]
        TF["TM / TC
Transfer Frames
COP-1"]
        CODING["Channel Coding
BCH & Reed-Solomon"]
    end

    ZEPHYR["Zephyr RTOS
PSA Crypto
Networking
Drivers"]

    HW["Radio
Modem
UDP Demo"]

    APP --> CFDP
    APP --> SP
    CFDP --> SP
    SP --> TF
    SDLS --> TF
    TF --> CODING
    CODING --> ZEPHYR
    ZEPHYR --> HW
Loading

Implemented subset:

  • CCSDS Space Packet encode/decode and APID routing.
  • TC transfer-frame and segment decode, complete-CLTU decode, BCH correction, packet reassembly.
  • A single-VC spacecraft receive profile covering sequence acceptance, lockout/retransmit state, UNLOCK and SET V(R), FARM-B counting, and CLCW generation.
  • TM transfer-frame generation, per-VC packet queues and routes, CLCW insertion, optional FECF, randomization, and Reed-Solomon coding.
  • CFDP PDU codecs, checksums, filestore/UT callback boundaries, Class 1 closure, missing-range recovery.
  • SDLS fixed-profile AES-256-GCM/GMAC wire processing, predefined-SA and key management by Extended Procedures, FSR generation.

Currently out of scope are:

  • LDPC channel coding
  • DTN / BP
  • BPSEC
  • AOS
  • Proximity-1
  • USLP

The implementation intentionally avoids targeting a complete flight software framework (e.g. NASA cFS ). It provides the minimal reusable CCSDS communications components as a native Zephyr library

Frame-level decoding and encoding are compile-time optional, since they may be deployed across multiple MCU, or supported in separate hardware. Cryptography uses the PSA API, which uses hardware assistance if available.

Obviously, the more you do in software, the lower the data rate you can support in a low-end MCU.

Why CCSDS?

In comparison with CSP (widely used on cubesats), CCSDS offers more standardisation & safety e.g. error correction, flow control, authentication & encryption & file transfer. On CSP missions the wider applications ecosystem tends to be proprieatary.

CCSDS remains the dominant interoperability standard for institutional space missions and provides the broadest ecosystem of interoperable communications infrastructure currently available. The standards are openly published.

Deployment

Zephyr applications consume it through standard module discovery and select the required protocol components through Kconfig.

The akira-ccsds project consumes this module as a west project for its application and device integrations. zephyr-ccsds is independent of AkiraOS, so other Zephyr applications can use its CCSDS implementation without adopting AkiraOS or its product-specific policies.

The module supplies public headers, neutral CONFIG_CCSDS_* Kconfig symbols, CMake integration, tests, samples, and application-facing callback boundaries. Applications retain ownership of endpoints, device drivers, filesystem layout, mission policy, security policy, and lifecycle behavior.

The included UDP adapter provides a ready-to-use transport. The callback boundaries also allow consuming applications to connect other transports, such as serial/UART, TWAI/CAN, Bluetooth LE, or radio, without changing the CCSDS protocol implementation. Adapters for those transports are not currently included in this repository.

See the documentation index for detailed behaviour, configuration, ownership, and limitations.

Requirements

  • A working Zephyr west workspace.
  • Zephyr 4.3.0 for the currently verified configuration.
  • A Zephyr-supported toolchain for the target board.
  • native_sim and a host compiler to run the supplied tests and sample.

The repository does not vendor Zephyr or toolchains.

Add It To A West Workspace

Add this project to the projects list in your application's west manifest:

manifest:
  projects:
    - name: zephyr-ccsds
      url: https://github.com/abarmitage/zephyr-ccsds
      revision: main
      path: modules/lib/ccsds

Then update only this project:

west update zephyr-ccsds

Using main is convenient while evaluating the module. Pin an immutable commit SHA or release tag for reproducible application builds. Zephyr discovers zephyr/module.yml automatically when the project is part of the active west manifest.

Existing Local Checkout

For temporary development outside a manifest, pass the repository's absolute path through ZEPHYR_EXTRA_MODULES:

west build -b native_sim /path/to/application --pristine -- \
  -DZEPHYR_EXTRA_MODULES=/absolute/path/to/zephyr-ccsds

Do not combine manifest discovery and ZEPHYR_EXTRA_MODULES for the same checkout; duplicate discovery can cause duplicate Kconfig or compilation integration.

Enable It In An Application

Once the module is discovered, an application needs no module-specific CMake calls:

cmake_minimum_required(VERSION 3.20.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
project(my_ccsds_app)
target_sources(app PRIVATE src/main.c)

Enable the core in prj.conf:

CONFIG_CCSDS=y

Public headers use the ccsds/ prefix:

#include <ccsds/ccsds_space_packet.h>
#include <ccsds/ccsds_router.h>

Frame support is enabled by default. Enable CFDP explicitly:

CONFIG_CCSDS=y
CONFIG_CCSDS_CFDP=y

For a packet-only CFDP application that does not need TC/TM transfer frames or channel coding:

CONFIG_CCSDS=y
CONFIG_CCSDS_CFDP=y
CONFIG_CCSDS_FRAME_SUPPORT=n

All protocol state is statically allocated or caller-owned. Review the module user guide and configuration reference before selecting buffer sizes for a constrained target.

Build And Run The Sample

From this repository's root inside a Zephyr west workspace:

west build -b native_sim samples/space_packet \
  -d build/ccsds-space-packet --pristine
./build/ccsds-space-packet/zephyr/zephyr.exe

Expected output includes:

CCSDS Space Packet round trip OK: APID=1 sequence=42 payload=deadbeef

Stop the native simulator with Ctrl+C after the result is printed. See the sample README for its exact behavior.

Run Verification

From this repository's root:

west twister -T tests -p native_sim --inline-logs
west twister -T samples -p native_sim --inline-logs
tests/cfdp_udp/run_cfdp_udp_integration.sh

The test suites cover module discovery, primitives, frames and profiles, CFDP, and packet-level two-peer UDP transfer with success, dropped-data recovery, and corruption failure.

Development

Development follows the standard Zephyr/west workflow for external modules.

When this repository is checked out by west, it is normally placed at the revision specified by the workspace manifest. Before making changes, switch to (or create) a development branch:

git switch -c my-feature

or:

git switch main

Develop, commit and push as you would with any normal Git repository.

Running west update later may return the working tree to the revision pinned by the workspace manifest, but your branches and commits remain intact.

Documentation

License

The module is distributed under the Apache License 2.0. The CCSDS standards themselves are not distributed with this repository.