Missions

1. Overview

A Groundkit Mission is the top-level description of the system. A Mission defines the following collections:

  • The Assets in the system

  • The Targets where ground software can be executed within each Asset, along with their associated Deployment instances

A Mission is the "universe" that the model works in. As with many other artefacts in a Groundkit library, Missions are model-based and their definition is described within a mission.xml file. However, Missions are fundamentally different in that a single Mission is expected to be used for each project; they cannot be reused. It is not possible for anything in one Mission to refer to instances outside of that Mission.

The Mission contains instances from the various model domains and connects them to form a complete ground system. For example, a Mission creates instances of functional Deployments - comprising the Components which make up the software for the Mission - and identifies on which Targets they run.

The Mission workflow follows similar steps to other model elements. The Groundkit hgk tooling can be used to create, generate and build a Mission, as well as generating its documentation. Building a Mission produces two valuable outputs: the executable jar file(s) and the Mission Database that can be used to integrate the software with other HELIX products.

2. Deployments, Targets, and Assets

Deployment instances are instantiations of Deployment Types that can be run as part of the Mission. They are an executable piece of GenOne software, constructed by connecting a set of Components together. Deployments are built to be run on a specific Target.

Targets bind specific Deployment Types to 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. A Target may hold one or more Deployment instances, however only one Deployment is reachable on that Target at any one time. Because of this, a Mission describes the potential for executing software in a system, rather than the actual running software in a system. 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.

Hosts in turn represent individual physical or virtual resources on which software can be executed. An example of a Host is the JVMProcess. By assigning a Target to a Host, we are saying it is capable of executing a specific type of software. If a Host is multithreaded, it is possible to associate multiple Targets with it but that does not necessarily mean they can all run or be accessed at the same time.

An Asset represents a standalone hardware unit such as a spacecraft, ground station, or server. The most common Asset within a ground system is the generic.BasicJVM Asset, which represents the Java Virtual Machine engine. Assets may be given further structure by decomposing them into Subsystems. Both Assets and Subsystems may contain Hosts.

Mission elements cannot contain child elements with the same full name. For example: a Mission cannot have a top-level Asset and a top-level Deployment Target with the same name.

3. Mission Workflow

3.1. Creating a Mission

A new Mission can be created with the following command:

hgk mission create <MissionName>

This command generates a directory structure in the Workspace's missions directory containing a template mission.xml. Inside is an example Mission (below) using the generic.BasicJVMAsset Asset. The Mission has one Target defined with a single generic.BasicCommsDemo Deployment instance attached to it that has specified the OSAL, Board, and BuildConfig it will use.

Example mission.xml
<?xml version="1.0" encoding="UTF-8"?>
<!--
    This file defines the MyMission Mission.

    A Mission is a collection of Deployment Instances and a description of the
    Assets they run on. The Deployment Instances in a Mission can be built and
    executed on target hardware.

    Copyright (c) Bright Ascension Ltd, 2025
    Licensed Material - Property of Bright Ascension Ltd
-->
<ModelElement xmlns="http://www.brightascension.com/schemas/gen1/model"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Mission name="MyMission">
    <!-- Note: The order of the tags is important and should not be changed.
         Also, any default values here will be part of the GroundkitFoundation
         Bundle.
    -->
    <Description>
      The MyMission Mission.
    </Description>
    <Assets>
      <!--
        TODO If required, update the name and type of your Asset. In Flightkit
        or Groundkit, Assets are typically spacecraft, but may be used to represent
        any physical environment which can host flight or ground software.

        If you change the name of your Asset here, remember to update your
        Targets to refer to the new name.
      -->
      <Asset name="MyMissionAsset" type="generic.BasicJVMAsset"/>
    </Assets>
    <Targets>
      <!--
        TODO If required, update the name of your Target and its Deployment
        Type. Targets bind Deployments to hosts. Hosts are the parts of Assets
        capable of running flight or ground software.

        All Deployments which run on the same Target must be instances of the
        same type.

        Targets should typically be named to identify the role which the given
        host fulfils in the Mission. For example, "FlightComputer",
        "CommsRelay" and "SupervisorProcess" all reflect the role which a
        physical host could fulfil within the Mission.
      -->
      <Target name="MyMissionTarget" deploymentType="generic.BasicCommsDemo" hostAsset="MyMissionAsset" hostName="JVMProcess">
        <Deployments>
          <!--
            TODO If required, update the name of your Deployment Instance.
            Deployment Instances are the individual flight or ground software
            binaries which can run within your Mission.

            Their names have target scope, so typically should be chosen to
            describe how they are configured. For example, "Failsafe" and
            "EMEAFrequencies" reflect how the particular Deployment Instance is
            set up to carry out its job.
          -->
          <Deployment name="MyMissionDeployment">
            <Architecture>
              <Board name="JVM"/>
              <OSAL name="JVM"/>
            </Architecture>
            <BuildConfig name="jvmdefault"/>
          </Deployment>
        </Deployments>
      </Target>
    </Targets>
  </Mission>
</ModelElement>

A Mission description and documentation can be added, to be used by an operator or systems engineer to understand more about the system. Descriptions are used to summarise what the Mission is and what it is used for, whereas documentation is used for a more in-depth description of how to use it. Documentation can also be written for each Deployment on each Target to make a record of when and how to use each Deployment.

3.2. Generating a Mission

Once you have written the mission.xml, the next thing to do is to generate it with the following command:

hgk mission generate <MissionName>

For each Target in the Mission, a new directory will be created. Use this to specify the initialisation (init) data for all of the Component instances in the various Deployments. Each Component's init data structure is defined in the Component Type's corresponding …​ImplInitData.java file. The init data in the Mission simply needs to populate the fields already specified.

Each Component's init data structure is defined in the Component Type's corresponding InitData.java file located at: library/componenttypes/<component_type_name>/src/main/java/com/brightascension/componentimpls/<component_type_name>/<component_type_name>impl.

By specifying initilisation values at the Mission level, the same Component Types can be used again in other Missions with minimal effort.

If initialisation files are already present within the Mission directory, the hgk mission generate command will not overwrite these files.

To generate HTML and Markdown documentation for the Mission and its dependencies, use the following command:

hgk mission generate-docs <MissionName>

By default this will create model documentation in the Workspace's output directory.

3.3. Building a Mission

The final thing to do is to build the Mission using the following command: e

hgk mission build <MissionName>

This command does two things. First, it creates the executable software jars for each Deployment. Second, it creates a Mission Database, a portable description of the Mission that can be used to integrate with external software. All of these created artefacts can be found in the Workspace's ouput directory.