Workspaces & Bundles
1. Overview
HELIX Groundkit uses Workspaces and Bundles to organise software development and manage how code is shared and reused.
Workspaces are directories where you write and organise your library code and Mission code, configure different parts of the system, and build your application for execution. Bundles are read-only snapshots of Workspaces that act as software libraries and can be reused by other Workspaces.
Together, they provide a clear separation between the code you write and the code you depend on.
2. Workspaces
Workspaces are project directories where you develop your ground software in HELIX Groundkit. It brings together all the directories and files you are actively working on into a single, structured environment.
Within a Workspace, you create Components, instantiate and group them in Deployments, and define the Assets within your Mission. The structure is designed to separate the different model elements and make it clear how the system is organised.
Once Workspaces have been fully populated, they will contain the following directories and files:
-
library– contains all created model elements except for Missions -
missions– contains the Mission XML file and the initialisation files for Component and Deployment instances. -
output– contains all outputs from development, including machine-readable Mission Database, generated HTML and Markdown documentation from Groundkit XML files, generated gRPCprotobuffiles, and executable ground softwarejarfiles -
generated– contains tooling-generated files required for building and running the Mission, and is not intended to be viewed or modified by users -
.hgk– contains Bundles andgen-one-java -
workspace.xml– defines the Workspace and lists its Bundle dependencies -
workspace-pom.xml– defines the external dependencies used by the Workspace
|
|
This structure helps you quickly understand where to make changes and which parts of the Workspace are managed by the system.
2.1. Creating a Workspace
To create a Workspace in your current directory, use the following command:
hgk workspace create <WorkspaceName>
This creates a directory with a workspace.xml file, which defines the Workspace and lists its dependencies, such as required Bundles.
2.2. Preparing a Workspace
The hgk workspace prepare command prepares a Workspace so it is ready to be used for development. This checks that the structures are valid and updates local resources in the Workspace.
2.3. Adding Model Elements to a Workspace
You can add model elements to a Workspace using the hgk command line tool. Use the following command to create a model element.
hgk <ModelElementType> create <ModelElementName>
where <ModelElementType> is the type of Groundkit model element you want to create (e.g. Component Type), and <ModelElementName> is a name of your choosing. The following model elements can be created this way:
-
Component Types
-
Deployment Types
-
Missions
-
Services
-
Modules
-
Boards
-
Operating System Abstraction Layers (OSALs)
This will create a blank XML template in the Workspace's library directory.
|
To learn more about the |
3. Generating Workspace Documentation
You can use the following command to generate HTML and Markdown documentation for your Workspace:
hgk workspace generate-docs
Documentation is created using each model element’s XML file and is added to the output directory within your Workspace. It can be helpful to generate documentation for Workspaces and Bundles to quickly view the contents of each model element and share it with other engineers.
4. Bundles
Bundles are read-only snapshots of Workspaces that function as software libraries in Groundkit. They contain pre-built Groundkit model elements such as Components, Deployments, Missions, and platform support. By adding a Bundle requirement in a Workspace, you can use its functionality without modifying it. This keeps your development straightforward by clearly separating what you create from what is provided for you.
Creating and sharing Bundles is the primary method of coordinating Groundkit software development within teams.
4.2. Bundle Versioning
Each Bundle has an associated version number, along with a corresponding hgk command line tooling version. These version numbers are defined in the Bundle’s bundle.xml file.
When a Bundle is used within a Workspace, the Workspace specifies the required version of that Bundle as a dependency. This dependency information is defined in the workspace.xml file.
4.3. Provided Bundles
Groundkit is distributed with the GroundkitFoundation and GroundkitExtras Bundles.
4.3.1. GroundkitFoundation Bundle
The GroundkitFoundation Bundle contains artefacts that are required to build a typical Mission.
It includes:
-
Core Components and Services
-
Communication & networking Components
-
Data storage Components
-
OSAL support
-
A pre-made Deployment and Groundkit Mission for communicating with a basic Flightkit Mission
4.3.2. GroundkitExtras Bundle
The GroundkitExtras Bundle provides additional operations-focused functionality beyond a basic Mission.
It includes:
-
Ground station network Services, including booking management
-
Orbital parameter distribution Components and Services
-
Parameter monitoring Components and Services
-
Event-driven response Components and Services
-
gRPC proxy Components for each of the above Services
4.4. Installing & Uninstalling a Bundle
Bundles on the disk must be installed to make them available to use in Workspaces. Use the following command to install a Bundle:
hgk bundle install <path-to-bundle-archive>
They can also be uninstalled when they are no longer needed:
hgk bundle uninstall <BundleName>.
This command can be forced using the -f flag.
4.5. Adding a Bundle Requirement to a Workspace
Workspaces can require one or more Bundles to access pre-built functionality. Adding a Bundle requirement in a Workspace brings in all of the Bundle's model elements, allowing them to be used.
Use the following command to add a Bundle requirement:
hgk workspace bundle require <BundleName>
Unless the Bundle version is specified, hgk will bring in the latest installed version.
After a Bundle requirement has been added to a Workspace, you must prepare the Workspace by using the following command:
hgk workspace prepare
5. Related Documentation
-
Feature Guide: hgk Tooling