​
Prerequisites

  • Have a Heex CLI
  • Have a USER_SECRET_KEY. Should be accessible in your personnal space on the heex cloud platform.

​
Usage

SubcommandDescription
addAdd a new Data Source to a given system.
createCreates a Data Source.
create-template-fileCreates a template file that can be used to create a Data Source.
getGet details of a Data Source for a given ID.
listProvides a list of available Data Sources.

Usage:

./heex datasource SUBCOMMAND [--help]

​
How to create a new Data Source

There are three ways to create a new Data Source. You can either create it from a bag, from a json file or by providing a name and/or a description. The flags that are available to achieve this command are the following:

  • --api-key: Provide your USER_SECRET_KEY. It is mandatory if you don’t use the --info-only flag.
  • --from-bag: The path to the bag file you want to extract the signals from.
  • --from-file: The path to the json file you want to extarct info about Data Sources and signals.
  • --system-id: System id on which the Data Source will be created. It is mandatory if you don’t use the --info-only flag.
  • --datasource-name: Data Source name.
  • --description: Data Source description. This is optional.
  • --info-only: If set, it will only list the signals that would be created into your terminal, without generating them on the cloud.
  • --cannot-contain: This option creates a ‘cannot contain’ filter on the topic names we shall extract. Any topic name containing one of these keywords shall not be extracted. Multiple can be given: --cannot-contain key1 --cannot-contain key2
  • --must-contain: This option creates a ‘must contain’ filter on the topic names we shall extract. Any topic name NOT containing one of these keywords shall not be extracted. Multiple can be given: --must-contain key1 --must-contain key2

If you just want to create a datasource without signals, you can specify the datasource name. You can also provide a description, but it is not mandatory. Here’s an example of how to create a new Data Source by providing a name and a description:

Usage:

./heex datasource create --api-key <USER_SECRET_KEY> --datasource-name "My Data Source" --description "This is my data source"

Second way to create a Data Source is by providing a bag, this command allows you to:

  1. Extract all the topics out of the bag.
  2. Create a Data Source.
  3. Bind it to your system.
  4. Create each individual signal and link them to the Data Source.
  5. Update your system’s implementation to include the Data Source.

Usage:

./heex datasource create --from-bag <BAG_PATH> --api-key <USER_SECRET_KEY> --system-id <SYSTEM_ID>

📝 Note: Custom Topics

If your bag contains custom packages/messages that are specific to your own environment, please make sure that you have sourced all the message types you mean to extract in the terminal you call the command from.

The third way to create a new Data Source is by providing a json file. First you need to create the json file, by following the format below:

{
  "data_sources": [
    {
      "name": "datasource1",
      "description": "description for datasource1",
      "system_id": "system_id1",
      "signals": [
        {
          "name": "signal1",
          "ros_topic_type": "ros_type",
          "type": 0,
          "unit": 0
        },
        {
          "name": "signal2",
          "ros_topic_type": "ros_type",
          "type": 1,
          "unit": 1
        }

      ]
    },
    {
      "name": "datasource2",
      "description": "description for datasource2",
      "system_id": "",
      "signals": [
        {
          "name": "signal1",
          "ros_topic_type": "ros_type",
          "type": 1,
          "unit": 0
        }
      ]
    }
  ]
}

Be aware that field name is mandatory for data sources and for signals. If not provided, the data source or signal will be skipped. If a system Id is provided, the data source will be bound to that system, otherwise the data source will be created but not bound to any system. Example of how to create a new data source from a json file:

Usage:

./heex datasource create --from-file create_datasource_template.json --api-key <USER_SECRET_KEY>

Check the section below to see how you can create a template file to use later.

​
How to create a template file

If you want to create a Data Source using a file, you can create a template file using the command below:

Usage:

./heex datasource create-template-file --folder-path /path/to/directory

If the command was successful, you will see a new file named create_datasource_template.json in the specified directory or current working directory if no path was specified. This file contains a basic template for creating a new data source. You can edit this file to add or modify the data source properties. If there is a field that is not required, you can leave it empty or with the default value. You can add as many data sources and signals as you want to the file.

​
How to add a Data Source to a System

To add a data source to a system, you can use the command add. Available flags are:

  • --datasource-id: The ID of the Data Source you want to add. Multiple can be specified: --datasource-id ID1 --datasource-id ID2.
  • --system-id: The ID of the System you want to add the Data Source to.

Usage:

./heex datasource add --datasource-id <datasource_ID> --api-key <USER_SECRET_KEY>  --system-id <SYSTEM_ID>

​
How to update a Data Source

To update a data source, you can use the command update. Available flags are:

  • --datasource-id: The ID of the Data Source you want to update.
  • --datasource-name: Data Source name to update.
  • --description: Data Source description to update.

Usage:

./heex datasource update --datasource-id <datasource_ID> --api-key <USER_SECRET_KEY> --datasource-name <NEW_NAME> --description <NEW_DESCRIPTION>

​
How to get Data Source details for a given Data Source Id

You can get the details of a Data Source if you provide an datasource-id, see example below:

Usage:

./heex datasource get --datasource-id <datasource_ID> --api-key <USER_SECRET_KEY> --output-file <OUTPUT-FILE>

This can be useful when you want to get the details of an Data Source that you have previously created or if you want to modify a Data Source.

​
How to list Data Source infos

This command allows you to retrieve datasources based on Data Source IDs or Data Source name. Note that all filters are optional, if no filters are provided, it will return all datasources found on page 1. Keep in mind that only a filter at a time can be applied, so if Data Source id is used , datasource-name cannot be used.

Available subcommands:

  • --api-key: mandatory USER_SECRET_KEY.
  • --datasource-id: The ID of the Data Source you want to retrieve. Multiple can be specified: --datasource-id ID1 --datasource-id ID2. It is exclusive with option name.
  • --name: The name of the Data Source to retrieve. It is exclusive with datasource-id option.
  • --output-file: If set, it’ll provide the result in a json format in a file generated at given path. Make sure you provide the ‘.json’ extension.

Usage:

./heex datasource list --api-key <USER_SECRET_KEY> --datasource-id <DATASOURCE_ID1> --datasource-id <DATASOURCE_ID2>

​
Getting Help

./heex datasource --help
./heex datasource add --help
./heex datasource create --help
./heex datasource create-template-file --help
./heex datasource get --help
./heex datasource list --help
./heex datasource update --help