Definition Files

STARDOS is a modular architecture that is designed to have individual components swapped in and out regularly. In order to make this work, the tools that interact with mission configurations (such as StarCommand) need some information about each one of these components. This information is provided in the form of definition files, JSON files which contain all the information that various tools will need in order for each component to be handled properly. Each component type has a unique definition file format, some of which are more complex than others. All of these formats are detailed in this document, as listed below.

• Aircraft Definitions
• Node Definitions
• Capture Group Definitions

Additionally, these definition files make varying levels of use of nested objects. The types for these nested objects are also documented here, after the definition formats themselves.

Definition Files

A definition file is a JSON object defining a specific software node or other component, stored in a file. The basic structure for all of these objects is as follows:

type DefinitionFile = {
	type: DefinitionType;
	content: Definition;
}

where DefinitionType is a string listed in each of the following sections, and Definition is the actual definition object. Every definition file must have this DefinitionFile type as its top-level object, or tools such as StarCommand will not be able to understand them.

Aircraft Definitions

Type String: "aircraft_definition"

An aircraft definition file is the simplest definition file, providing metadata for a vehicle, typically an aircraft, that a mission will be run with. It has the following fields:

• name: string
  • The name of the vehicle. This is only ever used in UIs, and as such can contain any printable character.
• platform: string
  • The platform, type, or class of vehicle. Can be used to identify groups of vehicles that should all behave the same and can fit the same hardware. Generally, a mission made for one vehicle of a certain platform should work on any other vehicle of that platform.
• avionics: AvionicsDefinition
  • A definition that specifies what hardware and software makes up the control systems of the vehicle. Any vehicles that share the same AvionicsDefinition should ideally be indistinguishable to most STARDOS software.
• has_copilot: boolean
  • Whether or not the vehicle has a "copilot" computer, responsible for abstracting communications between the vehicle software, the control station, and the payload. A payload should ideally be able to communicate with any vehicle with a copilot installed with no changes save for the name of the vehicle.

Node Definitions

Type String: "node_definition"

Node definition files are the most complex definition file, including a config input typing and constraints system. Most of this will be detailed below, as these data structures are also used by other definition file formats. The data fields are as follows:

• name: string
  • This is the name that will be used for the node's ROS namespaces, and as such must be a valid ROS2 namespace name. Specifically, it must start with a letter, and contain only alphanumeric characters and underscores.
• human_name: string
  • This is the name that will be displayed in most UIs, and can accept any printable character.
• description: string
  • A longer description that will be included in the mission editor, describing what the node is and what it does.
• executable: string
  • The ROS package and executable for the node, in the form <package>/<executable>.
• input_type: string
  • The input data type of the node. The empty string indicates that this is a data producer, such as a camera. The special type any will pair with any previous node with an output_type that is not the empty string. Any other type must match exactly to the previous node's output_type in order to be considered valid.
• output_type: string
  • The output data type of the node. The empty string indicates that this is a data consumer, such as a "write to disk" node. The special type any will pair with any subsequent node with an input_type that is not the empty string. Any other type must match exactly to the subsequent node's input_type in order to be considered valid.
• config_entries: ConfigEntryDefinition[]
  • A list of all the config options this node has. The options will be listed in the user interface in the order they appear in the file. The ConfigEntryDefinition type is defined later in this document.
• errors: NodeErrorDefinition[]
  • A list of the non-exclusive error/warning states this node can enter. These states are reported by the node in its heartbeats in the form of a 32-bit bitmask, and the bits are read in The NodeErrorDefinition type is defined later in this document.
• states: { [id: number]: NodeStateDefinition }
  • A table containing the exclusive states that this node can enter. The index of each definition must be a signed 8-bit integer, its value carrying general meaning, while the definition itself contains the specific meanings. The NodeStateDefinition type is defined later in this document.
• data_fields: NodeDataFieldDefinition[]
  • A list of supplemental data fields the node sends with its heartbeats. There are a total of 128 bits (16 bytes) to work with. The order that the fields appear in this list will be the order the fields are decoded from the heartbeat messages, and the values are 1-byte aligned. The NodeDataFieldDefinition type is defined later in this document.

