Skip to main content

​
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
add-credentialsAdd a system’s secret key to the credentials file.
connectivityChange the connectivity mode of a system.
createCreate a new system on the cloud.
create-AMR-systemGenerate AMR - Sample Mobile Robot system required for Quick Start Agent.
create-from-bagCreate a new system on the cloud from a bag file.
create-template-fileAdvanced usage: creates a template file for system creation configuration.
getRetrieve system details for a given ID.
get-sys-confRetrieve system configuration for a given ID.
listList all systems.
replayRun a replay for a given bag uploaded previously to the cloud.
statusProvides the status of the system.
todo-listProvides systems todo list for a given workspace.
updateUpdate a system on the cloud.
deleteDelete a system with a given ID.
Usage: 
./heex system SUBCOMMAND [--help]

​
## How to add a system’s secret key to the credentials file

Usage: 
./heex system add-credentials --system-id <SYSTEM_ID>
This command will fetch the system secret key and add it to the credentials file. The credentials file is required for the Kernel to work properly. This is required in case you create a new system via the Cloud Platform. If you create a new system via the CLI or the heex-installer, you can skip this step. Available flags are:
  • --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].

​
How to change connectivity mode of a system

To change connectivity mode of the system, you can use the following command: Usage: 
./heex system connectivity --system-id <SYSTEM_ID> --mode <MODE>
All options provided in the example are mandatory. Check help to see possible values for the --mode.

​
How to create a new system

2 different ways to create a new system on the cloud, both using the command create:
  • Create a system only by name and some optional flags:
    • --name: Must be unique on your cloud workspace.
    • --description: Description for your system.
    • --system-middleware: System middleware. Check help for available middleware.
    • --system-category: System category. Check help for available templates.
    • --operating_system: Operating system. Defaults to the OS of user executing the command. Check help for available templates.
Usage: 
./heex system create --name "Jane's system" --description "Optional description" --system-middleware 1 --system-category 1
This will create the new system on the Heex Cloud. You can later access this created system via the cloud platform and modify it there (i.e add implementations)
  • Another way to create a system is to use a configuration file that contains all the data you want to generate. To use it:
    • You can generate a template file using the ./heex system create-template-file command, and then fill the given file as you need.
    • Once it is filled, use the create subcommand with the --input-file input pointing to the filled file
    • Note that fields name and type are required, everything else can be removed.
  • Note that whichever way you chose to create your system, you can add the option --output-file which will save the created data info into a file. You’ll have to provide a filepath with a json extension: /path/to/file.json
  • If you provide --json-output, it will disable all logging (except errors), and your command shall only output the result in a json format. Be aware that it is not compatible with ‘—output-file’ option.
Usage: 
./heex system create --input-file /path/to/your/createSystemFilled.json --output-file /path/to/createdSystem.json

​
How to create an AMR sample system

You can generate a sample AMR (Autonomous Mobile Robot) system which is required for Quick Start Agent using the create-AMR-system command. This command will create a pre-configured system on the Heex Cloud Platform with all necessary components for Quick Start Agent to work correctly. This system normally exists when your workspace is created. In case you try to run the Quick Start Agent and it fails, you can use this command to generate a new AMR system. 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.
Usage: 
./heex system create-AMR-system

​
How to create a system from a bag file

You can create a new system on the cloud directly from a bag file using the create-from-bag command. This is useful for the Cloud replay feature. Currently the upload of bag file to be able to run Cloud replay is only supported via the command line interface and not via the web platform. 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.
  • --bag-path: Path or URL of the bag file. Supported formats are: .mcap, .db3 [required].
  • --system-id: System to link the bag file to. This is mandatory if no system name is given. You can use either this or --name.
  • --name: System code name (name display for your system on the UI). If the name of your system contains special characters such as ', enclose with double quotes "". For example, --name "John's dev station". This is mandatory if no system-id is given.
  • --filename: Filename of the bag file. If not provided, the filename will be extracted from the bag path. Please avoid special characters or spaces in the filename.
  • --datasource-creation: If --system-id is provided, you need to set this flag to true if you want to create a datasource from the bag file. If --name is provided, this flag is set to true by default.
  • --output-file: If you’d like to save the created data info into a file, provide its path using this option. Please provide a filepath with a json extension: /path/to/file.json
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. Not compatible with --output-file option.
Usage examples: Create a new system from a bag file and create a datasource from the bag file: 
./heex system create-from-bag --bag-path /path/to/recording.mcap --name "My System"
Link a bag file to an existing system: 
./heex system create-from-bag --bag-path /path/to/recording.db3 --system-id <SYSTEM_ID> --datasource-creation
Save the output to a JSON file: 
./heex system create-from-bag --bag-path https://example.com/recording.mcap --name "Remote System" --output-file /path/to/output.json
ℹ️ Important: bag-id and system-id are required to run a replay, so make sure to save them or use the --output-file option to save the output to a file.
ℹ️ Important: You can upload only one bag file per system. If you want to upload a new bag file, you need to create a new system.

​
How to run a replay from a bag file

After uploading a bag file to the cloud using the create-from-bag command, you can run a replay using the replay command. This will process the bag file on the cloud for a specific system. 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].
  • --bag-id: Bag ID to replay. This is the id of the bag uploaded previously to the cloud with the command ./heex system create-from-bag [required].
  • --output-file: If you’d like to save the created replay info into a file, provide its path using this option. Please provide a filepath with a json extension: /path/to/file.json
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. Not compatible with --output-file option.
Usage: 
./heex system replay --system-id <SYSTEM_ID> --bag-id <BAG_ID>
Save replay information to a file: 
./heex system replay --system-id <SYSTEM_ID> --bag-id <BAG_ID> --output-file /path/to/replay-info.json

