Prerequisites

  • Have a Heex CLI
  • Have a USER_SECRET_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
getRetrieve signal details for the given signal id.
listRetrieve signal list for the provided filters.
updateUpdate an existing signal.
createCreates a new signal.
create-template-fileCreates an empty template file that can be used as input for the create or update command.
deleteDelete a signal with a given ID.

Usage:

./heex signal SUBCOMMAND [--help]

How to get signal details

You can get the details of a signal if you provide a signal-id, see example below:

./heex signal get --signal-id <SIGNAL-ID> --api-key <USER_SECRET_KEY> --output-file <OUTPUT-FILE>

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

How to get signal list

You can get list of all available signals in a given workspace. Several filters are available to narrow down the results. The flags available to filter the results are:

  • --system-id ID of the involved system.
  • --trigger-id ID of the involved trigger.
  • --datasource-id ID of the involved datasource. Multiple can be given: e.g. —datasource-id 1 —datasource-id 2 —datasource-id 3
  • --signal-id ID of the involved signal. Multiple can be given: e.g. —signal-id 1 —signal-id 2 —signal-id 3
  • --signal-name Name of the signal to retrieve details for.
  • --datasource-name Name of the datasource to retrieve details for.
  • --owner-id Owner ID of the signal to retrieve details for.
  • --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

The result can be saved in a json file by using the --output-file flag. If the provided path doesn’t exist, it will be created. See example below where several filters can be used at the same time:

./heex signal list --system-id <SYSTEM_ID1>  --system-id <SYSTEM_ID2>  --datasource-id <DATASOURCE_ID1>  --datasource-id <DATASOURCE_ID2> --api-key <USER_SECRET_KEY> --output-file <OUTPUT-FILE>

How to create signals

There are 2 possible ways to create a new signal, either by providing a json file with the signal details or by providing the details directly in the command line. When using a file you can create multiple signals, otherwise you can create only one signal at the time.

The flags that are available to achieve this command are the following:

  • --api-key: Provide your USER_SECRET_KEY.
  • --datasource-id: ID of the involved datasource [required if not using a file].
  • --signal-name: Signal name to create [required if not using a file].
  • --signal-type: Type of the signal. Check help for available types [required if not using a file].
  • --signal-unit: Unit of the signal. Check help for available units [optional].
  • --ros-topic-type: Type of ros topic [optional].
  • --input-file: Full path to the input file to use, it has to be a .json file, example : /path/to/input.json

To create a signal by providing options, see example below:
Usage:

./heex signal create --api-key <USER_SECRET_KEY> --datasource-id <DATASOURCE_ID> --signal-name <SIGNAL_NAME> \
--signal-type <SIGNAL_TYPE> --signal-unit <SIGNAL_UNIT>

If you don’t know the Data Source Id, you can check Get Data Source to get it.

Create signals using a json file If you want to create multiple signals at the same time, you can use a json file with the signal details. You can use command below to generate a template file. If no --folder-path is provided, the template will be saved in the current directory.

Usage:

./heex signal create-template-file --folder-path <FOLDER_PATH>

Once the template file is generated, you can fill the details and use it as input file. See an example of file with 2 signals below:

{
  "signals": [
    {
      "name": "CreateSignalWithFile1",
      "type": "BOOLEAN",
      "datasource_id": "d-xxxxxxxx"
    },
    {
      "name": "CreateSignalWithFile2",
      "type": "STRING",
      "ros_topic_type": "",
      "datasource_id": "d-xxxxxx",
      "unit": "METER"
    }
  ]
}

Usage:

./heex signal create --api-key <USER_SECRET_KEY> --input-file create_signal_template.json

Be aware that name, type and datasource_id are required fields, other fields can be removed. To see possible values for type and unit you can use the --help flag.

How to update a signal

Same as for the creation, there are 2 possible ways to update a signal, by providing details in the command line or by using a json file. Either way, you can update only one signal at a time. Flags to update a signal are the same as for the creation, with the addition of --signal-id to specify the signal to update, which is required. If you want to update a signal using a json file, you can generate a template file using command below:

Usage:

./heex signal create-template-file --type update --folder-path <FOLDER_PATH>

Once the template file is generated, you can fill the details and use it as input file:

Usage:

./heex signal update --api-key <USER_SECRET_KEY>  --signal-id <SIGNAL_ID> --input-file update_signal_template.json

If you want to update signal by providng details in the command line, you can use the following command:

Usage:

./heex signal update --api-key <USER_SECRET_KEY> --signal-id <SIGNAL_ID> --datasource-id <DATASOURCE_ID> --signal-name <SIGNAL_NAME> \
--signal-type <SIGNAL_TYPE> --signal-unit <SIGNAL_UNIT>

How to delete a signal

To be able to delete a signal you need to provide a signal-id. If the signal is linked to any trigger, it is not possible to delete: you need to unlink it from the trigger(s) first and then try again.

Usage:

./heex signal delete --api-key <USER_SECRET_KEY> --signal-id <SIGNAL_ID>

Getting Help

./heex signal --help
./heex signal create --help
./heex signal update --help
./heex signal get --help
./heex signal list --help
./heex signal create-template-file --help
./heex signal delete --help