Data Collection Plugin¶

Data Collection plugin is used for operations regarding Data Collection API. They include the following items:

Component types ¶

This plugin is used for operations on DC component types. Currently, it supports the following operations:

ocli dc component-type --help

Usage: ocli dc component-type [OPTIONS] COMMAND [ARGS]

Options:
  --help    Show this message and exit.

Commands:
  get       Get a component type by id.
  list      List all component types with pagination.
  create    Create a component type.

Command get requires specifying which component_type_id to get, the specific operation can be found by calling --help on the command. All available commands have a non-required option -m/--mode which 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.

get¶

This command is used to get information about one component type with a specified id.

ocli dc component-type get --help

Usage: ocli dc component-type get [OPTIONS] COMPONENT_TYPE_ID

  Get a component type by id.

Options:
  -m, --mode       Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help           Show this message and exit.

You have to specify the component_type_id as an argument at the end of the command. 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 situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

list¶

This command is used to get information about all component types from a specified tenant with pagination.

ocli dc component-type list --help

Usage: ocli dc component-type list [OPTIONS]

  List all component types with pagination.

Options:
  -l, --limit      Maximum number of documents to return, default to 0 [not required][int].
  -o, --offset     Number of documents to skip from the beginning of the collection, default to 0 [not required][int].
  -m, --mode       Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help           Show this message and exit.

Options limit and offset are used to build pagination. If not specified, all the documents are returned. 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 situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

create¶

This command is used to 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:

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

Component type name:

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:

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 the 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:
...

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]

If element-type-id not provided, it creates an element_type document in Orchestra Communications Server with a name provided by the user.
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 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 situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

Components ¶

This plugin is used for operations on DC components. Currently it supports the following operations:

ocli dc component --help

Usage: ocli dc component [OPTIONS] COMMAND [ARGS]

Options:
  --help               Show this message and exit.

Commands:
  get                  Get a component by id.
  list                 List all components with pagination.
  create               Create a component.
  push-telemetry       Push one telemetry document coming from component's sensor to Orchestra.
  get-latest-telemetry Get the latest telemetry data coming from component's sensors.
  get-telemetry        Get telemetry data coming from component's sensors in a given timeframe.

Commands get, get-latest-telemetry and get-telemetry require specifying which component_id to get, the specific operation can be found by calling --help on those commands. All available commands have a not required option -m/--mode which 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.

get¶

This command is used to get information about one component with a specified id.

ocli dc component get --help

Usage: ocli dc component get [OPTIONS] COMPONENT_ID

  Get a component by id.

Options:
  -m, --mode           Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help               Show this message and exit.

You have to specify the component_id as an argument at the end of the command. 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 situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

list¶

This command is used to get information about all components from a specified tenant with pagination.

ocli dc component list --help

Usage: ocli dc component list [OPTIONS]

  List all components with pagination.

Options:
  -l, --limit      Maximum number of documents to return, default to 0 [not required][int].
  -o, --offset     Number of documents to skip from the beginning of the collection, default to 0 [not required][int].
  -m, --mode       Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help           Show this message and exit.

Options limit and offset are used to build pagination. 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 situation it will display such message: "Error from Data Collection. Status code {response.status_code}"

create¶

