Components Feature Guide
1. Overview
HELIX Groundkit ground software is made up of Components, which are reusable software blocks. Each Component encapsulates a specific function within the ground software. For example, the comms.ccsds.SpacePacket Component from the GroundkitFoundation Bundle encapsulates the logic and packet structure for the CCSDS Space Packet protocol. It can be reused anywhere Space Packet handling is required.
Writing and maintaining Components is a key part of writing ground software with Groundkit. This makes having an intuitive understanding of what they are and what they are capable of essential. This guide is intended to describe the different things that come together to form a Component and how they work.
2. What is a Component?
A Component is a reusable software building block. They define a standard interface and a set of behaviours that can be reused across Deployments. Components expose specific items to other systems and users, including:
-
Parameters - typed fields that make hardware or software information available such as status, data values, or configuration data.
-
Actions - commands that can be issued to the software to execute specific functionality.
-
Tasks - autonomous behaviours, including periodic or sporadic execution.
-
Events - notifications emitted to other parts of a Deployment to say something.
-
Exceptions - status codes or error conditions that the component can return.
-
Services - definitions of how the Component connects to other Components.
Components interact with each other primarily via Services. Services describe the capabilities and behaviour that Components either provide to or require from other Components. By separating these concerns of Component functionality and interaction, we ensure they are functionally standalone and inherently reusable.
A Deployment is described by a set of Component instances and the ways they are connected together. A typical Deployment will often contain a combination of Components from Groundkit's included Bundles and bespoke Components developed for mission-specific tasks.
3. Reusability and Regularity
There are good reasons for taking this Component-based and Service-oriented approach. We introduce Components and their characteristics via two motivating factors:
-
The need for reusability of pieces of software functionality
-
The need for regularity when handling distinct software entities
For Component developers, the use of Services and interfaces to describe software capabilities ensures that any Component providing them knows what it must deliver, and any Component consuming them knows what it can expect.
For integrators who combine Components to build software systems for products and missions, the clean separation between Service/interface definitions and Component implementations means that specific Components are not tightly coupled to one another. A Component consuming a Service or interface can rely on the defined behaviour, despite not knowing which specific Component realises that behaviour or where it is located. This allows Components to be combined in many different ways depending on the needs of individual missions or products.
For operators who use GenOne software products - like using HELIX Ops to operate ground software developed with Groundkit, for example - the use of Services and interfaces like Actions and Parameters to describe the facilities of the software being operated means there are consistent ways to interact with that software. Regardless of the particular devices in use and the peculiarities of different missions, all Actions are invoked in the same manner and all Parameters are interacted with in the same way.
Beyond reuse, Components also provide some essential structural consistency. By being strictly regular about the way we define Components, we can treat Components as being the same as each other in many situations.
For example, in order for a Deployment to be able to initialise all of its Components at start up, each Component must provide the same regular interface for carrying out this initialisation. Without this consistency a Deployment would have no way to know how to bring up each of its different Component instances.
4. Component Types vs Components
In order to provide reusability, we separate the following concepts, and consider the boundaries between them: Component Types and Component instances. It is this multiplicity that gives these concepts their power in enabling software reuse.
4.1. Component Type
Similar to how object-oriented languages use classes to promote reusability, Groundkit uses Component Types. A Component Type is an abstract contractual definition of some provided and required capabilities. A Component Type is defined by two parts:
-
componentType.xmlA descriptor file that specifies how external systems interact with the component Type (its interface, inputs/outputs and contracts).
-
Implementation
The code that provides the Component's behaviour and fulfils the contract described in
componentType.xml. In Groundkit, Component Type implementations are written in Java. Implementation code may also define what initialisation data is required when building a Mission with a Deployment Type that instantiates the Component Type.
4.2. Component Instantiation
Instances of Component Types can be used by adding them to Deployment Types. They provide property values with which Component implementations are parameterised. A Component implementation may have multiple instances (each would use different values to determine the runtime behaviour of the implementation).
Component instances assign values to Component Type properties. This means that, at runtime, a populated initialisation data structure is provided to the code in the Component implementation.
5. Writing Components
5.1. Creating a Component
New Component Types can be created using Groundkit's hgk tooling with the following command:
hgk component-type create <ComponentName>
This will create a blank componentType.xml model in the Workspace's library/componenttypes directory. This file defines the public interface of the Component Type (Parameters, Actions, Tasks, Services, Events, Exceptions) and is used by Groundkit hgk tooling for validation and code/documentation generation.
|
Initialisation data is not defined in |
A newly created componentType.xml looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<!--
This file defines the MyComponentType component type.
Component types are reusable pieces of software functionality which can be
instantiated within deployment types.
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">
<ComponentType name="MyComponentType">
<!-- Component Imports -->
<!-- Exceptions (Status Codes) -->
<!-- Events -->
<!-- Required Components -->
<!-- Services (Provided and Required) -->
<!-- Tasks -->
<!-- Actions -->
<!-- Parameters -->
<!-- Implementation -->
</ComponentType>
</ModelElement>
The next step is to model the Component Type by adding to the XML. It might take a few iterations of defining and revising the Component model and to get it right. Time spent at the start capturing an accurate model will save a lot of time when it comes to implementation later on.
|
When writing the Component model, it is important to add elements in the correct order as the comments appear in the template so that the tooling can read the file. You do not need to include every section - define only what your Component Type requires. |
5.1.1. Choose the right construct
Before planning the architecture of your Component Type:
-
Familiarise yourself with the structure and conventions of
componentType.xml. -
Review existing Component Types in your Groundkit Bundles to follow established patterns.
-
Decide what should be configurable via initialisation data mapping, what must be exposed as Actions, what should be emitted as Events, and which dependencies must be declared as Services.
-
Use an Action when work is explicitly triggered by operator or by another part of the system.
-
Use a Task for autonomous behaviour:
-
periodic: runs at a fixed interval
-
sporadic triggered when data arrives on the Task queue.
-
-
Use an Event to announce results or state changes to other Components.
-
Use a Service to model dependencies and external interactions.
-
Use Exceptions to provide consistent, documented error outcomes.
-
The sections under <ComponentType> are described below.
5.1.2. Component Imports
Use Component Imports to declare Component Types that are referenced by this Component (for example, when you need to refer to types defined elsewhere).
Example:
<!-- Component Imports -->
<Import>
<Use type="AnotherComponentType" />
</Import>
5.1.3. Exceptions (Status Codes)
Use Exceptions to define custom status codes specific to the Component Type.
If you define Exceptions, you must set defaultBaseId. This base ID should be unique across your Mission. The first exception receives the value of defaultBaseId, and each subsequent exception increments from there.
Example (from comms.ccsds.SpacePacket):
<!-- Exceptions (Status Codes) -->
<Exceptions defaultBaseId="72000">
<Exception name="SendMaxPacketLengthExceeded">
<Description>
Packet size exceeds the configured maximum for sending.
</Description>
</Exception>
<Exception name="ReceivedPacketExceedsMaxSize">
<Description>
Received packet size exceeds the configured maximum.
</Description>
</Exception>
<Exception name="NoConfigurationForChannel">
<Description>
The SpacePacket component has no configuration for the selected channel.
</Description>
</Exception>
<Exception name="NoChannelForApid">
<Description>
The SpacePacket component has no channel configured for the APID indicated in the packet.
</Description>
</Exception>
<Exception name="BadConfigurationForChannel">
<Description>
The SpacePacket component has invalid configuration for the selected channel.
</Description>
</Exception>
</Exceptions>
5.1.4. Events
Events are notifications emitted by a Component to other parts of the Deployment. Typical uses include signalling that processing has completed, a state change occurred, or an error condition was detected. Events can be consumed by other Components to trigger follow-on behaviour.
To publish events, your Component Type must publish an EDS (Event Distribution Service):
<Services>
<Published>
<Service name="task" type="component.EDS">
<Description>
A publication for publishing Event messages from the publishEvent
periodic task
</Description>
</Service>
</Published>
</Services>
Define Events under <Events>. Like Exceptions, Events require a defaultBaseId. Each Event also declares a severity:
-
info— informational Event -
error— error Event -
componentFatal— Component fatal Event -
systemFatal— system-wide fatal Event.
Example:
<Events defaultBaseId="10000">
<Event name="SomethingHappened" severity="info">
<Description>
An event to notify the operator that something happened!
</Description>
</Event>
</Events>
5.1.5. Services (Provided and Required)
Under <Services>, declare the Services that the Component Type:
-
requires (dependencies it consumes),
-
provides (capabilities it exposes),
-
and potentially publishes, brokers, or subscribes (depending on your model conventions).
Example of a required Service (storage.FSS):
<Services>
<Required>
<Service name="filestore" type="storage.FSS">
<Description>
The service to use for storing the configuration settings.
</Description>
</Service>
</Required>
</Services>
This means the Component Type requires a storage.FSS provider (filesystem access) to be connected in the Deployment Type.
5.1.5.1. Service bindings
Services can define a binding, which controls how channels are mapped and how connections are validated. The binding types are:
-
fixed— a fixed number of channels (typicallychannels="N") -
variable— one to N channels -
optional— zero to N channels -
open— open access (connections are not made directly)
By default, a Service is fixed with a single channel.
Required services: binding determines how providers must be connected. fixed and variable requirements must have connections; optional may have none; an open requirement should not have direct connections (it calls a provider and channel directly).
Provided services: binding determines how consumers can connect and what channel validation applies.
Example (from io.ams.AMSInitiatorCS, a provided Service with binding and channel count):
<Services>
<Provided>
<Service name="target" type="io.AMS" binding="fixed" channels="1">
<Description>
The service where CS packets to/from the target are sent and received.
</Description>
<Documentation>
<Text>
This service is used to transmit request from the initiator to the initiator and receive the response
from the target, if a response is required.
</Text>
</Documentation>
</Service>
</Provided>
</Services>
5.1.6. Tasks
Groundkit supports two types of Tasks:
-
Periodic tasks — run whenever a fixed time interval elapses
-
Sporadic tasks — run when data is added to the Task’s associated queue
5.1.6.1. Periodic Tasks
Periodic Tasks are used for behaviour that runs at regular intervals.
Example:
<Tasks>
<PeriodicTask name="publishEvent" defaultPeriod="3">
<Description>
A task used to periodically publish events
</Description>
</PeriodicTask>
</Tasks>
This task runs every 3 seconds by default. The defaultPeriod can typically be overridden in the Deployment Type where the Component Type instance is configured.
5.1.6.2. Sporadic Tasks
Sporadic Tasks execute when data is added to their queue.
Example (from comms.io.net.tcp.SimpleTCPClient):
<Tasks>
<SporadicTask name="startTcpReceive" defaultQueueSize="1">
<Description>
Handle data receipt from a socket.
</Description>
</SporadicTask>
</Tasks>
defaultQueueSize defines the default size of the associated queue and may be overridden in the Deployment Type where the Component Type is instantiated.
5.1.7. Actions
Actions expose callable operations on a Component. An Action may optionally define an Argument describing the input provided by the caller.
Example:
<Actions>
<Action name="printGreeting">
<Description>
Print a greeting, specified in initialisation data, to the console.
</Description>
<Documentation><Markdown>
The message to print is set by the `greeting` field of the
`MessagePrinter` component type's initialisation data.
</Markdown></Documentation>
</Action>
<Action name="printUserMessage">
<Description>
Print a message, provided as an argument, to the console.
</Description>
<Argument name="message">
<Description>
The message to print.
</Description>
<Type>
<Blob fixed="false" maxLength="127"/>
</Type>
</Argument>
</Action>
</Actions>
This defines:
-
printGreeting— an Action with no arguments -
printUserMessage— an Action with one argument,message, typed as a Blob with maximum length 127 bytes.
5.1.8. Parameters
Parameters define typed fields exposed by the component. Parameters are mutable by default. To make a Parameter read-only (immutable), set readOnly="true".
Example:
<Parameters>
<Parameter name="actionCounter" readOnly="true">
<Description>
The number of times the action has been invoked.
</Description>
<Type>
<Integer signed="false" bits="32"/>
</Type>
</Parameter>
</Parameters>
This defines an immutable Parameter actionCounter containing an unsigned 32-bit integer.
5.1.9. Implementation
<Implementation> is used to enable the connection phase - behaviour that is not part of the public interface definition.
The connection phase occurs after all Components in the Deployment have completed local initialisation. It is used for making service calls that require other Component instances to be available.
Enable it with:
<Implementation connectionPhase="true"/>
When enabled, generated code includes lifecycle methods such as:
public void connectionInit() throws GenOneBaseException {
// TODO: Connection initialisation stage, the Component has been initialised
// and it is now possible to make service calls to interact with other Component instances.
}
public void connectionFini() throws GenOneBaseException {
// TODO: Connection finalisation stage, the Deployment is shutting down
// and any resources opened in connectionInit should be closed here.
}
5.1.10. Documentation
It is highly recommended to well describe and document Component Types and their elements. Use <Description> for a short summary and <Documentation> for longer content (for example Markdown). Both are included in auto-generated documentation.
Example:
<Description>
Whether to append to the file.
</Description>
<Documentation><Markdown>
See table in operation's documentation section above for more
information about how this argument behaves when combined with
all other arguments.
</Markdown></Documentation>
To add comments that should not appear in auto-generated documentation, use XML comments.
5.2. Practical guidelines
-
Keep the Component’s interface explicit and well-documented in
componentType.xml. -
Prefer expressing deployment differences via initialisation data rather than branching behaviour in code.
-
Keep responsibilities focused: if a Component grows unrelated features, consider splitting it.
|
When designing a Component Type, aim for a clear contract and configuration-driven behaviour. Deployment-specific configuration is typically supplied via initialisation data. |
5.3. Component instantiation and initialisation
Component Types are used by instantiating them. Each instantiation creates a new Component instance.
To produce executable ground software with Groundkit, you create a Deployment Type: a reusable collection of Component instances plus the connections between them. Deployment Types are also instantiated, creating Deployment instances.
Deployment Types are instantiated in the context of a Mission. When instantiating a Deployment Type, you provide Initialisation Data for each Component instance. Initialisation Data controls the runtime behaviour of the Component instance.
Deployment instances can be built and run. If they contain the necessary Component Instances, client code can interact with them.
5.4. Testing
A Component Type is generated with the following command:
hgk component-type generate <ComponentName>
This creates a test file under src/test/. You can implement unit tests there.
To see detailed build output, build the Component Type with the --verbose option:
hgk component-type build <ComponentName> --verbose
More information about unit testing can be found in the Unit Testing tutorial.
6. Related Documentation
-
Tutorial: Hello World 1