Groundkit Getting Started Guide

This document will guide you through installing and setting up Bright Ascension’s Helix Groundkit.

1. System requirements

The groundkit package is built for and tested with Ubuntu 22.04 LTS.

1.1. Java

Groundkit makes use of Java, and installing it will install the openjdk-17-jre-headless, and maven packages as a dependencies.

The Helix Groundkit CLI hgk will attempt to use its own version of Java by default, and will fall back to your own version of Java (if you have a JRE or JDK installed) only if it is unable to find the openjdk-17-jre-headless package which was installed with Groundkit.

The version of Maven available in Ubuntu’s apt repositories can be quite old, and may be incompatible with some Groundkit functionality. We recommend downloading and installing Maven directly from the Apache Maven Project website, and ensuring this version is configured to run in your environment. Groundkit has been tested and works with 3.9.12, the newest version at the time of publication.

2. Installing Groundkit

  1. Download Groundkit from the Bright Ascension download server using the credentials provided in the introductory email.

  2. Open a terminal in your downloads directory and run the following command:

    sudo apt install ./groundkit_2026.5.0-1_amd64.deb
  3. Check that Groundkit has installed correctly by running the following command in a new terminal:

    hgk

    You should see help text about the available sub-commands.

Groundkit 2026.5.0 uses tooling version 5.1.0, you can confirm this by running command hgk --version.

3. Updating Groundkit

Groundkit can be updated from an older version by downloading and installing the new package as in the last section.

You should consult the change notes before updating Groundkit. If you would like assistance with the update process, contact Bright Ascension using our customer portal.

Updating Groundkit will update the hgk tooling used to build your ground software. You will need to update your workspaces to use this new tooling. If the major version of hgk changes you will also need to make changes to code you have written.

Updating Groundkit will also remove bundles which were installed with the old Groundkit package (bundles you have installed yourself will not be affected). If you used these bundles in your workspaces, you will need to update your workspaces to use the new versions of the bundles. If the major version of the bundles changes, you will also need to make changes to code you have written.

  1. Download Groundkit from the Bright Ascension download server using the credentials provided in the introductory email.

  2. Open a terminal in your downloads directory and run the following command:

    sudo apt install ./groundkit_2026.5.0-1_amd64.deb
  3. Update each workspace to use the tooling and bundles included in the new version of Groundkit:

    • In the workspace.xml file, update the <Workspace> element’s toolingVersion attribute so it reads toolingVersion="5.1.0"

    • In the workspace.xml file, update any bundle dependency on GroundkitFoundation so it requires version 7.1.0.

<Dependencies>
  <Bundle name="GroundkitFoundation">
    <Version major="7" minor="1" patch="0"/>
  </Bundle>
  ...
</Dependencies>
  • Run hgk workspace prepare to update the local resources in the workspace.

  • We recommend you remove the generated and target directories, as these may contain data which is no longer compatible with your new version of Groundkit.

  • Consult the change notes to determine what changes you will need to make to your code.

4. Open the documentation in your browser

You can open the installed Groundkit documentation in your browser by running hgk-open-docs from the command line.

5. Bundles

Bundles are snapshots of workspaces which can be required by your own workspace to enable access to the artefacts contained within them.

Groundkit comes shipped with one bundle, GroundkitFoundation.

6. Creating workspaces

Once you’re familiar with Groundkit you can create your own workspace in which you’ll be able to write your own ground software.

To do so, run the following command:

hgk workspace create MyWorkspace

Your workspace should have been created in the MyWorkspace directory.

It is empty, but you can populate it with your own artefacts.

You can also use artefacts from the bundles provided with Groundkit, bundles provided to you, or bundles you have generated yourself.

To use a bundle you must:

  1. Determine whether the bundle you want to use is installed. To do so you can run the following command:

    hgk bundle list
  2. If the bundle you want to use is not listed by hgk bundle list you must install it. To do so, run the following command, replacing <path-to-bundle-archive> with the path to the bundle .tar.gz file which you wish to use:

    hgk bundle install <path-to-bundle-archive>
    You will likely need to use sudo to run this command because bundles are installed under /usr/share/bright-ascension/…​.
  3. With the bundle installed you should be able to see it in the output of hgk bundle list. You can then add it as a requirement of your workspace. Run the following command in your workspace directory, where <name-of-bundle> and <version-of-bundle> are the name and version of the bundle as they appear in the output of hgk bundle list:

    hgk workspace bundle require <name-of-bundle>:<version-of-bundle>
    You may omit the version of the bundle you require if you want to use the latest version you have installed. Conversely, if you want to use a specific version of a bundle then you must provide a version. For example, to specifically require version 1.6.0 of MyNewBundle, you would run hgk workspace bundle require MyNewBundle:1.6.0.

You are now ready to build your own ground software using artefacts from whichever bundles you require.