​
Prerequisites

  • Have a Heex CLI
  • Have an API_KEY. Should be accessible in your personnal space on the heex cloud platform. If you already logged-in you don’t need to add the Api-Key in your command line.

​
Usage

SubcommandDescription
downloadDownload SDK package.
build-samplesBuild the SDK C++ samples.
generate-implementations-fileWill generate the implementations.json file based on all scripts you have in the implementations folder.
runStart the HeexSdk.
set-systemSet credentials and download systemConf.
replayPull a Docker image and run a bag play.
Usage: 
./heex sdk SUBCOMMAND [--help]

​
How to download the SDK

Usage: 
./heex sdk download
This command downloads the SDK that corresponds to the detected platform. The downloaded archive file will be named Heex_SDK_<version>_<os_version>_<arch_type>.zip. For example for the SDK version 2024_11_1 and Ubuntu 22.04 x86, the archive name will be Heex_SDK_2024_11_1_Ubuntu_22.04_x86_64.zip. The flags that are available to achieve this command are the following:
  • --api-key: Add your user API_KEY which can be found on the cloud [required]. No need to provide if you have an active userconfig.
  • --version: The version of the SDK to download (e.g., ‘2024.2.1’).
  • --verbose: Enable verbose output.
  • --output-dir: The output path folder where the SDK will be saved [Optional].
  • --unzip: Unzip the downloaded SDK package [Optional].
When using the unzip option, the output folder name will be name Heex_SDK_<version>.

​
How to build the SDK C++ samples

Usage: 
./heex sdk build-samples
This command builds the SDK C++ samples. By default, all build operations use 1 job. For faster operations, you can specify the number of parallel jobs with —jobs flag. The generated executables are located in the folder samples/cpp. The optional flags that are available to achieve this command are the following:
  • --path-to-sdk: If you don’t run from inside the SDK folder, you have to provide the /path/to/sdk/folder.
  • --jobs: Allow building with N jobs at once; default is 1 job.
MCAP samples: By default, the MCAP samples are disabled and will not be built. To activate the MCAP samples build, edit the file samples/CMakeLists.txt and uncomment the MCAP lines. Additionnal dependencies are required and will be automatically downloaded during the build.

​
Generating the implementation.json file

If you intend to run our solution within the packaged SDK, you may want to automatically handle the running of your implementations. To do so, you’ll need to generate a implementations.json file which shall be generated using following command: 
./heex sdk generate-implementations-file --path-to-sdk /path/to/sdk/folder
📝 Note: Only implementations located inside the implementations folder are handled, any other script you have outside of this folder, you shall have to handle manually.

​
How to set up a system and launch Heex

The command ./heex sdk set-system will define system credentials and download the systemConf to the default path ~/<Heex_SDK>/kernel/systemConfs/systemConf.json. Available options:
  • --api-key: Add your user API_KEY which can be found on the cloud [required]. No need to provide if you have an active userconfig.
  • --system-id: ID of the involved system [required].
  • --path-to-sdk: If you don’t run from inside a unzipped sdk package, provide the path to its root.
Usage: 
./heex sdk set-system --system-id <SYSTEM_ID> --path-to-sdk <Heex_SDK>

​
How to run the solution in SDK mode

The command ./heex sdk run will generate the implementations.json and launch Heex. Usage: 
./heex sdk run --path-to-sdk <Heex_SDK> --config-path /path/to/systemConf.json
The optional flags that are available to achieve this command are the following:
  • --path-to-sdk: If you don’t run from inside the SDK folder, you have to provide the /path/to/sdk/folder.
  • --api-key: This one is mandatory the very first time you execute the SDK for your system (it is needed to fetch the credentials of this system, they are saved after the first run). It is also mandatory if you use the --system-id option. No need to provide if you have an active userconfig.
  • --config-path: If you have the systemConf.json already located inside the kernel/systemConfs/ folder, then you don’t need to specify it.
  • --system-id: If you don’t have the systemConf.json yet, you may provide the system-id in order to download the systemConf.json from the cloud. Api Key is required for this.

​
How to replay a bag and watch events triggered for a given system

The command ./heex sdk replay will pull a Docker image, install the latest Agent and run a replay on the given bag to watch events that are generated for a given system. Replay will use the default bag if none is provided. The bag shall be replayed in a accelerated speed. Flags available:
  • system-id: The system ID to use. [Required]
  • bag-path: The path to the bag to play.
  • os-version: The OS version to use. [default: Ubuntu_24.04]
  • arch-type: Docker image architecture to use for the replay. [default: x86]
  • api-key: The API_KEY to use. [Required]. No need to provide if you have an active userconfig.
  • api-url: Heex Cloud API base URL to use for fetching and reporting events.
  • --custom-topic-folder: If your bag contains custom topics, provide the full path to folders containing the custom topic definitions (ie with the CMakelists, package.xml, .msg and .srv files). Multiple folders can be provided: —custom-topic-folder /path/to/folder1 —custom-topic-folder /path/to/folder2
  • --verbose: Enable verbose output. If not set, logs are saved to file and only progress bars are shown.
Once the bag is played, you can watch the evolution of the bag replay and the events that are generated. Note that if you have uploaded an Agent onto your system, and this Agent does not contain the implementations/builtin/RDABagReplay file, the replay of the bag shall be ran using the command ros2 bag play, which’ll be much slower at execution. Usage: 
/heex sdk replay --system-id <SYSTEM_ID>

​
Getting Help

./heex sdk --help
./heex sdk download --help
./heex sdk build-samples --help
./heex sdk generate-implementations-file --help
./heex sdk run --help
./heex sdk set-system --help
./heex sdk replay --help