hgk Tooling

1. Overview

The hgk command line tooling comes as part of HELIX Groundkit, and allows you to:

  • Create Groundkit model elements such as Component Types and Deployment Types, and generate the resources needed to implement them.

  • Generate documentation for a model element or an entire Workspace.

  • Build and run Component Type unit tests.

  • Build a Mission, which produces a JAR file for each Deployment and a Mission Database.

  • Manage Workspaces and Bundles.

2. Using hgk

hgk is self-documenting. To bring up the help menu and show the available commands, open up a terminal and run hgk --help or hgk -h.

Usage: hgk [-h | --help] [SUB-COMMAND] [SUB-COMMAND-ARGS]

Helix Groundkit is a development kit for spacecraft ground software

Command arguments:
  --help, -h : display this help menu
  --version : display version information

Available sub-commands:
  board : Generate resources for boards
  bundle : Commands for managing bundles
  component-type : Create, delete and generate code for component types
  deployment-type : Create and generate documentation for deployment types
  mission : Create, generate, and build missions and their documentation
  module : Create, delete and generate code for modules
  osal : Generate resources for osals
  python : Generate python data bindings for a given mission
  service : Create, delete and generate code for services
  workspace : Create, delete and manipulate workspaces and bundles

The -h flag can also be added to any sub-command to see the required and optional arguments. For example, hgk component-type create -h:

usage: hgk component-type create
       [-h] [--verbose] [--root ROOT] name

Create a new component-type

positional arguments:
  name                   name of the component-type

named arguments:
  -h, --help             show this help message and exit
  --verbose              display a verbose output  message  for the command
                         (default: false)
  --root ROOT            root workspace  path,  required  if  not currently
                         within a workspace

While using hgk, it is expected that commands are run from within a Workspace, however it’s possible to run commands from outside a Workspace if the --root flag is specified.

To run commands with more expressive output to the console, use the --verbose flag.

2.1. hgk Version

The version of the tooling can be checked with the following command:

hgk --version

Note that this command does NOT return the Groundkit version; this version refers only to the hgk tooling.

The version of the tooling the Workspace expects to use is specified as a dependency in the workspace.xml file. Using a different tooling version in a Workspace to the one specified can lead to issues reading the model.

It is important to update each Workspace's tooling dependency inside the workspace.xml file any time Groundkit is updated.

2.2. Documentation and Tutorials

The full Groundkit documentation can be opened in your default browser with the following command:

hgk-open-docs

To generate the tutorials, run:

hgk-prepare-tutorials

This creates the necessary Workspaces and resources needed to follow the tutorials in the current directory.

3. Creating Model Elements

New model elements can be created with the command:

hgk <ElementType> create <ElementName>

where <ElementType> is the type of element you want to create (e.g. Component Type), and <ElementName> is a name of your choosing. The following model elements can be created this way:

  • Boards

  • Component Types

  • Deployment Types

  • Missions

  • Services

  • Modules

  • OSALs

This will create a blank XML template in the Workspace's library directory, or missions directory in the case of Missions. It is also possible to create a new Workspace this way, using hgk workspace create <workspace-name>.

4. Generating Model Elements

Once a model element has been created and its template XML file has been written, it can then be generated.

This process involves generating all the relevant resources needed to implement the artefact to satisfy the XML model. This includes generating the necessary directory structures, skeleton implementation code for the model element, and the glue code from the GenOne:Java language implementation that handles its interfaces. hgk generate produces these resources for Component Types, Services, Missions, and Modules, leaving the implementation code to be written.

Model elements can be generated with the command:

hgk <ElementType> generate <ElementName>

where <ElementType> is the artefact you want to generate (e.g. Component Type), and <ElementName> is the name of the artefact. The following model elements can be generated this way:

  • Component Types

  • Missions

  • Services

  • Modules

  • OSALs

The hgk osal generate command currently only generates the build system files associated with an OSAL. Implementations of periodic and sporadic Tasks are currently the full responsibility of the developer.

5. Generating Documentation

hgk can be used to generate documentation for model elements and entire Workspaces. This is in both HTML and Markdown form, and will be created in the output directory unless otherwise specified.

hgk <ElementType> generate-docs <ElementName>

where <ElementType> is the model element such as component-type or mission and <ElementName> is its name.

By default, this will also generate documentation for any target dependencies, although this can be changed by specifying --no-deps.

The tooling uses the XML model to populate this documentation. This includes using the <Description> and <Documentation> XML tags, as well as denoting the structure of the artefact.

6. Missions

As well as creating, generating, and generating documentation for Missions, hgk can build a Mission. Building produces the outputs needed to run the software.

Specifically, the build command creates a JAR file for each Deployment in the mission.xml, and a Mission Database. The Mission Database archives the Mission and its dependencies, and ground software such as HELIX Lab reads it to command and monitor the deployed software.

A Mission can be built using the following command:

hgk mission build <MissionName:MAJOR.MINOR.PATCH>

If no version number is specified, there must only be a single version of the Mission within the Workspace and its Bundle dependencies. The artefacts built with this command will be created in the output directory.

7. Using Workspaces and Bundles

The hgk bundle command allows a user to manage Groundkit Bundles.

Bundles cannot be created or required in a Workspace with this command. Use the hgk workspace command instead.

7.1. Install and Uninstall Bundles

A Bundle is a snapshot of a Workspace, which enables teams to share library elements. Bundles on the disk must be installed to make them available to use in Workspaces.

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.

7.2. List Available Bundles

To see available Bundles that can be used, run:

hgk bundle list

7.3. Creating a Workspace

To create a new Workspace, run:

hgk workspace create <WorkspaceName>

7.4. Preparing a Workspace

hgk workspace prepare 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.

7.5. Requiring a Bundle

Requiring a Bundle in a Workspace brings in all of the Bundle's elements, allowing them to be used.

hgk workspace bundle require <BundleName>

Unless the Bundle version is specified, hgk will bring in the latest installed version.

After a new Bundle requirement has been added, the Workspace must be prepared again using hgk workspace prepare.

7.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>

8. Unit Tests

The hgk component-type build command allows a user to build and run Component Type unit tests. For example, hgk component-type build <ComponentName>.

Each test in the ComponentNameImplTest.java file will output a success or fail status to the console. There will also be a summary of the overall test results.

By specifying the --build-only flag, the tests will not run.

Refer to the Unit Testing tutorial for more information about performing unit tests in Groundkit.

9. Python

Groundkit can be used to generate a Python API for a Mission, enabling it to be interacted with via Python scripts. This takes a Mission Database and generates a set of classes representing each of the model elements within the Mission to a specified output directory. To do this, run:

hgk python generate <MissionName:MAJOR.MINOR.PATCH> -m <path-to-missiondb> -o <output-directory>
  • The positional argument names the Mission and its version, using the Mission's full name. The version can be omitted where only one version of that Mission is available.

  • -m is the path to the Mission Database to generate from.

  • -o is the directory to generate into.