Core Concepts¶

This document defines many of the core concepts that Hermes is designed around. Much of the Hermes documentation references concepts defined here.

Dictionary¶

A dictionary is the interface specification for a spacecraft's flight software. It defines all the commands the spacecraft accepts, the telemetry channels it produces, the events it can emit, and the parameters that configure its behavior. Without a dictionary, ground software cannot communicate with or understand data from the spacecraft.

Dictionaries serve as the contract between flight software and ground systems. When flight software is built, it generates a dictionary file that describes its entire command and telemetry interface. Ground software loads this dictionary to:

• Decode incoming telemetry: Map numeric channel IDs to human-readable names and parse binary values according to their types
• Encode outgoing commands: Serialize command arguments and validate them before transmission
• Format event messages: Combine event IDs with their arguments to produce readable log messages
• Validate data: Ensure values are within expected ranges and types match specifications

A dictionary is divided into namespaces whos use is defined by the project or framework. Dictionaries will always include the main or default namespace "".

Dictionaries are versioned and can evolve as flight software is updated. Ground systems may load multiple dictionary versions simultaneously to handle different spacecraft configurations or testbeds.

Types¶

The dictionary type system defines how data is structured and serialized between ground software and spacecraft. All telemetry values, command arguments, event arguments, and parameters use these types.

Primitives¶

Primitive types represent simple scalar values. These are the building blocks for more complex types.

Integer Types:

Floating-Point Types:

Other Primitives:

Integer and float types may optionally specify min/max bounds for validation.

Enumerates¶

Enumerated types map symbolic names to integer values, allowing human-readable labels for discrete states.

Key Attributes:

Bitmasks are a variant of enums where each item represents a bitwise mask, allowing multiple flags to be combined into a single value.

Objects¶

Objects (structs) are composite types containing multiple named fields. Fields are serialized in the order they are defined.

Key Attributes:

Each field has a name, type, and optional constant value. Objects can contain any type including other object, enabling nested data structures.

Arrays¶

Arrays are homogeneous collections of elements of the same type. Arrays can be either static (fixed size known at compile time) or dynamic (variable size with length prefix).

Key Attributes:

Static arrays have a compile-time fixed size and do not include a length prefix in their serialization. Dynamic arrays include a length prefix (U8/U16/U32/U64) before the array elements, allowing variable-length data.

Bytes¶

Bytes types are specialized arrays optimized for homogeneous numeric data. They store elements as packed binary data without per-element encoding overhead, making them efficient for bulk numeric telemetry like sensor arrays or image data.

Key Attributes:

Bytes types decode to native array types: NumPy arrays in Python, TypedArrays in JavaScript/TypeScript. This provides efficient memory layout and compatibility with numeric computing libraries.

Commands¶

Commands represent uplink messages sent from the ground system to the spacecraft. A command is the most basic (and important) mechanism to communicate with the spacecraft. They make up the backbone for deep-space autonomous operations.

Each command execution is a discrete event that should be recorded for audit and analysis purposes. The start and end of a command typically emit an event with COMMAND severity.

Key Attributes:

Commands can be grouped into sequences for multi-step operations, where multiple commands are executed in order as a single logical unit.

Telemetry¶

Telemetry represents channelized time-series data downlinked from the spacecraft. This is typically high-frequency sensor data, state information, and performance metrics that are continuously sampled and stored.

Key Attributes:

Telemetry is the highest volume data type and benefits most from time-series optimized storage.

Events¶

Events (EVRs - Event Reports) represent discrete log messages emitted by the spacecraft. These are structured log entries with severity levels, similar to traditional application logging but with spacecraft-specific context.

Key Attributes:

Severity Levels:

Events are lower volume than telemetry but critical for understanding spacecraft behavior and troubleshooting.

Parameters¶

Parameters represent configuration values, constants, and settings defined in the spacecraft's flight software. Unlike telemetry which provides dynamic sensor readings, parameters are static or semi-static values that configure how the system operates. They define thresholds, limits, operational modes, and other configuration data.

Key Attributes:

Parameters are typically lower volume than telemetry and events, representing the configuration state rather than runtime state. They may be updatable via special commands or fixed at compile-time depending on the flight software implementation.

Namespaces¶

Namespaces are organizational containers within a dictionary that group related definitions together. Many dictionaries will include a single main namespace called "".

Key Attributes:

Namespaces provide hierarchical organization of dictionary definitions, making it easier to manage large flight software systems with many components. Dictionary queries can target specific namespaces to retrieve only relevant definitions for a particular subsystem.

Files¶

File transfers track both uplink (ground → spacecraft) and downlink (spacecraft → ground) operations. These records capture transfer sessions for audit, debugging incomplete transfers, and data provenance.

Key Attributes:

File transfer records are relatively low volume compared to telemetry and events, but are important for operational tracking and ensuring data products are received completely.

Time¶

You obviously know all about time. But you may not know that time is actually far more complex than a readout on a clock. A spacecraft or mission as a whole typically has more than one source of time. It is important for operators to understand and manage these sources of time to understand the state of the spacecraft and plan accordingly. To illustrate this important point, we will consider a spacecraft in deep-space with a ground station on Earth.

In this example mission there are a couple time sources at play:

Epoch¶

The spacecraft's on-board clock is typically a crystal oscillator or some other high precision mechanism for measuring relative time deltas. The spacecraft clock keeps time using a numeric value that increments a specified rate. The value represents the time elapsed since some "zero time" or Epoch.

JPL uses two major epochs:

• J2000: January 1 2000. This is the most common epoch used by our spacecraft
• Unix: January 1 1970. This is the most common epoch used around the globe by many timekeeping systems.

Time Base¶

During the operational cycle of a spacecraft, the SCLK may incur discontinuous time jumps during different states. For example, many spacecraft will shutdown on a fixed cycle to save energy during unused spans. When the spacecraft boots back up the clock might not be initialized yet meaning the FSW reports time 0.0.

The ground might receive some messages like this:

0 000000000.0000 FSW CPU Reset
0 000000000.0010 FSW is booting up
0 000000000.0020 Looking for synchronized clock source
0 000000000.0030 Synchronizing clock
1 827432430.1512 Clock synchronized

You'll notice between the fourth and fifth event there is a time skip of about 26 years. This happens because the source of on-board time changes when the flight software synchronizes with the "proper" time source. The first field in this example indicates the "time base" of the SCLK. The time base is defined by the mission and should include enough cardinality to encompass all the continous time scales.

In this example the 0 time base indicates the raw on-board clock which is tied to the system reset time. The 1 time base indicates the epoch synchronized clock which is the nominal time base during the operation of the mission.

Non-Linear Time¶

Most of the concepts of time handling in Hermes are derived from JPL NAIF SPICE. SPICE concepts have been used at JPL to manage deep space missions for many decades dating back to the Apollo era.

Hermes provides an implementation of SPICE SCLK that is bit-compatible with CSPICE and supports loading SCLK time kernels. To understand more about SCLK and SPICE time kernels see the NAIF required reading.

Earth Return Time¶

Earth return time (ERT) simply means the time (usually in UTC) at which a given piece of data reaches the ground system. All Hermes timestamped telemetry will include SCLK and ERT and both will be used to analyze the state of the spacecraft.