Capture Group Definitions

Type String: "capture_type_definition"

Capture group definitions are similar to node definitions, but are moderately simpler as capture group nodes don't have any data flow that needs to be accounted for. They use many of the same data types as node definitions.

• name: string
  • This is the name that will be used for the capture group's ROS namespaces, and as such must be a valid ROS2 namespace name. Specifically, it must start with a letter, and contain only alphanumeric characters and underscores.
• human_name: string
  • This is the name that will be displayed in the editor UI, and can accept any printable character.
• description: string
  • A longer description that will be included in the editor UI.
• executable: string
  • The ROS package and executable for the node, in the form <package>/<executable>.
• manual: Optional<boolean>
  • Whether or not this capture group will accept manual activation / deactivation requests. If it is not present, it will be treated as though it were set to true. If this value is true, payload control software will include activation and deactivation buttons for the capture group. Note that if it is true and the capture group does not respond to the requests, the buttons will not function, which may be confusing to the payload operator. If there are certain times when manual control should not be possible, but automatic control is, it may be desireable to place the node into a custom initialization state, as both buttons will be disabled when the node is in such a state, rather than setting this value to false.
• config_entries: ConfigEntryDefinition[]
  • A list of all the config options this capture group has. The options will be listed in the user interface in the order they appear in the file. The ConfigEntryDefinition type is defined later in this document.
• errors: NodeErrorDefinition[]
  • A list of the non-exclusive error/warning states this capture group can enter. the NodeErrorDefinition type is defined later in this document.
• states: { [id: number]: NodeStateDefinition }
  • A JSON object containing the exclusive states that this capture group can enter. Every key must be a signed 8-bit integer, its value carrying general meaning, while the definition itself contains the specific meanings. The NodeStateDefinition type is defined later in this document.
• data_fields: NodeDataFieldDefinition[]
  • A list of supplemental data fields the capture group sends with its heartbeats. There are a total of 128 bits (16 bytes) to work with. The order that the fields appear in this list in will be the order the fields are decoded from the heartbeat messages in, and the values are 1-byte aligned. The NodeDataFieldDefinition type is defined later in this document.

Complex Data Types

Each of the above definition formats utilizes one or more of the following complex data types, and many of the following types use additional complex types. These exist to provide more structure to the definition files as well as make them more readable and manageable.

They all appear in their respective JSON objects as nested JSON objects.

Additionally, some of these types make use of enum types, which will be defined in subsections under the type itself.

AvionicsDefinition

This is a simple data type that merely serves to identify parts of a vehicle which are shared among all vehicles that utilize the same control hardware and software. It should be noted that StarCommand contains a database table for this data type, and as such it can also be placed in a definition file of its own, with the type string "avionics_definition". Currently, this functionality is unused, but eventually StarCommand will have a UI for creating aircraft definitions, at which point this will become necessary.

• name: string
  • The name that will be displayed in UIs showing information about vehicles. Any printable characters are accepted here.
• description: string
  • A longer description that will be shown in some UIs.
• copilot_executables: string[]
  • A list of all of the programs that need to be launched in order for an on-board computer to communicate with the vehicle. ROS nodes should be in the format <package>/<executable>. A string that begins with a leading slash or does not contain any slashes will be treated as a simple executable at the given location or in the system default $PATH.

ConfigEntryDefinition

This data type defines a single config field for a software component. Many of its fields are optional. It includes a mechanism for adding constraints to the user-inputted values.

• name: string
  • The name that will be used when storing the value in the mission configuration. Ideally should be a valid identifier. Never seen in the UI.
• human_name: string
  • The name that will be displayed in the editor UI.
• description: string
  • A short description shown when hovering the mouse cursor over the config field in the editor UI.
• type: ConfigEntryType enum
  • The data type that the editor should accept for this field.
• units: string optional
  • A short string (usually only a few characters) that will be displayed after the input field. Intended to be used for a unit annotation.
