hfk Tooling
Overview
The hfk command line tooling that comes as part of HELIX Flightkit is a powerful tool to help users develop and manage their flight software. It plays a central role throughout the software development lifecycle, defining the processes through which users create and interact with Flightkit model elements like Component Types and Deployment Types. hfk provides ways of accelerating the development process through code and documentation generation, unit testing support, and the creation of Mission outputs in the form of a Mission Database and binary executables.
As a developer, understanding hfk and what it is capable of is crucial to get the most out of Flightkit's model-driven approach to writing flight software.
Using hfk
hfk is self-documenting. To bring up the help menu and show the available commands, open up a terminal and run hfk --help or hfk -h.
Usage: hfk [-h | --help] [SUB-COMMAND] [SUB-COMMAND-ARGS]
Helix Flightkit is a development kit for spacecraft flight software
Command arguments:
--help, -h : display this help menu
--version : display version information
Available sub-commands:
board : Generate resources for boards
build-config : Generate resources for build configurations
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
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, hfk component-type create -h:
usage: hfk 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 hfk, it is expected that commands are ran 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.
hfk Version
The version of the tooling can be checked with the following command:
hfk --version
|
Note that this command does NOT return the Flightkit version; this version refers only to the |
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 |
Documentation and Tutorials
The full Flightkit documentation can be opened in the default browser with the following command:
hfk-open-docs
To generate the tutorials, run:
hfk-prepare-tutorials
This creates the necessary Workspaces and resources needed to follow the tutorials in the current directory.
Creating Model Elements
New model elements can be created with the command:
hfk <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:
-
Component Types
-
Deployment Types
-
Missions
-
Services
-
Modules
This will create a blank XML template in the Workspace's library directory. It is also possible to create a new Workspace this way, using hfk workspace create <workspace-name>.
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 element to satisfy the XML model. This includes generating the necessary directory structures and skeleton implementation code for the model element. The hfk generate command is a powerful command that allows developers to concentrate on the mission specific implementation of their Component Types, Services, Missions, and Modules.
|
Creating and generating model elements is a key part of flight software development with Flightkit. To learn more, see the Workflow feature guide. |
Model elements can be generated with the command:
hfk <ElementType> generate <ElementName>
where <ElementType> is the 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:
-
Component Types
-
Missions
-
Services
-
Modules
Generating Documentation
hfk 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.
hfk <ElementType> generate-docs <ElementName>
where <ElementType> is a model element such as component-type or mission.
By default, this will also generate documentation for any target dependencies, although this can be changed by specifiying --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.
Missions
On top of being able to create and generate Missions, hfk can be used to build a Mission. This is the crucial last step in development which provides all of the outputs needed to execute and use the software that’s been written.
Specifically, the build command creates the software binaries for each Deployment instance in the mission.xml, and a Mission Database. This Mission Database fully describes the flight software and enables rapid integration with ground software for command and control.
A Mission can be built using the following command:
hfk mission build <MissionName>
Unless otherwise specified, the artefacts built with this command will be created in the output directory. Optional arguments can be added to build only certain parts or versions of the Mission.
This command can be used with the flag --legacy-scdbs. This generates a legacy {SCDB} for each Deployment within the Mission, capable of being ingested by {BAL}'s {MCS}.
Using Workspaces and Bundles
A Bundle is a snapshot of a Workspace, which enables teams to share library elements. The hfk bundle command allows a user to manage Flightkit Bundles.
|
Note that Bundles cannot be created or required in a Workspace with this command. Instead, see the |
Install & Uninstall Bundles
Bundles on the disk must be installed to make them available to use in Workspaces.
hfk bundle install <path-to-bundle-archive>
By default, the Bundle install directory points to a path that is only writable as root (/usr/share/bright-ascension/helix/flightkit/bundles/). If you cannot write such paths, you can set the HFK_BUNDLES_SOURCE_DIR environment variable to change the path hfk uses to look for or install Bundles. Doing so will also require copying the FlightkitFoundation and FlightkitExtras Bundles to that new path.
Bundles can also be uninstalled when they are no longer needed:
hfk bundle uninstall <BundleName>.
This command can be forced using the -f flag.
Preparing a Workspace
hfk workspace prepare prepares a Workspace so it is ready to be used for development. This checks the Workspace is valid and sets up the gen-one-c and required Bundle dependencies.
Requiring a Bundle
Requiring a Bundle in a Workspace brings in all of the Bundle's elements, allowing them to be used.
hfk workspace bundle require <BundleName>
Unless the Bundle version is specified, hfk will bring in the latest installed version.
|
After a new Bundle requirement has been added, the Workspace must be prepared again using |
Unit Tests
The hfk component-type test command allows a user to build and run Component Type unit tests. For example, hfk component-type test <ComponentName>.
Each test in the ComponentName_Test.c 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.
|
For more information about performing unit tests in Flightkit, see the Unit Testing tutorial. |
Related Documentation
-
How-To Guide: Getting Started
-
Feature Guide: Workflow
-
Tutorial: Unit Testing