This command is used to 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:

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]

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:

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`.

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

Component name:

If element-id not provided, it creates an element document in Orchestra Communications Server with a name provided by the user.
Creates a component document in 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.

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

push-telemetry¶

This command is used to push one telemetry document coming from component’s sensor to Orchestra.

ocli dc component push-telemetry --help

Usage: ocli dc component push-telemetry [OPTIONS] DATA

  Push one telemetry document coming from component's sensor to Orchestra.

Options:
  -t, --ts             Timestamp of the measurement [required].
  -e, --element-id     Element id of the element from which the measurement comes [required].
  -m, --mode           Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help               Show this message and exit.

This command pushes one telemetry document for an element with a given id to Orchestra Communications Server through _push_telemetry Orchestra SDK method.

As an argument, you have to input data either as a filepath to a json file or input a json directly in the cli, e.g. {“temperature”: 23}.

Options -t/--ts, -e/--element-id describe the data coming from the component. 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 situation it will display such message: "Error from Data Collection. Status code {response.status_code}"

get-latest-telemetry¶

This command is used to get the latest telemetry from sensors belonging to the component.

ocli dc component get-latest-telemetry --help

Usage: ocli dc component get-latest-telemetry [OPTIONS] COMPONENT_ID

  Get the latest telemetry data coming from component's sensor(s).

Options:
  -m, --mode                   Defines the output mode. Can be 'normal', 'json' or  'csv' [not required].
  --help                       Show this message and exit.

This command returns the latest telemetry documents from sensors belonging to the component..

Example:

ocli dc component get-latest-telemetry

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

get-telemetry¶

This command is used to get telemetry from sensors belonging to the component in a given timeframe.

ocli dc component get-telemetry --help

Usage: ocli dc component get-telemetry [OPTIONS] COMPONENT_ID

  Get telemetry data coming from component's sensor(s).

Options:
  -s, --sensing-capabilities Sensing capabilities from which a user wants to get data, separated by commas [not required]. If not specified, the data from all of the component's sensors will be fetched.
  --ts-from              Start timestamp to get the data in the ISO format [required].
  --ts-to                End timestamp to get the data in the ISO format [required].
  -m, --mode                  Defines the output mode. Can be 'json' or  'csv' [not required].
  --help                      Show this message and exit.

This command returns the telemetry documents from sensors belonging to the component, with specified capabilities (if specified), in a given timeframe.

Example:

ocli dc component get-telemetry -sc TEMPERATURE,BRIGHTNESS -tf 2023-06-25T17:09:56.868+00:00 -tt 2023-07-25T17:09:56.868+00:00

You have to specify the component_id as an argument at the end of the command. Option -m/--mode specifies how to print the result. It can be set to 'json'/'csv' and the result will be printed in the desired format. The 'json' mode is the default option.

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

Assets ¶

This plugin is used for operations on DC assets. Currently, it supports the following operations:

ocli dc asset --help

Usage: ocli dc asset [OPTIONS] COMMAND [ARGS]

Options:
  --help          Show this message and exit.

Commands:
  get             Get an asset by id.
  list            List all assets with pagination.
  create          Create an asset.
  get-latest-telemetry     Get the latest telemetry data coming from asset's sensors.
  get-telemetry   Get telemetry data coming from asset's sensors in a given timeframe.

Commands get, get-insight and get-telemetry require specifying which asset_id to get, the specific operation can be found by calling --help on those commands. All available commands have a not required option -m/--mode which 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.

get¶

This command is used to get information about one asset with a specified id.

ocli dc asset get --help

Usage: ocli dc asset get [OPTIONS] ASSET_ID

  Get an asset by id.

Options:
  -m, --mode       Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help           Show this message and exit.

You have to specify the asset_id as an argument at the end of the command. 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 situation it will display a message: "Error from Data Collection. Status code {response.status_code}"

list¶

This command is used to get information about all assets from a specified tenant with pagination.

ocli dc asset list --help

Usage: ocli dc asset list [OPTIONS]

  List all assets with pagination.

Options:
  -l, --limit      Maximum number of documents to return, default to 0 [not required][int].
  -o, --offset     Number of documents to skip from the beginning of the collection, default to 0 [not required][int].
  -m, --mode       Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help           Show this message and exit.

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

create¶

This command is used to 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:

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

Asset name:

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:

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].

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.

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

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}"

get-latest-telemetry¶

This command is used to get latest telemetry from sensors belonging to the asset.

ocli dc asset get-latest-telemetry --help

Usage: ocli dc asset get-latest-telemetry [OPTIONS] ASSET_ID

  Get the latest telemetry data coming from asset's sensors.

Options:
  -m, --mode        Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help            Show this message and exit.

This command returns the latest telemetry documents from sensors belonging to the asset.

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

get-telemetry¶

This command is used to get telemetry from sensors belonging to the asset in a given timeframe.

ocli dc asset get-telemetry --help

Usage: ocli dc asset get-telemetry [OPTIONS] ASSET_ID

  Get telemetry data coming from asset's sensors in a given timeframe.

Options:
  -s, --sensing-capability Sensing capability from which a user wants to get data [required].
  --ts-from            Start timestamp to get the data in the ISO format [required].
  --ts-to              End timestamp to get the data in the ISO format [required].
  -l, --limit               Maximum number of documents to return, default to 0 [not required][int].
  -o, --offset              Number of documents to skip from the beginning of the collection, default to 0 [not required][int].
  -m, --mode                Defines the output mode. Can be 'normal', 'json' or 'csv' [not required].
  --help                    Show this message and exit.

This command returns the telemetry documents from sensors belonging to the asset, with a specified capability, in a given timeframe.

Example:

ocli dc asset get-telemetry -sc TEMPERATURE -tf 2023-06-25T17:09:56.868+00:00 -tt 2023-07-25T17:09:56.868+00:00 -l 10 -o 10

You have to specify the asset_id as an argument at the end of the command. Options limit and offset are used to build pagination. If not specified, all the documents are returned. 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}"

Data Collection Plugin¶

Component types¶

get¶

list¶

create¶

Components¶

get¶

list¶

create¶

push-telemetry¶

get-latest-telemetry¶

get-telemetry¶

Assets¶

get¶

list¶

create¶

get-latest-telemetry¶

get-telemetry¶

Component types ¶

Components ¶

Assets ¶