• choices: string[] optional
  • A list of options to select. Supported for text and enum fields. When used with a text field, they are merely suggestions. When used with an enum field, they are the only options available, and the index of the selected option in this list will be stored in the config file.
• constraints: ConfigEntryConstraint[] optional
  • A list of constraints on the value. The order is irrelevant, as all constraints are checked regardless.
• placeholder: string optional
  • A placeholder value shown in a lighter text color when nothing is in the field.
• default: T where T is the type referenced by type. optional
  • The value that will be placed in the field when the node is added to a mission config in the editor.
• required: boolean
  • Whether or not this config field must have a value in it. If this is set to true, the mission control UI will not allow a mission configuration containing this component to be uploaded if this field is undefined or the empty string "".

ConfigEntryType

An enum used to identify the data type of a config entry field. The values are integers.

0. Integer
   • An integer field. Floating-point numbers will be truncated.
1. Float
   • A floating-point or decimal number field.
2. String
   • A short text field, possibly with optional suggested choices.
3. Enum
   • A list of options. The value stored will be the index of the selected option in the choices field, rather than the string value of the option.
4. Boolean
   • A checkbox. Note that the required field will require that the checkbox be checked.

ConfigEntryConstraint

A constraint on the value of a specific config entry. Each config entry can have any number of constraints. Only constraints of error severity will prevent a config from being uploaded.

• type: ConstraintType enum
  • The type of constraint this is.
• relation: ConstraintRelation enum
  • The relationship that is being checked for.
• alert: string
  • The message that will be included when the constraint is violated.
• severity: ConstraintSeverity enum
  • How severe the constraint is. Config upload will only be stopped if an error-severity constraint is violated.
• offset: number optional
  • If the value being checked against is a number, this number can be added to it. Most useful for Linked and Config-Linked constraints.
• invert: boolean optional
  • Inverts the match. Checks for equality become checks for inequality, checks for regex matching become a check that the value doesn't match, less than becomes greater than or equal to, etc.
• target: string only if type is Linked or Config-Linked
  • The name of the config field to compare against for Linked and Config-Linked constriants. Does nothing for Static constraints.
• value: T where T is the type of the config value being constrained. only if type is Static
  • The raw value to compare against for Static constraints. Does nothing for Linked and Config-Linked constraints.

ConstraintType

Indicates the "type" of constraint, how the editor determines what value to compare the inputted value against. The values are integers.

0. Static
   • The simplest form of constraint, this allows the editor to compare the user-provided config value with a static value stored in the definition. For example, an integer can be compared against a static maximum or minimum value, or a string can be matched against a stored regex expression.
1. Linked
   • Allows the editor to compare two user-provided config values within the same node configuration. For example, a capture group's activation altitude can be compared against its deactivation altitude, to ensure that it is above the deactivation altitude, and vice versa. Note that this will only create an alert on the constrained field, and will not affect the validity of the linked field.
2. Config-Linked
   • Allows the editor to compare the constrained value against a config value at the root of the mission configuration, for example the flight altitude. Note that this will only create an alert on the constrained field, and will not affect the validity of the linked field.

ConstraintRelation

Indicates the operation that should be used to compare the constrained value to the constraining value. The values are strings containing well-known operators for these operations from many programming languages. The operations are performed with the constrained value on the left-hand side and the constraining value on the right-hand side.

• ==: Equals
  • Checks if the constrained value is equal to the constraining value
• < : Less than
  • Checks if the constrained value is less than the constraining value
• > : Greater than
  • Checks if the constrained value is greater than the constraining value
• <=: Less than or equal to
  • Checks if the constrained value is less than or equal to the constraining value
• >=: Greater than or equal to
  • Checks if the constrained value is greater than or equal to the constraining value
• ~=: Matches
  • Treats the constraining value as if it were a regular expression and checks to see if the constrained value matches it. Note that anchors are not automatically inserted, so if the pattern is meant to match the entire constrained value, start and end anchors should be added to the pattern manually. Otherwise, the constraint will clear if any part of the constrained value matches.

ConstraintSeverity

Indicates what should happen if the constraint is violated. The values are integers.

