Deployments Feature Guide

1. Overview

A Component is a reusable software block that encapsulates specific functions. A Deployment is a group of instantiated Components and the connections between those Component Instances.

Like Components, Deployments are also reusable and can be instantiated in a similar way within a Mission.

This guide describes the structure of a Deployment Type, how it is defined and instantiated, and how to generate its documentation.

2. Defining and Creating a Deployment Type

A Deployment Type is a reusable collection of Component Instances and the connections between them. Choices about which Components to instantiate and how those Instances are connected determine the behaviour of the Deployment when it is used.

Deployment Types are defined in deploymentType.xml files. A Deployment Type is created by executing the command:

hgk deployment-type create <DeploymentTypeName>

This command creates a new directory under library/deploymenttypes that contains the deploymentType.xml for a Deployment Type named <DeploymentTypeName>.

Deployment Types are used by instantiating them, creating Deployment Instances.

To use a Deployment Type in a Mission, you instantiate it as a Deployment Instance. To instantiate a Deployment Type you must provide Initialisation Data for each of its Component Instances. Initialisation Data is used to control the behaviour of Component Instances at run time.

3. Structure of a deploymentType.xml File

A newly created deploymentType.xml has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<!--
    This file defines the MyDeployment deployment type.

    A deployment type is a collection of connected component instances which
    can be instantiated within missions.

    Copyright (c) Bright Ascension Ltd, 2026
    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">
  <DeploymentType name="MyDeployment">
    <!-- Deployment Exceptions -->
    <!-- Deployment Events -->
    <!-- Deployment Implementation -->

    <!-- Execution Lists -->
    <!-- Routes -->
  </DeploymentType>
</ModelElement>

A Deployment Type is defined within the <DeploymentType> element. Each comment marker shows where a section belongs.

Currently, a Deployment Type uses only <Description>, <Documentation>, and the <Implementation> section with its <Routes> subsection. The other sections marked in the skeleton are not used by the Deployment Types that ship with Groundkit.

<Description> and <Documentation> are best placed as the first elements in <DeploymentType>. <Description> holds a brief description of the Deployment Type, and <Documentation> holds the fuller detail useful to developers and to users.

The supported sections under <DeploymentType> are described below.

3.1. Deployment Implementation

Under <Implementation> you instantiate Components and define connections between them. For each Component you want to instantiate, you need to specify the Component Type name and assign a name for the Component Instance. Example of Component instantiation:

<Component name="MyEventPublisher" type="EventPublisher">
  <Description>
    An instance of the EventPublisher which will log your message
  </Description>
  <Connections><Services>
    <Service name="task" component="EDSBrokerInst" service="edsBroker"/>
  </Services></Connections>
  <Tasks>
    <PeriodicTask name="publishEvent" priority="0"/>
  </Tasks>
</Component>

This is an example of instantiation of the Component Type EventPublisher named MyEventPublisher.

3.1.1. Services

When a Component Type declares a published, required or subscribed Service, that connection must be specified in the <Connections><Services> block during instantiation. In this example the Component Type publishes a Service component.EDS (the Event Distribution Service) under the name task, so that connection is defined when it is instantiated: published Service task is connected to the Service edsBroker brokered by an instance of core.component.eds.InContextEDSBroker named EDSBrokerInst.

3.1.2. Tasks

All Tasks declared on the Component Type must be listed in the <Tasks> block of the <Component> element. In this example the Component Type declares one Periodic Task, publishEvent. Every Task listed here takes a required priority attribute, and may also set deadline, stackSize and wcet. A Periodic Task may override the defaultPeriod declared on its Component Type with an optional period attribute, and may set an offset. A Sporadic Task may instead set queueSize and miat.

3.2. Routes

Routes define how a Deployment Type communicates with other Deployments. They are placed inside <Implementation> and must be specified for any Services that cross Deployment boundaries. Each Route has a name and a role - either initiator or target - which determines the direction of the connection.

Here is an example of Routes in the BasicCommsDemo:

<Routes>
  <Route name="ToFlightSoftware" role="initiator">
    <Service component="AASInitiatorInst" service="proxy"/>
    <Service component="PASInitiatorInst" service="proxy"/>
  </Route>
</Routes>

This defines a Route named ToFlightSoftware. Deployment Types specify whether they are Initiators or Targets on each Route: an initiator Route provides the Services it lists, and a target Route requires them. Declaring matching Routes is not on its own enough to connect two Deployments. The Mission that instantiates them makes the connection, by naming the target and its Route in a <Connections><Routes> block on the Deployment instance. BasicCommsDemo is a proxy Deployment containing Components for communicating with flight software. Components AASInitiatorInst and PASInitiatorInst in this Deployment act as a proxy for the AAS/PAS Service Providers in the flight deployment.

4. Generating Deployment Type Documentation

Documentation for a Deployment Type is generated by executing the following command:

hgk deployment-type generate-docs <DeploymentTypeName>

As a result documentation in HTML and Markdown formats will be created in the output/library/deployment_types/<DeploymentTypeName> directory.

A Deployment's documentation contains all of the elements of the Deployment Type and information about them from tags <Description> and <Documentation>.

5. Summary

A Deployment Type is a reusable collection of Component Instances and the connections between them. A new Deployment Type is created by executing the command:

hgk deployment-type create <DeploymentTypeName>

This command creates a deploymentType.xml file that instantiates selected Component Types and defines connections between them. It also specifies Routes for Services that communicate outside of the Deployment.

The deploymentType.xml file should contain:

  • <Description> - brief information about the Deployment Type

  • <Documentation> - extended explanation

  • <Implementation> - instances of all Component Types required in the Deployment Type.

If a Component Type declares Connections or Tasks, they need to be specified as well.

In addition to that, <Implementation> can also be used to define <Routes>.

A Deployment Type is not generated on its own. hgk deployment-type provides only create and generate-docs; the Deployment itself is built when its Mission is built, with hgk mission build, which produces a JAR file for each Deployment in the Mission.