Custom Dashboard in Data Collection

In order to prepare a functional Data Collection dashboard, you need to create a few elements in the following order:

  • Component type,

  • Component,

  • Asset.

In this tutorial, you will be instructed how to do it using Orchestra CLI DC Plugin.

After completing all of the steps below, you will be able to see the asset with newly created component(s) on the dashboard on the platform.

On this page:

1. Create a component type

2. Create a component

3. Create an asset

1. Create a component type

$ ocli dc component-type create --help

Usage: ocli dc component-type create [OPTIONS]

  Create a component type.

Options:
  -n, --name                 Name of the component type [not required]. If not specified, the user will be prompted to input it in the flow.
  -e, --element-type-id      ID of an element type connected to the component type [not required]. If not specified, it will be created in the flow.
  -s, --sensing-capabilities Sensing capabilities supported by this component type, separated by commas [not required]. If not specified, the user will be prompted to input it in the flow.
  -p, --telemetry-properties Filepath to a file containing a list of telemetry properties where each doc describes a format of the data sent by one sensor [not required]. If not specified, the user will be prompted to input it in the flow.
  -m, --mode                 Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help                     Show this message and exit.

This command invokes a set of actions:

  1. If --name is not provided, the user is asked to input a name:

Component type name:

  1. If --sensing-capabilities are not provided, the user is asked to input them:

Please provide supported sensing capabilities separated by commas.

Allowed values are:

TEMPERATURE, HUMIDITY, BRIGHTNESS, NOISE_POLLUTION, PM_1, PM_2_5, PM_10, VIBRATIONS, LUMINAIRE_STATE, SPEAKER_STATE, CO, CO_2, PRESSURE, POWER_3_PHASE, VOLTAGE_3_PHASE, CURRENT_3_PHASE, PHASE_3_PHASE, AMBIENT_LIGHT, BATTERY_VOLTAGE, PRESENCE, ACCELEROMETER_3D_G, NO, NO_2, O3, H2S, SO_2, TVOC

Example:

TEMPERATURE,BRIGHTNESS,O3

Provide supported sensing capabilities:

  1. If --telemetry-properties filepath is not provided, the user is asked to input them:

Now please specify the format of the data sent by your device's sensors. You will be asked to provide necessary information for each sensor separately.

Add telemetry properties of the first sensor.

Provides sensing capability (allowed values: TEMPERATURE, HUMIDITY, BRIGHTNESS, NOISE_POLLUTION, PM_1, PM_2_5, PM_10, VIBRATIONS, LUMINAIRE_STATE, SPEAKER_STATE, CO, CO_2, PRESSURE, POWER_3_PHASE, VOLTAGE_3_PHASE, CURRENT_3_PHASE, PHASE_3_PHASE, AMBIENT_LIGHT, BATTERY_VOLTAGE, PRESENCE, ACCELEROMETER_3D_G, NO, NO_2, O3, H2S, SO_2, TVOC):

Telemetry name is used to distinguish between different sensors, for example when one component type has two sensors of the same sensing capability (e.g. two TEMPERATURE sensors).

Telemetry name:

Data unit (allowed values: °C, %, µg/m3, mg/m³, dB, dBm, % RH, m/s², ppm, kPa, hPa, Pa, V, W, A, °, lx, g, MB):

Data kind (allowed values: ANY, STRING, INTEGER, FLOAT, BOOLEAN, MAP, ARRAY, INT_ENUM, DATE):

Post processor unit:

Parameters describe the format of the data and where exactly the value is placed in the data document. It can be one of the three types. You can find their descriptions with examples here:

https://dc.orchestra.cthings.co/redoc#tag/Component-types/operation/Create_a_component_type_v1_components_types__post

Choose parameters type from the following - ParamSingleKey, ParamMultipleKey, ParamGroupKey:

Key:
...

  1. After inputting, the user is asked whether they want to add another one telemetry properties doc.

Do you want to add telemetry properties document for another sensor in this component? [y/n]

  1. If element-type-id not provided, it creates an element_type document in Orchestra Communications Server with a name provided by the user.

  2. Creates a component_type document in Data Collection database with values provided by the user. The capabilities parameter in the API request body should be an object like so:

{
    "kind": "SENSOR",
    "sensing_capabilities": sensing capabilities provided by the user
}

Option -m/--mode specifies how to print the result. It can be set to 'normal'/'json'/'csv' and the result willbe printed in the desired format. The 'normal' mode pretty-prints results in the form of a table, it is the default option.

This command can fail if it fails to create or get data from Data Collection, in such situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

2. Create a component

ocli dc component create --help

Usage: ocli dc component create [OPTIONS]

  Create a component.

Options:
  -n, --name               Name of the component [not required]. If not specified, the user will be prompted to input it in the flow.
  -e, --element-id         ID of an element connected to the component [not required]. If not specified, it will be created in the flow.
  -c, --component-type-id  Id of the component type [not required]. If not specified, the user will be prompted to choose it in the flow.
  -m, --mode               Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help                   Show this message and exit.

This command invokes a set of actions:

  1. If --component-type-id is not provided, the user is asked to choose a component type that will be assigned to the component.

Do you want to use one of the existing component types? [y/n]

  1. If the user answers yes, then the command List components is invoked in the background and a list of components is displayed to the user and they are asked to choose one of them.

Choose a component type from the list above:

  1. If the user answers no, then they are asked to create a component type and it exits.

Create a component type first with the command `ocli dc component-type create`.

  1. If --name is not provided, the user is asked to input a name:

Component name:

  1. If element-id is not provided, it creates an element document in Orchestra Communications Server with a name provided by the user.

  2. Creates a component document in the Data Collection database with values provided by the user. If component-type-id was not provided at the beginning, the id of a chosen component type is used.

Option -m/--mode specifies how to print the result. It can be set to 'normal'/'json'/'csv' and the result will be printed in the desired format. The 'normal' mode pretty-prints results in the form of a table, it is the default option.

This command can fail if it fails to get data from Data Collection, in such a situation it will display such message: "Error from Data Collection. Status code {response.status_code}"

3. Create an asset

ocli dc asset create --help

Usage: ocli dc asset create [OPTIONS]

  Create an asset.

Options:
  -n, --name          Name of the asset [not required]. If not specified, the user will be prompted to input it in the flow.
  -c, --component-ids Ids of components assigned to this asset, separated by commas [not required]. If not specified, the user will be prompted to choose the components in the flow.
  -a, --address       Filepath to a file containing an address of the asset [not required].
  -m, --mode          Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help              Show this message and exit.

This command invokes a set of actions:

  1. If --name is not provided, the user is asked to input a name:

Asset name:

  1. If --component-ids are not provided, the user is asked to choose components that will be assigned to the asset.

Choose a component from the list below:

  1. After the user chooses a component typing its id, they will be asked whether they would like to add another one. After answering yes, they can input another id, and if they answer no, they go to another step.

Do you want to add another one? [y/n].

  1. If --address is not provided, the user is asked to input all the components of the address one after another, so:

Provide (city/street/street no/country/zip) etc.

  1. Creates an asset document in the Data Collection database with values provided by the user. If component-ids were not provided as a parameter, the ids of newly created components are used.

Option -m/--mode specifies how to print the result. It can be set to 'normal'/'json'/'csv' and the result will be printed in the desired format. The 'normal' mode pretty-prints results in the form of a table, it is the default option.

This command can fail if it fails to create or get data from Data Collection, in such a situation it will display a message: "Error from Data Collection. Status code {response.status_code}"