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 gRPC protobuf files, and executable ground software jar files

  • 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 and gen-one-java

  • workspace.xml – defines the Workspace and lists its Bundle dependencies

  • workspace-pom.xml – defines the external dependencies used by the Workspace

gen-one-java is the Java language implementation of GenOne. Groundkit uses it to supply the shared Java runtime, APIs, and framework code needed for model elements, and it is treated as an internal dependency that should not be directly modified or touched by end users.

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 hgk command line tool, see the hgk Tooling feature guide.

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.1. List Available Bundles

To see available Bundles that can be used, run:

hgk bundle list

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

4.6. Creating a Bundle

To create a Bundle from the current Workspace, use the following command:

hgk workspace bundle generate <MAJOR.MINOR.PATCH> <output_directory>