Flightkit Mission Layout Reference

A guide to the structure and on-disk layout of Flightkit missions.

1. Introduction

Missions are used to define the physical locations of the space system that deployment instances need to be run on. The tooling can then make use of this information to build the executable software required.

More specifically, a mission defines the following three collections:

  • The physical assets involved in the space system.

  • The targets on board those assets.

  • The deployment instances accessed by those targets.

Assets within a space system are most commonly spacecraft, but they can also be ground systems or other physical devices. An asset is essentially any physical environment that can host flight software. Depending on the asset, it may have the capability to host more than one piece of flight software at a time.

Targets bind specific deployment types to specific hosts within an asset. They are used to define the various deployment instances that need to be built to run on a particular host, usually to fulfil a particular functional role, within the mission.

Deployment instances are instantiations of deployment types that can be run as art of the mission. These are built to be run on a specific target. All deployment instances for a particular target are of the same deployment type, but can be configured differently via initialisation data to produce different behaviour.

The definition of a mission is described within a mission.xml file.

This document describes the contents of a mission.xml file in more detail, explains how it can be used to generate and build executable flight software for a mission, and describes the file structure produced by this process.

2. Mission XML

Missions are defined within a mission.xml file. Once defined, the tooling can use this information to both generate the mission’s boilerplate code and build system, as well as build the deployment instances within the mission to produce executable binaries.

2.1. Creating a Mission

The following command is used to create an XML for defining a mission:

hfk mission create MissionName

This command generates a file structure in missions containing a skeleton mission.xml file according to the mission name provided, which in this case was MissionName:

Workspace
└── missions
    └── MissionName
        └── mission.xml

The skeleton file contains the necessary elements for generating a mission consisting of a single deployment instance that runs on a Linux asset. It also contains comments explaining how the file can be modified to suit a specific mission’s needs.

2.2. Generating a Mission

Without making any changes to the default XML file, the mission defined within it, MissionName, can be generated by executing the following command:

hfk mission generate MissionName

This generates various additional files for configuring the mission, resulting in the following file structure:

Workspace
├── generated
|   └── ...
└── missions
    └── MissionName
        ├── MissionNameTarget
        |   └── MissionNameDeployment
        |       ├── init
        |       |   ├── comms
        |       |   |   ├── services
        |       |   |   |   ├── AASMessaging_Init.c
        |       |   |   |   ├── AASTarget_Init.c
        |       |   |   |   ├── PASMessaging_Init.c
        |       |   |   |   └── PASTarget_Init.c
        |       |   |   ├── PacketStream_Init.c
        |       |   |   ├── SpacePacket_Init.c
        |       |   |   └── TCPServer_Init.c
        |       |   └── Version_Init.c
        |       ├── lib_config
        |       |   └── meson.build
        |       └── meson.build
        └── mission.xml

The file structure shown is specific to the mission defined within the mission.xml file. All missions will follow a similar structure to this, however certain details will differ slightly.

Notice that the details of the directories under generated have been excluded from the diagram. They are not important from the perspective of the user. They are generated by the tooling and are required for the mission software to build and operate as expected, however they are never intended to be viewed or modified. For this reason they will not be discussed for the remainder of this document.

All of the user facing files generated by the tooling are placed within the MissionName directory. The first layer of these generated files consists of directories representing each target defined within the mission. In this case the only target is MissionNameTarget.

Within each target directory, a directory is generated to represent each deployment instance that runs on that particular target. In this case the only deployment instance running on MissionNameTarget is MissionNameDeployment.

Within each deployment instance directory, various initialisation and Meson files are generated. The initialisation data files placed within the init directory will differ depending on the component instances that exist within the deployment instance’s deployment type. They are grouped into subdirectories as per the dot separated names of the component instances within the deployment type. These are used to specify the initialisation data for each component instance in the instantiated deployment type.

The two Meson files, meson.build and lib_config/meson.build, are generated to indicate to the build system what it needs to build and how it needs to build it. The meson.build file specifies the initialisation data files which need to be included in the build process when building the corresponding deployment instance. This file is not expected to be modified by the user, it will be overwritten by the tooling each time the mission is generated to reflect the latest version of the deployment type. The lib_config/meson.build file provides a means of setting specific build arguments for different component types. This includes overriding preprocessor symbols which are defined within component types' _config.h files.

The following table illustrates how each element in the XML explicitly maps to the user facing files/directories generated by the tooling when generating the default mission:

Element Files

<Mission name="MissionName">

missions/MissionName/

<Assets><Asset>

No effect on user-facing files. Defines a physical asset that a target can be bound to.

<Targets><Target name="MissionNameTarget" …​>

missions/MissionName/MissionNameTarget/

<Deployments><Deployment name="MissionNameDeployment">

missions/MissionName/MissionNameTarget/MissionNameDeployment/

<Architecture><Board>

No effect on user-facing files. Specifies the physical board the deployment instance needs to be built to run on.

<Architecture><OSAL>

No effect on user-facing files. Specifies the OSAL that will be used to run the deployment instance.

<BuildConfig>

No effect on user-facing files. Specifies the build configuration that will be used when building the deployment instance.

The following table provides a brief description of each user facing file/directory generated by the tooling when generating the default mission:

File Description

MissionNameTarget

A directory for storing all files related to the mission’s MissionNameTarget target.

MissionNameTarget/MissionNameDeployment

A directory for storing all files related to the MissionNameTarget target’s MissionNameDeployment deployment instance.

init

A directory for storing initialisation data files for the associated deployment instance.

meson.build

Defines symbols which are required by the build system to build the associated deployment instance.

lib_config/meson.build

Enables setting of custom compiler arguments for building the associated deployment instance.

As mentioned earlier, not all of the files are intended to be modified by the user as some are overwritten by the tooling each time the mission is generated. The following table details which of the generated files are overwritten by the tooling, and which are intended to be modified and maintained by the user.

File Overwrite Behaviour

init/*

Not overwritten, no additional file generated

meson.build

Always overwritten

lib_config/meson.build

Not overwritten, no additional file generated

2.3. Building a Mission

Once the intialisation data has been set for all component instances within each deployment instance in the mission, the mission can be built using the tooling.

The command for building the MissionName mission is as follows:

hfk mission build MissionName

This generates the following additional files within the workspace:

Workspace
└── output
    └── missions
        └── MissionName
            ├── MissionNameTarget
            |    └── MissionNameDeployment
            |        └── MissionNameDeployment
            └── MissionName_0_0_0.missiondb

The output directory contains the completed artefacts needed for running the mission on the target hardware. It includes the deployment instance executables and the mission database. The artefacts are arranged in a similar manner to the files produced when generating a mission, with directories separating individual targets, and subdirectories separating deployment instances within those targets.

The deployment instance executables are the raw binaries that will be run on the assets defined by the targets. In this case only one executable has been produced since the mission only contains one target, with one deployment instance. The executable is given the same name as the deployment instance, MissionNameDeployment.

The mission database is a computer interpretable representation of the entire mission. It contains all the information necessary for understanding how to interact with the various pieces of executable software produced by the mission. It is used by the ground software to enable seamless integration with the flight software without needing to perform any manual configuration. The mission database is named after the mission itself, MissionName_0_0_0.missiondb.