Components Feature Guide
1. Overview
Helix Flightkit flight software is made up of Components, which are functional building blocks within a GenOne system. Each Component encapsulates a specific role within the flight software. They can represent software subsystems, such as the FlightkitFoundation Monitor Component, which permits the monitoring of onboard Parameters. They can also represent physical hardware, such as the LM70 Component in the FlightkitExtras Bundle, which provides an interface to the Texas Instruments LM70 temperature sensor.
A Deployment is a set of Component instances and the ways they are connected together. A typical Deployment will often contain a combination of Components from Flightkit's included Bundles and bespoke Components developed for mission-specific tasks.
Working with Components is a key part of writing flight software with Flightkit. 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 self-contained software unit, with a standard interface and well-defined set of behaviours. Components can use a variety of features which allow them to represent many different functions within GenOne software:
-
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 - Service messages informing subscribers that something specific happened.
-
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.
3. Component Types and Component Instances
In order to provide reusability, we separate the following concepts: Component Types and Component instances. It is this multiplicity that gives these concepts their power in enabling software reuse.
3.1. Component Type
Similar to how object-oriented languages use classes to promote reusability, Flightkit uses Component Types. A Component Type is an abstract contractual definition of some provided and required capabilities. Component Types are modelled using componentType.xml files, where the Component Type's high-level functionality is described.
A Component Type implementation is the code that provides the Component Type's behaviour and fulfils the contract described in componentType.xml. The implementation for a Component Type consists of the user-maintained C files and header files found with its componentType.xml.
3.2. Component Instantiation
Instances of Component Types can be used by adding them to Deployment Types. Each instance of a given Component Type has a specific set of values associated with it called initialisation data. The structure and interpretation of the initialisation data is set by the Component Type. This allows each instance to behave differently, within the bounds set by the Component Type.
4. Component Architecture
Developers working with Flightkit can rely on the Component-based architecture to insulate their Component from the details of the system in which they are working. This "insulation" happens courtesy of autogenerated data structures associated with each Component. These data structures are called containers.
In principle containers provide the only mechanism by which Component implementations can interact with "the outside world". This makes the details of this mechanism critical to understanding what Components can, and cannot, do.
Containers hold Service access point (SAP) and Service provision point (SPP) data structures used by the Component to consume and provide Services, respectively.
They also hold the Component initialisation data. The convention of including a pointer to initialisation data within a Component structure is just that - a convention - and is not actually required.
Containers provide PAS if the Component Type has Parameters and AAS if the Component Type has Actions. They also contain code to map PAS and AAS operations directly onto Component Parameter and Action access.
|
For more information, consult the Component Layout reference material. |
5. Why Components?
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 features like Actions and Parameters 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 definitions and Component implementations means that specific Components are not tightly coupled to one another. A Component consuming a Service 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 flight software developed with Flightkit, for example - the Component-based approach 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.
6. Writing Component Types
6.1. Creating a Component Type
New Component Types can be created using Flightkit's hfk tooling with the following command:
hfk component-type create <ComponentTypeName>
This will create a blank componentType.xml file in the Workspace's library/component_types directory. <ComponentTypeName> may contain . (dot) characters. The elements between the . characters are packages, and are represented within the library/component_types directory as sub-directories.
|
Consider the name you give to your Component Types to make them as descriptive as possible. For example, when creating a new Component Type to represent some hardware, we recommend using a name that matches the specific part name of the hardware, rather than a more generic name like |
The generated XML will have the following structure:
<?xml version="1.0" encoding="UTF-8"?>
<!--
This file defines the MyComponent 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. Before planning the architecture of your Component Type:
-
Familiarise yourself with the structure and conventions of
componentType.xml. -
Review Component Types in existing Flightkit Bundles to follow established patterns.
-
Decide what should be configurable via initialisation data.
It might take a few iterations of defining and revising the componentType.xml to get it right. Time spent at the start designing a Component Type will save a lot of time when it comes to implementation later on.
While writing the componentType.xml, keep responsibilities focused: if a Component Type grows unrelated features, consider splitting it.
|
When writing the You do not need to include every section - define only what your Component Type requires. |
6.1.1. Descriptions and Documentation
Most of the XML elements within a componentType.xml can have associated descriptions and documentation. Documentation is included here as a key way in which external parties interact with Component Types. It is unique in that the accessors should be expected to be human readers! As applies for any element added to a Component Type, it is important to consider carefully the correct level of detail to capture.
Both the <Documentation> and <Description> elements are included by the tooling when generating HTML and Markdown documentation.
|
Be generous with your use of documentation. This makes development between teams easier. Remember that it is likely that the end-users of the Component Types will not have access to the code you write. |
A <Description> gives a quick overview. This is to be used to convey quickly what the Component Type or element is at-a-glance. <Documentation> is there to give operators and systems engineers information on how to use the Component Type.
Top-level Component Type documentation in the typically provides some high-level narrative about:
-
The purpose of the Component Type.
-
How, broadly, to use it.
-
Any notable features, or substantial restrictions, it may have.
-
Any reference or other documentation which might be useful to a user later in the lifecycle.
Documentation may also be added for anything which the Component Type provides or requires - whether this is Services, Modules or other Component Types. This should typically describe the provided or required functionality in more detail to make using a Component Type easier.
6.1.2. Requiring and Providing Services
A Component may expose functionality through a Service provision.
Such a Component is offering a contract to the wider system. The Component is "promising" to fulfil the contract defined by that Service. It must do whatever is required to handle Service operations from a connected Component in line with the semantics of the provided Service. A Component providing a Service may be called a provider.
Thinking of Service provision in contractual terms is extremely powerful. It allows those interacting with a Component via a Service to "forget" all of its other characteristics and treat it only as a provider of the functionality promised by the Service.
Service provisions are specified by adding <Provided><Service> elements to a componentType.xml:
<Services>
<Provided>
<Service name="file" type="storage.FSS">
<Description>
Provides access to a file system.
</Description>
</Service>
</Provided>
</Services>
This snippet indicates that the Component Type will provide FSS. The provision’s name is file - this can be used later to connect a consumer to the Service provision.
A Component may offer multiple Service provision in various ways:
A provider can always choose to provide multiple channels of a Service. A channel represents some static subdivision of the Service provision (i.e. a channel refers to the same thing for the duration of the Service provision’s existence).
Components can provide a Service multiple times. Each provision has its own resources, and from the "outside" is not distinguishable from multiple Components each with a single Service provision. This makes sense in cases where the provider really can behave like 2 distinct providers.
A Service can be required by a Component Type in a similar way:
<Services>
<Required>
<Service name="file" type="storage.FSS">
<Description>
Requires access to a file system.
</Description>
</Service>
</Required>
</Services>
Components can provide different Services, each one or more times (and each with 1 or more channels).
A FileSystem Component would typically provide a single FSS provision, as shown above. If the author wished to acknowledge the existence of partitions on a single device, those partitions could be accessed by different channels on a single FSS provision:
<Services>
<Provided>
<Service name="file" type="storage.FSS" channels="4">
<Description>
Provides access to four filesystem partitions.
</Description>
</Service>
</Provided>
</Services>
If FileSystem provided access to file systems on a number of different storage devices, but each may (or may not) be available at a given time, the author might think it wise to offer multiple provisions of FSS to reflect the independence of the underlying file systems:
<Services>
<Provided>
<Service name="diskA" type="storage.FSS">
<Description>
Provide access to files on disk A.
</Description>
</Service>
<Service name="diskB" type="storage.FSS">
<Description>
Provide access to files on disk B.
</Description>
</Service>
</Provided>
</Services>
There are always subjective decisions to make when choosing whether to provide multiple channels on a single provision, or multiple provisions.
6.1.3. Requiring Components
Component requirements allow a Component Type to specify that it requires direct access to an instance of another Component Type at runtime.
This has the following concrete effects:
-
The requiring Component Type has a reference (pointer) to the required Component added to its container.
-
A mechanism for accessing this reference is provided to the Component Type.
-
#includedirectives are added to autogenerated headers to allow the requiring Component to directly call the functions defined by the required Component
A fairly common need when writing Component Types is to record the results of some operation. This might be logging data received from a subsystem, or recording the result of executing some scheduled behaviour, or maintaining a log of telecommands (TCs) received from a ground station.
A convenient way to capture this need is to specify a requirement on the CommandLogger Component Type. The requiring Component can than call the CommandLogger_log() function (effectively invoking the log Action, but without actually issuing an AAS operation).
Note that in the XML schema, Component requirements are specified quite separately from Service requirements:
<Required>
<Components>
<Componentname="packetLogger" type="logging.CommandLogger">
<Description>
packetLogger is used to log all incoming TCs
</Description>
<Documentation><Markdown>
Packets are logged using `packetLogger.log`.
Logged packets are prefixed with a 4-byte network-endian exception
value, indicating the status of the packet decoding.
Successfully decoded packets are prefixed with 0.
</Markdown></Documentation>
</Component>
</Components>
</Required>
It is essential to add clear documentation to Component requirements indicating how the connected Component will be used. Without this it is very difficult for Deployment authors to configure their Deployments.
6.1.4. Synchronous vs Asynchronous Service Access
A Component Type implementation can specify whether a Service it provides is provided synchronously or asynchronously.
The choice of synchronous or asynchronous provision can have a substantial effect on the overall behaviour of the system. Synchronous Service provision means Service operations are carried out within a single context. This is simpler to implement, and easier to understand. Asynchronous Service provision means Service operations are started in one context but completed in another. This frees up a system to do other work while a Service operation is blocked (on IO, for example).
Configure whether Service operations are carried out synchronously or asynchronously for the Component Type under the <Implementation> tag.
Under <Implementation>, you can define the default access mode for a Service (defaultAccess) and override access per operation. You can also mark operations as unused/unimplemented with access="none".
Example:
<Implementation>
<Service name="bus" defaultAccess="async">
<Description>
This service is asynchronous by default.
</Description>
<Operation name="writeRead" access="sync">
<Description>
This operation is used synchronously.
</Description>
</Operation>
<Operation name="readModifyWrite" access="none">
<Description>
This operation is not implemented/used by the component
</Description>
</Operation>
</Implementation>
6.2. Implementing a Component Type
Once the componentType.xml has been written, the next step is to generate the Component Type which will create the necessary implementation files.
hfk component-type generate <ComponentTypeName>
The main implementation file is ComponentTypeName.c. Here we need to provide the functionality promised in the componentType.xml model. The tooling will generate skeleton code based on the Component Type's model so the developer can focus on implementing the functions specific to the Component Type.
It also generates header files, where the Component Type's structure is defined, along with the structure of the initialisation data.
6.2.1. Templates
As you implement a Component Type, you may wish to change the componentType.xml to better suit your needs. In this case, if an implementation C file (e.g. ComponentTypeName.c) already exists for a Component Type then the hfk component-type generate command will instead create a new template file - ComponentTypeName.template.c. The skeleton code from this template file can then be copied across to ComponentTypeName.c, where the functions can be implemented. This way, you can still quickly generate the skeleton code without overwriting the work that has already been done.
6.3. Testing a Component Type
When a Component Type is generated, a test file is created within the Component Type's test directory. This contains various data structures and functions required to write some unit tests, as well as some autogenerated unit tests based on the componentType.xml.
As with implementation files, if a test file already exists when the Component Type is generated, then a template test file is created instead which can be used to copy across the generated functions.
As Component Types are expected to be reused in different contexts, it is important to write a set of tests that cover as many different use-cases as possible.
Once satisfied with the tests, run them with the following command:
hfk component-type test <ComponentTypeName>
|
More information about how to test Component Types can be found in the Unit Testing tutorial. |
6.4. Generating Component Type Documentation
Model documentation for a Component Type is generated with the following command:
hfk component-type generate-docs <ComponentTypeName>
This command will generate HTML and Markdown documentation in the output directory. It will also generate documentation for any target dependencies of the Component Type unless the no-deps flag is specified.
7. Component Lifecycle
The procedures by which Components are managed are collectively referred to as the Component lifecycle. In this section we describe the procedures the GenOne framework uses to manage Components.
7.1. Startup
Whether bare metal or running in a hosted environment like Linux, plenty of work is done before any Component code is executed. The system first goes through a layered startup process beginning with bringing up the board and OS support packages, then initialising the framework, platform, and task infrastructure, before handing over to the Deployment, which initialises all the Component management infrastructure, and all the Service dispatchers. At this point, task queues and tasks are initialised too.
With this infrastructure initialised, the Deployment’s Deployment_run() uses the Component manager to carry out the following Component-oriented initialisation steps.
Each of the steps in the following sections are carried out for each Component in the deploymentType.xml, in the order they are instantiated. For brevity we will call this instantiation order.
7.2. Local Initialisation
Each Component container’s localInit() function is called by the Component manager in instantiation order. The container initialises all SAPs and SPPs before calling the Component localInit().
The Component instance’s localInit() function is called with a pointer to the Component instance’s initialisation data. When this is called, the Component should at least validate its initialisation data. During localInit(), Component instances must not issue Service operations or interact with other Component instances.
If a Component instance returns a failure from its localInit() function then the Deployment will not start. What happens next depends on the OS and board support packages and hardware.
7.3. Configuration Initialisation
Again in instantiation order, the containers' configInit() functions are called. Containers of Component instances whose implementations do not require persistent configuration return immediately, indicating that no configuration is required.
If configuration is required, the container configInit() function calls the Component getConfigSize() function. This allows the Component manager to determine whether the amount of persistent storage the Component instance requires can be provided.
If getConfigSize() returns a failure, or if the indicated configuration size exceeds the Component manager limit, the Deployment will not start.
7.4. Connection Initialisation
Next, containers' connectionInit() functions are called. Containers of Component instances whose implementations do not require a connection initialisation phase then return.
If connection initialisation is required, the container connectionInit() function calls the Component connectionInit() function. The Component connectionInit() function may issue Service operations and otherwise interact with other Component instances. The connection initialisation phase is enabled by adding to the Component Type's <Implementation>:
<Implementation connectionPhase="true"/>
If a Component instance returns a failure from its connectionInit() function then the Deployment will not start.
7.5. Configuration Reset
Depending on the contents of the Deployment, the Component manager then performs a configuration reset.
In instantiation order, each container’s configSet() function is called. Containers of Component instances whose implementations do not require persistent configuration check no configuration is actually being provided and then return immediately.
If configuration is required, the container configSet() function calls the Component setConfig() function. This will either be called with a configuration size of 0, indicating the Component should use its internal default configuration, or a non-zero size, in which case the Component should validate and apply the given configuration.
If setConfig() returns a failure it is currently ignored. This is to give some resilience to bad persisted data.
8. Related Documentation
-
Reference Material Component Layout
-
Tutorial: Hello World 1