User Documentation (Getting Started)

Installation

From PyPI

pip install space_packet_parser

From Anaconda

conda install -c lasp space_packet_parser

Basic Usage

The typical workflow for parsing packets is to

  1. Load a packet definition

    Packet definitions are the XTCE configuration documents that describe how to parse and extract binary chunks of data into Python variables.

    definition = spp.load_xtce("/path/to/xtce_definition.xml")

  2. Iterate over binary data

    You can load binary data from a file all at once, or continually read from a socket stream. To parse individual packets, you can iterate over that binary data to yield individual binary packet chunks one at a time. There is a built-in generator for CCSDS packets. Other binary packet generators can be used as well if your packets follow a different protocol from CCSDS.

    for binary_packet in spp.ccsds_generator("/path/to/packet_file.ccsds"):
    # Print out each packet's header
    print(binary_packet)

  3. Parse the binary packet data into a dictionary of parsed items

    With a definition (1) and a stream of individual packets (2), one can then parse the contents of that binary data into Python objects. The packet definition defines a lookup structure based on Parameter names, which are returned as a python dictionary of {ParameterName: value} items.

    packet = definition.parse_bytes(binary_packet)
# All items within the packet
print(packet)
# An individual item
print(packet["my_uint3_param"])

Putting this all together in an example script:

from pathlib import Path
import space_packet_parser as spp

packet_file = Path('my_packets.pkts')
xtce_document = Path('my_xtce_document.xml')
# 1) load the XTCE
packet_definition = spp.load_xtce(xtce_document)
# 2) create a binary generator to yield packet binary data
generator = spp.ccsds_generator(packet_file.open('rb'))
# 3) parse individual packets with the definition
packets = [packet_definition.parse_bytes(ccsds_packet) for ccsds_packet in generator]

# You can introspect the packet definition to learn about what was parsed
# Look up a type (includes unit and encoding info)
pt = packet_definition.parameter_types["MY_PARAM_Type"]
# Look up a parameter (includes short and long descriptions)
p = packet_definition.parameters['MY_PARAM']
# Look up a sequence container (includes inheritance)
sc = packet_definition.containers['SecondaryHeaderContainer']
# See the API docs for more information about the ParameterType, Parameter, and SequenceContainer classes

with packet_file.open("rb") as binary_data:
    from space_packet_parser import ccsds
    ccsds_generator = ccsds.ccsds_generator(binary_data)

    for packet_bytes in ccsds_generator:
        packet = packet_definition.parse_bytes(packet_bytes)
        # Do something with the packet data, which behaves like a dict
        print(packet['PKT_APID'])
        print(packet.header)  # subset of packet
        print(packet.user_data)  # subset of packet

We aim to provide examples of usage patterns. Please see the examples directory in the GitHub repo. If there is a specific example you want to see demonstrated, please open a GitHub Issue or Discussion for support.

Error Handling and Debugging

When parsing packets, you may encounter situations where packets cannot be parsed successfully. The low-level API provides direct control over how to handle these cases.

Handling UnrecognizedPacketTypeError

If a packet doesn’t match any of the defined packet structures in your XTCE definition, an UnrecognizedPacketTypeError will be raised. You can catch this error to examine the partially parsed packet data for debugging:

from space_packet_parser import ccsds
from space_packet_parser.exceptions import UnrecognizedPacketTypeError

with packet_file.open("rb") as binary_data:
    ccsds_generator = ccsds.ccsds_generator(binary_data)

    for packet_bytes in ccsds_generator:
        try:
            packet = packet_definition.parse_bytes(packet_bytes)
            # Process successful packet
            print(f"Successfully parsed packet with APID: {packet.binary_data.apid}")
        except UnrecognizedPacketTypeError as e:
            # Handle unrecognized packet
            print(f"Unrecognized packet type")
            print(f"Partial data: {e.partial_data}")  # Contains any successfully parsed fields
            # Continue processing other packets or handle the error as needed

Packet Objects

The object returned from parse_bytes() is a SpacePacket. This object subclasses a python dictionary and behaves as a dictionary. To retrieve a parameter value from the parsed packet, you can iterate over its items() or you can access individual parameters by name.

from space_packet_parser import ccsds
ccsds_generator = ccsds.ccsds_generator(data)
packet_bytes = next(ccsds_generator)
packet = packet_definition.parse_bytes(packet_bytes)
my_param = packet["MY_PARAM_NAME"]
all_param_names = list(packet.keys())

