Glossary

This page defines the terms you will encounter most often when working with CCSDSPy, a Python library for reading tightly packed binary spacecraft data in the CCSDS Space Packet Protocol format. Terms are grouped from the standard itself down to the specific API objects you use in code.

note

The names in this glossary follow the CCSDS Space Packet Protocol standard and the CCSDSPy API. Where a term has a precise meaning in the standard (such as the bit-length of a header field), that meaning is given exactly. CCSDSPy itself does not invent these terms; it implements the standard.

Standard and protocol terms

CCSDS

The Consultative Committee for Space Data Systems (CCSDS) is a multi-national forum that develops communications and data-systems standards for spaceflight. It publishes the standards that define how spacecraft format and transfer data. CCSDSPy is named after this body and implements one of its standards.

CCSDS is used by many NASA and ESA missions for low-level telemetry, and the data often contains tightly packed bits to reduce downlink requirements. CCSDSPy is used in operational flight missions including GOES-R, Europa Clipper, MMS, PACE, and HERMES.

Space Packet

The Space Packet is the unit of data defined by the CCSDS Space Packet Protocol. It describes how space missions transfer application data when both sending and receiving. A Space Packet has a maximum length of 65,536 octets (an octet is 8 bits, equivalent to a byte) and consists of three parts:

Component	Required?	Length
Primary header	Mandatory	48 bits (6 octets)
Secondary header	Optional	Variable
User data field	Variable	Variable

Everything after the primary header (the optional secondary header plus the user data) is collectively called the packet data field.

APID

The APID (Application Process Identifier) is an 11-bit field in the primary header that uniquely identifies a stream of packets — its source, destination, or type — on a space vehicle. Packets carrying the same kind of measurement share an APID, and the packet sequence count is maintained per APID.

tip

A single binary file frequently interleaves packets from many different APIDs. A common first step is to split the stream by APID so that each group can be parsed with the packet definition that matches it. CCSDSPy provides utilities for inspecting and splitting mixed streams; see the User Guide for the current helpers.

Primary header

The primary header is the mandatory 48-bit (6-octet) block that begins every Space Packet. Its fields are fixed by the standard:

Field	Length	Meaning
Version Number	3 bits	CCSDS version number; set to 000.
Packet Type	1 bit	Distinguishes telemetry (0) from commands (1).
Secondary Header Flag	1 bit	1 if a secondary header is present, otherwise 0.
APID	11 bits	Unique identifier for the packet stream.
Sequence Flags	2 bits	Marks segmentation (e.g. first/continuation/last).
Packet Sequence Count	14 bits	Sequential count of packets for a given APID.
Data Length	16 bits	Length in octets of the rest of the packet, minus 1.

In CCSDSPy you usually do not define the primary header by hand. When you call load(...), the primary header is decoded for you, and the include_primary_header parameter controls whether those parsed header fields are returned alongside your defined fields.

Secondary header

The secondary header is an optional block that directly follows the primary header. Its presence is signalled by the Secondary Header Flag in the primary header. It usually carries a time code for the packet. Because its layout is mission-specific, you typically model the secondary header as ordinary PacketField entries at the start of your packet definition.

Telemetry

Telemetry is the low-level measurement and housekeeping data transmitted from a spacecraft, encoded in CCSDS format. In the primary header, a Packet Type of 0 indicates telemetry (as opposed to 1 for commands). Reading downlinked telemetry into usable arrays is the primary purpose of CCSDSPy.

CCSDSPy API terms

PacketField

A PacketField defines a single field within a packet. It is the basic building block of a packet definition and requires a name, a data type, and a bit length:

from ccsdspy import PacketField

PacketField(name='SHCOARSE', data_type='uint', bit_length=32)

The supported data_type values are:

data_type	Meaning
uint	Unsigned integer.
int	Signed integer.
float	Floating-point value.
str	Fixed-length string.
fill	Padding / unused space (see Fill value below).

PacketArray

A PacketArray extends PacketField to decode multiple values of the same type into an array. In addition to name, data_type, and bit_length, it takes an array_shape and an array_order:

from ccsdspy import PacketArray

PacketArray(
    name='SENSOR_GRID',
    data_type='uint',
    bit_length=16,
    array_shape=(32, 32),
    array_order='C',
)

array_shape accepts either a tuple for a fixed-size array (as above) or the string "expand" for a variable-length field whose size is determined per packet:

PacketArray(
    name="data",
    data_type="uint",
    bit_length=16,
    array_shape="expand",
)

info

An expanding PacketArray (array_shape="expand") only works with ccsdspy.VariableLength, because the field length is not known until each packet is read. Fixed-shape arrays work with ccsdspy.FixedLength. See the Variable Length Packets guide.

Fill value

A fill value is space in a packet that does not carry meaningful data — for example, bits inserted for alignment or reserved for future use. In CCSDSPy you model these by setting data_type='fill' on a PacketField. A fill field is parsed (so that subsequent fields stay correctly aligned) but its contents are treated as padding rather than as a value you care about.

PacketField(name='SPACER', data_type='fill', bit_length=1)

Illustrative example. The following definition combines the terms above. It is shown only to illustrate how fields, arrays, and a fill field fit together; the field names and bit lengths are made up and do not correspond to any real mission packet.

import ccsdspy
from ccsdspy import PacketField, PacketArray

# Illustrative packet definition (not a real mission layout).
pkt = ccsdspy.FixedLength([
    PacketField(name='SHCOARSE', data_type='uint', bit_length=32),
    PacketField(name='SHFINE',   data_type='uint', bit_length=20),
    PacketField(name='OPMODE',   data_type='uint', bit_length=3),
    PacketField(name='SPACER',   data_type='fill', bit_length=1),  # fill value
    PacketField(name='VOLTAGE',  data_type='int',  bit_length=8),
    PacketArray(
        name='SENSOR_GRID',
        data_type='uint',
        bit_length=16,
        array_shape=(32, 32),
        array_order='C',
    ),
])

result = pkt.load('mypackets.bin')

Sources

• CCSDSPy documentation — User Guide
• CCSDS (Space Packet Protocol overview)
• Defining Packet Fields
• Variable Length Packets
• CCSDSPy/ccsdspy on GitHub