​
How to update a system

You can update a system by using a json file. Flags to update a system are --input-file and --system-id which are both required. You can generate a template file using the command below: Usage: 
./heex system create-template-file --type update --folder-path <FOLDER_PATH>
Here’s an example of the template file that shows which values can be updated, you can fill it as you need and remove what you don’t need: 
{
  "systems": [
    {
      "operating_system": "UBUNTU_22_04_LTS_X86_64",
      "__comment_operating_system": "Possible values: ['UBUNTU_20_04_LTS_X86_64', 'UBUNTU_20_04_LTS_ARM', 'UBUNTU_22_04_LTS_X86_64', 'UBUNTU_22_04_LTS_ARM', 'UBUNTU_24_04_LTS_X86_64', 'UBUNTU_24_04_LTS_ARM']",
      "labels": [
        {
          "source": "SYSTEM",
          "key": "",
          "value": ""
        }
      ],
      "triggers": [
        {
          "trigger_id": ""
        }
      ],
      "signals": [
        {
          "signal_id": "",
          "implementation_id": ""
        }
      ],
      "name": "",
      "description": "",
      "middleware": "MIDDLEWARE_TYPE_UNSPECIFIED",
      "__comment_middleware": "Possible values: ['MIDDLEWARE_TYPE_UNSPECIFIED', 'ROS2', 'OTHER']",
      "type": "SYSTEM_TYPE_UNSPECIFIED",
      "__comment_type": "Possible values: ['AUTONOMOUS_MOBILITY_ROBOTS', 'OPEN_ROAD_ADAS_AD', 'SEA', 'AERIAL', 'RAIL', 'LINEAR_INFRASTRUCTURE', 'BUILDINGS_FIXED_STRUCTURES', 'CLOUD_ON_PREMISE_DEVICES', 'DEV_STATION']"
    }
  ]
}
Usage: 
./heex system update --system-id <SYSTEM_ID> --input-file /path/to/updateSystemFilled.json

​
How to get system details

You can retrieve the system details using the command get, which will retrieve system details for a given system ID in the specified output format. The system ID can be found on the web platform or by using command ./heex system list [OPTIONAL-FILTERS]. 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].
  • --output-file: The result will be saved into this provided filepath. The output format is json, so please provide a filepath with that format: /path/to/file.json
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. Not compatible with ‘—output-file’ option.
Usage: 
./heex system get --system-id <SYSTEM_ID> --output-file path/to/your/systemDetails.json
⚠️ Warning: System name or description with special characters: If your system name or description contains special characters (i.e ’ or space), please use double quotes before and after your names. For example, for a system called Jane’s system, provide that as —name “Jane’s system”.

​
How to get system configuration

You can retrieve the system configuration using the command get-sys-conf, which will retrieve system configuration for a given system ID in the specified output format. Options are the same as get command. See the usage example below: Usage: 
./heex system get-sys-conf --system-id <SYSTEM_ID> --output-file path/to/your/sysConf.json

​
How to get system status

You can retrieve the status of a system using the command status. This command will retrieve the status of a given system ID in the specified output format. Information that will be provided is:
  • Agent version
  • Last OTA update
  • System status
  • Signal details
Usage: 
./heex system status --system-id <SYSTEM_ID> --output-file path/to/your/filledConfigFile.json

​
How to get system to-do list for a given ID

You can retrieve the to-do list of systems for a given workspace with the corresponding status using the command todo-list. You can filter the result by providing a system ID and/or system status. If a system status is given, for example , --system-status TO_CODE, only systems with the given status will be returned and you’ll be able to see the list of systems that need to be coded yet. 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. Multiple can be provided, example: --system-id sysId1 --system-id sysId2
  • --system-status: Filter by system status.
  • --details: Show details of each system implementations status included.
  • --output-file: The result will be saved into this provided filepath. The output format is json, so please provide a filepath with that format: /path/to/file.json
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. Not compatible with ‘—output-file’ option.
If --details is provided, the output will be a list of systems including their signal details. Otherwise, it will display only system id, status and agent version when available. Usage: 
./heex system todo-list --system-id <SYSTEM_ID>  --system-status <SYSTEM_STATUS> --output-file path/to/your/systemsToDoList.json

​
How to get list of systems with details for a given workspace

You can retrieve the list of systems for a given workspace with the corresponding status using the command list. Same as for todo-list, you can filter the result by providing a system ID and/or system status. The result will be a list of systems with details. 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. Multiple can be provided, example: --system-id sysId1 --system-id sysId2
  • --system-status: Filter by system status.
  • --output-file: The result will be saved into this provided filepath. The output format is json, so please provide a filepath with that format: /path/to/file.json
  • --json-output: Disables all logging (except errors), and your command shall only output the result in a json format. Not compatible with ‘—output-file’ option.
Usage: 
./heex system list --system-id <SYSTEM_ID>  --system-status <SYSTEM_STATUS> --output-file path/to/your/systemsList.json

​
How to delete a system

To be able to delete a system you need to provide a system-id and use the command below. 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].
Usage: 
./heex system delete --system-id <SYSTEM_ID>

​
Getting Help

./heex system --help
./heex system add-credentials --help
./heex system connectivity --help
./heex system create --help
./heex system create-AMR-system --help
./heex system create-from-bag --help
./heex system create-template-file  --help
./heex system get --help
./heex system get-sys-conf --help
./heex system list --help
./heex system replay --help
./heex system status --help
./heex system todo-list --help
./heex system update --help
./heex system delete --help