Parameter Objects

The parameter values within the packet are subclasses of normal python data types: int, float, str, bool and bytes. The objects behave exactly as the python data types except that they all contain a raw_value attribute, which contains the value generated by the data encoding parser, before being passed through any calibrators, enum lookups, string parsing, or boolean evaluation.

print(my_param)  # prints the most derived value available - str, int, float, bytes, or bool
print(my_param.raw_value)  # prints the "raw" encoded value parsed by the low level data encoding

Space Packet Parser returns the following types for parameters within a packet. They behave just as their Python base classes (int, float, str, bytes, and bool respectively) except that each contains a raw_value attribute that contains the encoded value before applying any calibration or other derived processing of the value. The primary value of each parameter type is the fully parsed (calibrated, enumerated, string-parsed, etc.) value.

  • IntParameter

  • FloatParameter

  • StrParameter

  • BinaryParameter

  • BoolParameter

Numeric Calibration

Int and float parameters can be calibrated on the fly during decoding. These calibrators are defined on the data encoding XTCE element and can transform the raw encoded value to a calibrated value, e.g. via a polynomial. Calibrated values are always floats, even if the raw encoded value is an integer.

For example,

<xtce:IntegerDataEncoding xmlns:xtce="http://www.omg.org/space/xtce" sizeInBits="16" encoding="unsigned">
    <xtce:DefaultCalibrator>
        <xtce:PolynomialCalibrator>
            <xtce:Term exponent="1" coefficient="1.215500e-02"/>
            <xtce:Term exponent="0" coefficient="2.540000e+00"/>
        </xtce:PolynomialCalibrator>
    </xtce:DefaultCalibrator>
</xtce:IntegerDataEncoding>

in this encoding definition, the raw encoded value is a 16bit unsigned integer that is calibrated by a polynomial to produce a calibrated value, which is always a float. In this case value = .012155 * raw_value + 2.54.

String Parsing

Strings are encoded as a buffer of determined size (either fixed length or dynamic based on previous parameter). The raw buffer includes any additional string data such as a leading size integer or a termination character. If a leading size or termination character is specified in the XTCE definition, the parsed string value is returned as the value of the parameter and the buffer is returned as the raw_value. If no termination character or leading size is specified, the value and raw_value are the same and both refer to the raw string buffer.

For example,

<xtce:StringDataEncoding xmlns:xtce="http://www.omg.org/space/xtce">
    <xtce:Variable maxSizeInBits="32">
        <xtce:DynamicValue>
            <xtce:ParameterInstanceRef parameterRef="STR_SIZE"/>
            <xtce:LinearAdjustment intercept="27" slope="8"/>
        </xtce:DynamicValue>
        <xtce:LeadingSize sizeInBitsOfSizeTag="3"/>
    </xtce:Variable>
</xtce:StringDataEncoding>

in this encoding definition, the size of the raw string buffer (number of bytes in the packet) is defined by a parameter named STR_SIZE. The value stored in STR_SIZE is given in number of bytes so it is multiplied by 8 and a constant base length of 27 bits is added to the final buffer size. So if STR_SIZE encodes the value 4, the raw string buffer width in the packet is 59bits. This is an odd size for a string because it is not an integer number of bytes but that’s because it includes a 3bit unsigned int in front of the string data that specifies the size of the string, in bits, making the raw string [3 bit uint | 7 bytes]

In this case, the raw_value of the parameter will contain the full string buffer as an 8 byte string, padded on the RHS with 5 zero bits. We have to pad it because you cannot create a byte string from a non-integer number of bytes (59bits). The value of the parameter will contain the fully parsed str object based on the value of the leading size. If the leading size uint3 represents the integer 4, the value of the parameter will be a str that is made of the first 4 bytes of data in the raw buffer following the leading size.

Termination characters work similarly.

<xtce:StringDataEncoding encoding="UTF-16BE" xmlns:xtce="http://www.omg.org/space/xtce">
    <xtce:SizeInBits>
        <xtce:Fixed>
            <xtce:FixedValue>32</xtce:FixedValue>
        </xtce:Fixed>
        <xtce:TerminationChar>0058</xtce:TerminationChar>
    </xtce:SizeInBits>
