.. _dc-plugin-functionalities: Data Collection Plugin ====================================== Data Collection plugin is used for operations regarding Data Collection API. They include the following items: .. contents:: :local: :class: 'this-will-duplicate-information-and-it-is-still-useful-here' :depth: 1 Component types --------------- This plugin is used for operations on DC component types. Currently, it supports the following operations: .. code:: bash 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. .. code:: bash 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. .. code:: bash 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. .. code:: bash 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: .. code:: bash Component type name: 2. If ``--sensing-capabilities`` are not provided, the user is asked to input them: .. code:: bash 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: 3. If ``--telemetry-properties`` filepath is not provided, the user is asked to input them: .. code:: none 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: ... 1. After inputting, the user is asked whether they want to add another one telemetry properties doc. .. code:: bash Do you want to add telemetry properties document for another sensor in this component? [y/n] 5. If ``element-type-id`` not provided, it creates an ``element_type`` document in Orchestra Communications Server with a ``name`` provided by the user. 6. 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: .. code-block:: python { "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: .. code:: none 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. .. code:: bash 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. .. code:: bash 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. .. code:: bash 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. .. code:: bash Do you want to use one of the existing component types? [y/n] 2. 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. .. code:: bash Choose a component type from the list above: 3. If the user answers *no*\ , then they are asked to create a component type and it exits. .. code:: bash Create a component type first with the command `ocli dc component-type create`. 4. If ``--name`` is not provided, the user is asked to input a name: .. code:: bash Component name: 5. If ``element-id`` not provided, it creates an ``element`` document in Orchestra Communications Server with a ``name`` provided by the user. 6. 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. 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}"`` push-telemetry ^^^^^^^^^^^^^^ This command is used to push one telemetry document coming from component's sensor to Orchestra. .. code:: none 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. .. code:: none 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: .. code:: bash ocli dc component get-latest-telemetry 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}"`` get-telemetry ^^^^^^^^^^^^^ This command is used to get telemetry from sensors belonging to the component in a given timeframe. .. code:: bash 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: .. code:: bash 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: .. code:: bash 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. .. code:: bash 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. .. code:: bash 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. 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 an asset. .. code:: bash 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: .. code:: bash Asset name: 2. If ``--component-ids`` are not provided, the user is asked to choose components that will be assigned to the asset. .. code:: bash Choose a component from the list below: 3. 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. .. code:: bash Do you want to add another one? [y/n]. 4. If ``--address`` is not provided, the user is asked to input all the components of the address one after another, so: .. code:: bash Provide (city/street/street no/country/zip) etc. 5. 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. 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}"`` get-latest-telemetry ^^^^^^^^^^^^^^^^^^^^ This command is used to get latest telemetry from sensors belonging to the asset. .. code:: none 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. 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 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. .. code:: none 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: .. code:: bash 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}"``