MessagePackWriter Satellite#

Name	MessagePackWriter
Description	A satellite that receives data and writes it to a file using MessagePack
Category	Data Receivers
Language	C++
Website	constellation/satellites/messagepackwriter
Version	v0.1

Description#

This satellite receives data from other satellites and encodes them using MessagePack. The file format is sequential meaning that data can be read by other software while it is written by the satellite.

Data Format#

The file format consists of independent MessagePack objects which are added sequentially to the file. Each object is an array with length 3, consisting of the sender of the message (str), the type of the message (int) and a type-specific payload (array).

+--------------+------------+-----------------+
| Sender (str) | Type (int) | Payload (array) |
+--------------+------------+-----------------+

BOR Message#

Begin-Of-Run (BOR) messages have type 1 and the payload is an array with length 2 consisting of the BOR user tags (map) and the satellite configuration (map).

+-----------------+---------------------+
| User tags (map) | Configuration (map) |
+-----------------+---------------------+

DATA Record#

Data records have type 0 and the payload is an array with length 3 consisting of the sequence number of the data record (int), user tags (map) and the data blocks (array). Each data blocks is binary data (bin).

+-----------------------+-----------------+---------------------+
| Sequence Number (int) | User tags (map) | Data blocks (array) |
+-----------------------+-----------------+---------------------+

EOR Message#

End-Of-Run (EOR) messages have type 2 and the payload is an array with length 2 consisting of the EOR user tags (map) and the run metadata (map).

+-----------------+--------------------+
| User tags (map) | Run metadata (map) |
+-----------------+--------------------+

Python Decoder#

The following Python code can be used to dump the content of a file to the console:

from enum import IntEnum

import msgpack


class DataType(IntEnum):
    DATA = 0
    BOR = 1
    EOR = 2


def handle_msgpack_object(msgpack_object):
    # Each msgpack object consists of a sender, data type and payload
    sender, data_type_raw, payload = msgpack_object
    data_type = DataType(data_type_raw)

    print(f"{data_type.name} message from {sender}")

    if data_type == DataType.DATA:
        # DATA: payload consists of sequence number, user tags and data frames
        sequence_number, user_tags, data_frames = payload
        print(f" sequence number: {sequence_number}")
        print(f" user tags: {user_tags}")
        print(f" data frames:")
        # Each data frame is a bytes object
        for n, data_frame in enumerate(data_frames):
            print(f"  frame {n}: {data_frame}")

    elif data_type == DataType.BOR:
        # BOR: payload consists user tags and satellite configuration
        user_tags, config = payload
        print(f" user tags: {user_tags}")
        print(f" satellite configuration: {config}")

    else:
        # EOR: payload consists of user tags and run metadata
        user_tags, run_metadata = payload
        print(f" user tags: {user_tags}")
        print(f" run metadata: {run_metadata}")


def read_file(file_path: str):
    # Open file for reading in binary mode
    with open(file_path, "rb") as file:
        # Create msgpack unpacker to read from file
        unpacker = msgpack.Unpacker(file_like=file, timestamp=3)
        while True:
            try:
                # Read next msgpack object
                handle_msgpack_object(unpacker.unpack())
            except msgpack.exceptions.OutOfData:
                # Finished reading file
                print("End of file")
                break
            except KeyboardInterrupt:
                break

Building#

The satellite can be build and installed via Meson:

meson setup build -Dbuildtype=debugoptimized -Dwerror=false
meson compile -C build
meson install -C build

Parameters#

Parameter	Type	Description	Default Value
`output_directory`	String	Base path to which to write output files to	-
`file_name_pattern`	String	Pattern for the output filename. The placeholder `{}` will be replaced with the current run identifier.	`data_{}.raw`
`buffer_size`	Unsigned Integer	Size of file buffer before flushing takes place in KiB	`128`

Framework Parameters#

This satellite interprets the following configuration parameter that are provided through the Constellation framework. Parameters have to be placed in their respective configuration section.

Autonomous Operation#

Parameters to control autonomy in the _autonomy section:

Parameter	Type	Description	Default Value
`role`	Role name	Role this satellite should take in the Constellation. Accepted values are `ESSENTIAL`, `DYNAMIC`, `TRANSIENT` and `NONE`.	`DYNAMIC`
`max_heartbeat_interval`	Unsigned integer	Maximum interval in seconds between heartbeats to be sent to other Constellation components. The time between heartbeat is adjusted automatically according to the number of nodes in the Constellation but will never exceed this value.	`30`

Conditional Transitions#

Parameters to control conditional transitions in the _conditions section:

Parameter	Type	Description	Default Value
`require_initializing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `initializing` state	-
`require_launching_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `launching` state	-
`require_landing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `landing` state	-
`require_starting_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `starting` state	-
`require_stopping_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `stopping` state	-
`transition_timeout`	Unsigned integer	Timeout in seconds to wait for all conditions to be satisfied for conditional transitioning	`30`

Framework Metrics#

This satellite provides the following metrics that are defined by the Constellation framework.

Basic Satellite Metrics#

Metric	Description	Value Type	Interval
`RUN_ID`	Current run identifier. Updated whenever it changes.	String	-
`STATE`	Current satellite state. Updated when changed.	String	-
`CPU_LOAD_AVG`	CPU load average over the past 1 minute, provided in percent.	Float	10s
`MEM_AVAIL`	Available memory in Megabytes.	Integer	10s