</xtce:StringDataEncoding>

In this case, the raw buffer is a fixed length (32bits). The parsed StrParameter.raw_value will be the full string buffer, including the termination character and any additional following bytes. The value of the parameter will be a str based on all the encoded bytes preceding the termination character. In this case, the raw string buffer will always be an integer number of bytes since a termination character is always an integer number of bytes, so no padding of the raw value is required.

Enumerated Lookups

Enums are defined by lookup tables in the XTCE, which are converted to dictionaries internally. Once the raw value from the data encoding is parsed, a lookup is made to the lookup table and the final string label is returned. Note that the final label from enumerated lookups is always a string. The raw value used in the lookup table is interpreted based on the data encoding for the parameter. Integer encoded enum values are ints, float encoded values are floats, and string encoded values are used as the raw string buffer from the encoding.

Only raw values may be used for enum lookups. Calibrated numeric values cannot be used for enum lookups from numeric encodings. For string encoded parameters, only raw string buffers may be used for lookups (not fully parsed strings).

For example,

<xtce:EnumeratedParameterType xmlns:xtce="http://www.omg.org/space/xtce" name="TEST_ENUM_Type">
    <xtce:UnitSet/>
    <xtce:IntegerDataEncoding sizeInBits="8" encoding="unsigned"/>
    <xtce:EnumerationList>
        <xtce:Enumeration label="OP_LOW" value="0"/>
        <xtce:Enumeration label="OP_HIGH" value="7"/>
    </xtce:EnumerationList>
</xtce:EnumeratedParameterType>

the encoded value (raw_value) is a uint8 integer but the value returned for an enumerated parameter type will be a StrParameter containing the label string associated with the integer value.

Boolean Evaluation

Booleans behave nicely for integers and floats where zero is False and everything else is True. For string and binary encoded values, the only falsy value is an empty string, which is kind of silly to encode. XTCE is not specific on the interpretation of string and binary encoded values for boolean parameters and there is no generally accepted interpretation, so we default to Python’s bool, which interprets any non-empty string as True.

Only raw values may be used for boolean evaluation. Calibrated values are not considered.

For example,

<xtce:BooleanParameterType xmlns:xtce="http://www.omg.org/space/xtce" name="TEST_PARAM_Type">
    <xtce:UnitSet>
        <xtce:Unit>m/s</xtce:Unit>
    </xtce:UnitSet>
    <xtce:IntegerDataEncoding encoding="unsigned" sizeInBits="1"/>
</xtce:BooleanParameterType>

the encoded value (raw_value) is a single bit interpreted as an integer but the value returned for a boolean parameter type will be a BoolParameter, evaluated over the encoded integer value. False if the integer is 0, True otherwise.

Parsing from a Socket

The input data object to XtcePacketDefinition.packet_generator need only be a binary filelike object from which bytes can be read. This means the packet generator is not limited to parsing data from files! In an effort to support development of quicklook type tools, we provide an example of parsing data streaming through a socket in parsing_and_plotting_idex_waveforms_from_socket.py.

The example mocks the behavior of an instrument sending packet data asynchronously through a socket in chunks of inconsistent size. The packet parser reads bytes from the receiver side of the socket and will read data repeatedly until there is sufficient data for the full packet. Once it has a full packet (as determined by the packet length in the CCSDS header), it cranks the generator and yields a parsed packet.

You’ll notice that the example ends with a timeout error. This timeout can be controlled when creating the socket connection with receiver.settimeout(timeout_seconds).

Variable Length Packet Fields of Explicit Length

Flight software engineers often need to downlink data (usually binary blobs) of variable length. The length of these fields is often specified in a previous telemetry point in the same packet, and you have to fetch the length by referencing that previous field.

Explicit Variable Length Example

Suppose the variable length field is called SCI_DATA and is a binary blob (e.g. of compressed data). The length of this field is specified earlier in the packet in a field called SCI_DATA_BYTELEN, specified in number of bytes. To define the type for SCI_DATA in XTCE, you could use the following (snippet):

<xtce:BinaryParameterType>
    <xtce:BinaryDataEncoding>
        <xtce:SizeInBits>
            <xtce:DynamicValue>
                <xtce:ParameterInstanceRef parameterRef="SCI_DATA_BYTELEN" useCalibratedValue="false"/>
                <xtce:LinearAdjustment intercept="0" slope="8"/>
            </xtce:DynamicValue>
        </xtce:SizeInBits>
    </xtce:BinaryDataEncoding>