0. Notice
   • The hover text will be updated with the alert field, but nothing else will happen. Can be used to provide details for enum options by using an inverted equality constraint.
1. Warning
   • The hover text will be updated with the alert field and the config field will turn red, but the mission manager will not prevent the mission from being uploaded.
2. Error
   • The hover text will be updated with the alert field and the config field will turn red. The mission will be considered invalid as long as any error-level constraints are being violated.

NodeErrorDefinition

A description of a non-exclusive warning / error bit, able to communicate the meaning of the warning or error to a mission operator if the flag is ever set.

• name: string
  • The name of the non-exclusive state, displayed by the UI.
• description: string
  • A short description of the non-exclusive state, potentially providing extra context towards what the error might mean.
• set_status: Status enum
  • The minimum status code that the mission monitor should use when this state flag is set.

Status

The status enum is used internally by mission monitor UIs as a single value that combines many different data sources into a single value used to set a status LED. It is used by the NodeErrorDefinition type to indicate the minimum status code while the referenced error flag is set. The values are integers.

0. Online
   • A default status to fall back on when no other status makes sense. Displayed the same as the Running status.
1. Running
   • The monitored system is online and performing its duties. StarCommand displays this status code as a solid green LED.
2. Standby
   • The monitored system is online and waiting for a command. StarCommand displays this status code as a solid blue LED.
3. Initializing
   • The monitored system is initializing. StarCommand displays this status code as a blinking light blue LED.
4. Warning
   • The monitored system is in a warning state. It likely needs attention, but is not critical. StarCommand displays this status code as a solid yellow LED.
5. Error
   • The monitored system is in a critical state and needs attention. This might indicate a mission failure scenario. StarCommand displays this status code as a blinking red LED.
6. Offline
   • The monitored system is offline. It has not been heard from in some time. StarCommand displays this status code as a grey, or "off" / "unilluminated" LED.

NodeStateDefinition

A description of an exclusive / "real" state. Provides additional context for what a specific state means with regards to the component, beyond what the range the state code falls under says.

• name: string
  • The name that will be shown in mission monitor detail UIs, in place of the default for the code range.
• description: string
  • A short description of the state that will be shown when hovering over the state in monitor detail UIs.

NodeDataFieldDefinition

A description of a supplemental data field included in the software component's heartbeats.

• name: string
  • The name of the data field. Should be a short, descriptive name generally only a single word or two. Abbreviations are encouraged as the space to display these is minimal.
• description: string
  • A short description that provides more context for the data. Shown when hovering over the data field in the mission monitor.
• type: DataFieldType enum
  • The primitive data type that is stored in the referenced field.
• units: string optional
  • A short (two or three characters) unit annotation that is appended to the decoded value when being displayed.
• size: int
  • The number of bytes this field needs. Should match the size of the data type.
• enum_definition: string[] only if type is Enum
  • A list of the up to 256 predefined strings that will be displayed based on the decoded value.

DataFieldType

An enum representing the primitive data type being sent in the data field. Values are strings containing short but descriptive and recognizeable types.

• uint8: Unsigned 8-bit (1-byte) integer (0 - 255)
• uint16: Unsigned 16-bit (2-byte) integer (0 - 65,535)
• uint32: Unsigned 32-bit (4-byte) integer (0 - 4,294,967,295)
• uint64: Unsigned 64-bit (8-byte) integer (0 - 18,446,744,073,709,551,615)
• int8: Signed 8-bit (1-byte) integer (-128 - 127)
• int16: Signed 16-bit (2-byte) integer (-32,768 - 32,767)
• int32: Signed 32-bit (4-byte) integer (-2,147,483,648 - 2,147,483,647)
• int64: Signed 64-bit (8-byte) integer (-9,223,372,036,854,775,808 - 9,223,372,036,854,775,807)
• float: Single-precision (32-bit, 4-byte) floating-point number
• double: Double-precision (64-bit, 8-byte) floating-point number
• bool: A boolean value. Will eventually be expanded to an 8-bit bitmask. Uses 1 byte.
• enum: An unsigned 8-bit (1-byte) integer that is used to look up a string to be displayed.