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
-
Download Groundkit from the Bright Ascension download server using the credentials provided in the introductory email.
-
Open a terminal in your downloads directory and run the following command:
sudo apt install ./groundkit_2026.6.0-1_amd64.deb -
Check that Groundkit has installed correctly by running the following command in a new terminal:
hgkYou should see help text about the available sub-commands.
Groundkit 2026.6.0 uses tooling version 5.2.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 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. |
-
Download Groundkit from the Bright Ascension download server using the credentials provided in the introductory email.
-
Open a terminal in your downloads directory and run the following command:
sudo apt install ./groundkit_2026.6.0-1_amd64.deb -
Update each workspace to use the tooling and bundles included in the new version of Groundkit:
-
In the
workspace.xmlfile, update the<Workspace>element’stoolingVersionattribute so it readstoolingVersion="5.2.0" -
In the workspace.xml file, update any bundle dependency on
GroundkitFoundationso it requires version7.2.0.
-
<Dependencies>
<Bundle name="GroundkitFoundation">
<Version major="7" minor="2" patch="0"/>
</Bundle>
...
</Dependencies>
-
Run
hgk workspace prepareto update the local resources in the workspace. -
We recommend you remove the
generatedandtargetdirectories, 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:
-
Determine whether the bundle you want to use is installed. To do so you can run the following command:
hgk bundle list -
If the bundle you want to use is not listed by
hgk bundle listyou must install it. To do so, run the following command, replacing<path-to-bundle-archive>with the path to the bundle.tar.gzfile which you wish to use:hgk bundle install <path-to-bundle-archive>You will likely need to use sudoto run this command because bundles are installed under/usr/share/bright-ascension/…. -
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 ofhgk 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 runhgk workspace bundle require MyNewBundle:1.6.0.
You are now ready to build your own ground software using artefacts from whichever bundles you require.