</xtce:BinaryParameterType>

This tells the parser that the size in bits of data type SCI_DATA_Type (the type of SCI_DATA) is the raw value encoded in the parameter SCI_DATA_BYTELEN, multiplied by 8 (to convert number of bytes to number of bits).

Variable Length Packet Fields of Implicit Length

In some circumstances, flight software teams define a packet field that simply fills up the “remaining space” in the packet. The length of this field is usually implicit but can be computed by subtracting the combined length of all fixed length fields in the packet from the total length of the packet specified in the CCSDS header.

The PKT_LEN field is the length of the packet user data, in bytes. This field:

  • counts from zero

  • does not include the header data (always 6 bytes)

Thus, you can determine the length of your field dynamically from the packet length in the CCSDS header:

\[len_{var} = 8 \times (len_{packet} + 1) - \sum_n len_{fixed,n}\]

where

  • \(len_{var}\) is the length, in bits, of the variable length field

  • \(len_{packet}\) is the packet user data length in bytes (from the CCSDS header)

  • \(\sum_n len_{fixed,n}\) is the combined length of all fixed length fields in the packet user data

There are some limitations to this. If your FSW team is violating these limitations, they are making your life extremely difficult, and you have my condolences.

  • You can only have a single “remaining packet length” field in a given packet definition. Encoding more than one such field makes it impossible to determine the length of the fields.

  • All other fields in the packet must be fixed length. There is no way that I know of in XTCE to calculate a dynamic length that is an arbitrary function of multiple previous length specifier fields.

Implicit Variable Length Example

Packet Definition:

"VERSION" : 3 bits
"TYPE" : 1 bits
"SEC_HDR_FLG" : 1 bits
"PKT_APID" : 11 bits
"SEQ_FLGS" : 2 bits
"SRC_SEQ_CTR" : 14 bits
"PKT_LEN" : 16 bits
"SHCOARSE" : 32 bits
"SID" : 8 bits
"SPIN" : 8 bits
"ABORTFLAG" : 1 bits
"STARTDELAY" : 15 bits
"COUNT" : 8 bits
"EVENTDATA": variable length

To calculate the length of EVENTDATA:

\[\begin{split}len_{var} &= 8 \times (len_{packet} + 1) - (&&len_{SHCOARSE} + len_{SID} + len_{SPIN} + \\ & &&len_{ABORTFLAG} + len_{STARTDELAY} + len_{COUNT})\\ &= 8 \times (len_{packet} + 1) - (&&32 + 8 + 8 + 1 + 15 + 8)\\ &= 8 \times len_{packet} - 64 &&\end{split}\]

This equation can be implemented in XTCE by referencing the packet length field as follows:

<xtce:BinaryParameterType name="EVENTDATA_Type" >
    <xtce:BinaryDataEncoding>
        <xtce:SizeInBits>
            <xtce:DynamicValue>
                <xtce:ParameterInstanceRef parameterRef="PKT_LEN"/>
                <xtce:LinearAdjustment intercept="-64" slope="8"/>
            </xtce:DynamicValue>
        </xtce:SizeInBits>
    </xtce:BinaryDataEncoding>
</xtce:BinaryParameterType>

XTCE Document Validation

Space Packet Parser provides comprehensive validation capabilities for XTCE documents to help ensure they are correct and will work properly for parsing packets. The validation system operates in three modes: “schema”, “structure”, and a default mode of “all” (both schema and structure validation).

  • Schema Validation: Validates the XML document against the in-document referenced XTCE XSD schema

  • Structural Validation: Validates XTCE-specific structure and reference integrity

Schema validation requires correct namespacing declarations at the top of your XTCE document. e.g.

<xtce:SpaceSystem name="SpacePacketParser"
                  xmlns:xtce="http://www.omg.org/spec/XTCE/20180204"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://www.omg.org/spec/XTCE/20180204
                                      https://www.omg.org/spec/XTCE/20180204/SpaceSystem.xsd">

CLI Validation

spp --log-level=DEBUG validate my_xtce.xml --local-schema my_xsd.xml --level all

Programmatic Validation

from space_packet_parser import validate_xtce

# Validate an XTCE file against the referenced schema
result = validate_xtce("my_xtce.xml", level="schema")
if result.errors:
    for error in result.errors:
        print(f"Error: {error}")
else:
    print("Document is valid")

# Validate an XTCE document structure to check for
# unused Parameters ParameterTypes and nonexistent references
result = validate_xtce("my_xtce.xml", level="structure")
if result.errors:
    for error in result.errors:
        print(f"Error: {error}")
else:
    print("Document is valid")

# Comprehensive validation (both schema and structure)
result = validate_xtce("my_xtce.xml", level="all")
print(f"Validation completed in {result.validation_time_ms:.1f}ms")
if result.errors:
    for error in result.errors:
        print(f"Error: {error}")
else:
    print("Document is valid")

Troubleshooting Packet Parsing

Parsing binary packets is error-prone and getting the XTCE definition correct can be a challenge at first. Most flight software teams can export XTCE from their command and telemetry database but these exports usually require some fine-tuning.

UnrecognizedPacketErrors are raised during parsing of an individual packet when either:

  • a) multiple child containers are valid inheritors of the current sequence container based on restriction criteria evaluated against the data parsed so far

  • b) no child containers are valid inheritors of the current sequence container based on restriction criteria evaluated against the data parsed so far and the current container is abstract

To aid you during development, UnrecognizedPacketError exceptions generated during parsing can be returned alongside any valid packet objects by setting yield_unrecognized_packet_errors=True. These exception objects are not raised so that the generator may keep parsing. Instead, they are yielded from the generator with a partial_data attribute for user examination. This partial data allows you to see how far it got through a container inheritance structure before failing to determine the rest of the structure.

Common Issues and Solutions

Parser Generator Completes without Yielding a Packet

This can occur if your data file contains only packets that do not match any packet definitions in your XTCE document and yield_unrecognized_packet_errors=False (the default). This could mean that your data file actually contains only APIDs that are not covered in your packet definition, but usually it means you have incorrectly defined restriction criteria for SequenceContainer inheritance.

For example a restriction criteria element that requires an APID which does not exist in the data.

<xtce:RestrictionCriteria>
    <xtce:Comparison parameterRef="PKT_APID" value="-99" useCalibratedValue="false"/>
</xtce:RestrictionCriteria>

Only Packet Headers are Parsed

If you observe that only packet headers are being parsed but no exceptions are being raised (you may be seeing a lot of length mismatch warnings if you have logging set up), it likely means that you have forgotten to set abstract="true" on your non-concrete sequence container elements.

For example

<xtce:SequenceContainer name="CCSDSPacket">
    <xtce:LongDescription>Super-container for telemetry and command packets</xtce:LongDescription>
    <xtce:EntryList>
        <xtce:ParameterRefEntry parameterRef="VERSION"/>
        <xtce:ParameterRefEntry parameterRef="TYPE"/>
    </xtce:EntryList>
</xtce:SequenceContainer>

will parse as a complete packet, containing only VERSION and TYPE instead of searching for inheriting sequence containers. To define the container as abstract, change the first element opening tag to

<xtce:SequenceContainer name="CCSDSPacket" abstract="true">
...contents
</xtce:SequenceContainer>

Optimizing for Performance

The logic evaluated during packet parsing is largely reflective of the XTCE configuration being used to define packet structures. The more logic in the XTCE, the more logic must be evaluated during parsing. Below are some common ways to reduce complexity and speed up parsing:

  1. Remove RestrictionCriteria Elements: If your packet stream is a single packet structure, there is no reason to require the evaluation of a restriction criteria for each packet.

  2. Remove Unnecessary Packet Definitions: Even in a packet stream with multiple packet formats, if you only care about one packet type, you can remove the definitions for the other. By default, the packet Parser will catch unrecognized packet errors and skip to the next packet. This skips the parsing of packets for which a valid definition cannot be determined.

  3. Reduce Container Inheritance: A flat container definition structure will evaluate restriction criteria faster than a nested structure. Each instance of nesting requires an additional MatchCriteria.evaluate() call for each packet being parsed.

  4. Reduce Complex Items: Parameter type definitions that contain calibrators or complex string parsing (especially variable length termination character defined strings) add significant evaluation logic to the parsing of each parameter, as does any parameter type that is variable length. Removing them can speed up parsing.