.. _example-onboarding: Create a mock dashboard ================================================ In this tutorial, you will be guided on how to create an example dashboard on **Data Collection** platform. **The steps include:** 1. :ref:`creating-component-types` 2. :ref:`creating-components` 3. :ref:`creating-an-asset` Preconditions ------------- * active subscription of **Orchestra with Data Collection**, * an account on **Identity Platform** with access to the tenant and to **Data Collection** platform on this tenant, * Orchestra CLI installed (see :ref:`ocli-setup`). Final result ------------- After completing all of the steps in this manual, you will be able to see the following dashboard: .. image:: images/dashboard-final.png :alt: Data Collection: final dashboard :width: 100% :align: center Steps ----- 1. If you have your tenant with an active **Orchestra with DC subscription**, log in to **Data Collection** platform and choose your tenant. You should see the platform with no devices that should look like this: .. image:: images/dashboard-empty.png :alt: Data Collection: empty dashboard :width: 100% :align: center Now we can proceed to create an example DC dashboard. 2. First, authenticate yourself with Orchestra CLI using the command below: .. code:: bash ocli auth login 3. Decide on the data format sent by your sensors. Later, we will create 4 components and elements providing different data. Here are our sample documents: **Element 1** .. code-block:: json {"temperature": 19, "humidity": 52} **Element 2** .. code-block:: json {"x": -2.1575, "y": -10.1205, "z": -0.1961} **Element 3** .. code-block:: json {"event": "Presence detected"} .. _creating-component-types: Creating component types ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 4. Create your first **component types** that will show you the possibilities of the platform. We will create 4 component types with capabilities that will correspond to the data described above: - TEMPERATURE and HUMIDITY, - VIBRATIONS, - PRESENCE. Below you will find the commands with outputs to follow. Temperature and humidity """""""""""""""""""""""" .. code:: none ocli dc component-type create Component type name: Temp. and Humidity 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: TEMPERATURE,HUMIDITY 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. 1. 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): TEMPERATURE 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). 1. Telemetry name: Temperature 2. Data unit [not required] (allowed values: °C, %, µg/m3, mg/m³, dB, dBm, % RH, m/s², ppm, kPa, hPa, Pa, V, W, A, °, lx, g, MB, s, kWh, Hz): °C 3. Data kind (allowed values: ANY, STRING, INTEGER, FLOAT, BOOLEAN, MAP, ARRAY, INT_ENUM, DATE): FLOAT 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://coreapi.dc.orchestra.ctiot.io/redoc#tag/Component-types/operation/Create_a_component_type_v1_components_types__post 1. Choose parameters type from the following (ParamSingleKey, ParamMultipleKey, ParamGroupKey): ParamSingleKey Provide 'key' values separated by commas. Example: temperature,value key: temperature Do you want to add telemetry properties for another sensor in this component? [y/N]: y 1. Provides sensing capability: HUMIDITY 2. Telemetry name: Humidity 3. Data unit [not required] (allowed values: °C, %, µg/m3, mg/m³, dB, dBm, % RH, m/s², ppm, kPa, hPa, Pa, V, W, A, °, lx, g, MB, s, kWh, Hz): % RH 4. Data kind: FLOAT 5. Choose parameters type from the following (ParamSingleKey, ParamMultipleKey, ParamGroupKey): ParamSingleKey Provide 'key' values separated by commas. Example: temperature,value key: humidity Do you want to add telemetry properties for another sensor in this component? [y/N]: n Vibrations """""""""" .. code:: none ocli dc component-type create Component type name: Vibrations 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: VIBRATIONS 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. 1. 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): VIBRATIONS 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). 1. Telemetry name: Vibrations 2. Data unit [not required] (allowed values: °C, %, µg/m3, mg/m³, dB, dBm, % RH, m/s², ppm, kPa, hPa, Pa, V, W, A, °, lx, g, MB, s, kWh, Hz): g 3. Data kind (allowed values: ANY, STRING, INTEGER, FLOAT, BOOLEAN, MAP, ARRAY, INT_ENUM, DATE): MAP 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://coreapi.dc.orchestra.ctiot.io/redoc#tag/Component-types/operation/Create_a_component_type_v1_components_types__post 1. Choose parameters type from the following (ParamSingleKey, ParamMultipleKey, ParamGroupKey): ParamMultipleKey For each value that makes up the measurement, provide 'name' and 'key' values separated by commas. Example: For a measurement sent like that: {"gps": { "lat": 52.12, "lng": 21.22}} Provide the following values: name: lat, key: gps,lat name: lng, key: gps,lng ... etc. Add the first value. name: X key: x Do you want to add another one? [y/N]: y name: Y key: y Do you want to add another one? [y/N]: y name: Z key: z Do you want to add another one? [y/N]: n Do you want to add telemetry properties for another sensor in this component? [y/N]: n Presence """""""" .. code:: none ocli dc component-type create Component type name: Presence 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: PRESENCE 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. 1. 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): PRESENCE 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). 2. Telemetry name: Presence 3. Data unit [not required] (allowed values: °C, %, µg/m3, mg/m³, dB, dBm, % RH, m/s², ppm, kPa, hPa, Pa, V, W, A, °, lx, g, MB, s, kWh, Hz): 4. Data kind (allowed values: ANY, STRING, INTEGER, FLOAT, BOOLEAN, MAP, ARRAY, INT_ENUM, DATE): STRING 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://coreapi.dc.orchestra.ctiot.io/redoc#tag/Component-types/operation/Create_a_component_type_v1_components_types__post 5. Choose parameters type from the following (ParamSingleKey, ParamMultipleKey, ParamGroupKey): ParamSingleKey Provide 'key' values separated by commas. Example: temperature,value key: event Do you want to add telemetry properties for another sensor in this component? [y/N]: n .. _creating-components: Creating components ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5. Now please create 4 **components** with the newly created types. Each time you create one, you will be prompted to choose a component type from the list and input its ID. Below you will find a detailed description of the flow. .. important:: Remember to save IDs of all of the components created. They will be needed to push example telemetry data. Temperature and humidity """""""""""""""""""""""" .. code:: bash ocli dc component create Component name: Temp. and Hum. Component Do you want to use one of the existing component types? [y/N]: y [ { "id": "6620f5e190bf68da3e814885", "name": "Temp. and Humidity", "element_type_id": "6620f5e0d72ed631f15c081f", "sensing_capabilities": [ "TEMPERATURE", "HUMIDITY" ] }, { "id": "6620f7f2ec65359a9d9e4694", "name": "Vibrations", "element_type_id": "6620f7f2da264508a1fc1c3a", "sensing_capabilities": [ "VIBRATIONS" ] }, { "id": "6620f89431ff57ca57c798fc", "name": "Presence", "element_type_id": "6620f893bbc2709d1a65ddd7", "sensing_capabilities": [ "PRESENCE" ] } ] Choose a component type from the list above (input the ID): 6620f5e190bf68da3e814885 Vibrations """""""""" Alternatively, you can provide `component-type-id` as an option if you know it already: .. code:: bash ocli dc component create -c 6620f7f2ec65359a9d9e4694 Component name: Vibrations Component Presence """""""" .. code:: bash ocli dc component create -c 6620f89431ff57ca57c798fc Component name: Presence Component 6. The next step is adding mock telemetry data for all of our components. To achieve that, you will need **element IDs** of the newly created components. If you don't remember them, just run the following command to find out: .. code:: bash ocli dc component list --mode json [ { "name": "Temp. and Hum. Component", "component_type_id": "6620f5e190bf68da3e814885", "element_id": "6620f98208a70b084d642b75", "element_type_id": "6620f5e0d72ed631f15c081f", "twin_id": "b901569b-ba5e-4a17-9e1c-877e32fbd344", "created_at": "2024-04-18T10:44:19.012000+00:00", "updated_at": "2024-04-18T10:44:19.012000+00:00", "id": "6620f983f22cd2a1dda5be2c", "component_type_name": "Temp. and Humidity", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "TEMPERATURE", "HUMIDITY" ] } ] }, { "name": "Vibrations Component", "component_type_id": "6620f7f2ec65359a9d9e4694", "element_id": "6620f9e602956125a884cb60", "element_type_id": "6620f7f2da264508a1fc1c3a", "twin_id": "4ce61a51-2ef0-444c-a9da-1fa84de0bf10", "created_at": "2024-04-18T10:45:58.446000+00:00", "updated_at": "2024-04-18T10:45:58.446000+00:00", "id": "6620f9e6ec65359a9d9e4695", "component_type_name": "Vibrations", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "VIBRATIONS" ] } ] }, { "name": "Presence Component", "component_type_id": "6620f89431ff57ca57c798fc", "element_id": "6620fa1d08a70b084d642b78", "element_type_id": "6620f893bbc2709d1a65ddd7", "twin_id": "5f97998d-305e-4fa3-b08a-ea647b4dfc19", "created_at": "2024-04-18T10:46:53.853000+00:00", "updated_at": "2024-04-18T10:46:53.853000+00:00", "id": "6620fa1d6dd74d0c63d3b445", "component_type_name": "Presence", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "PRESENCE" ] } ] } ] Now, use the IDs to push telemetry (2 documents for each element). In the commands below, swap the IDs with the IDs of your elements. Remember to slightly change timestamps for data from one element. .. code-block:: bash ocli dc component push-telemetry -e 6620f98208a70b084d642b75 --ts 2024-04-17T13:40:47.008+00:00 '{"temperature": 19, "humidity": 52}' ocli dc component push-telemetry -e 6620f98208a70b084d642b75 --ts 2024-04-17T16:40:47.008+00:00 '{"temperature": 21, "humidity": 48}' ocli dc component push-telemetry -e 6620f9e602956125a884cb60 --ts 2024-04-17T13:40:47.008+00:00 '{"x": -2.1575, "y": -10.1205, "z": -0.1961}' ocli dc component push-telemetry -e 6620f9e602956125a884cb60 --ts 2024-04-17T16:40:47.008+00:00 '{"x": -4.1575, "y": -8.1205, "z": -1.1961}' ocli dc component push-telemetry -e 6620fa1d08a70b084d642b78 --ts 2024-04-17T13:40:47.008+00:00 '{"event": "Presence detected"}' ocli dc component push-telemetry -e 6620fa1d08a70b084d642b78 --ts 2024-04-17T16:40:47.008+00:00 '{"event": "Presence detected"}' .. _creating-an-asset: Creating an asset ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 7. The last step of the flow is **adding an asset** containing all of the newly created components. To achieve that, follow the steps below: .. code-block:: bash ocli dc asset create Provide asset name: Test Asset Choose a component from the list below: [ { "name": "Temp. and Hum. Component", "component_type_id": "6620f5e190bf68da3e814885", "element_id": "6620f98208a70b084d642b75", "element_type_id": "6620f5e0d72ed631f15c081f", "twin_id": "b901569b-ba5e-4a17-9e1c-877e32fbd344", "created_at": "2024-04-18T10:44:19.012000+00:00", "updated_at": "2024-04-18T10:44:19.012000+00:00", "id": "6620f983f22cd2a1dda5be2c", "component_type_name": "Temp. and Humidity", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "HUMIDITY", "TEMPERATURE" ] } ] }, { "name": "Vibrations Component", "component_type_id": "6620f7f2ec65359a9d9e4694", "element_id": "6620f9e602956125a884cb60", "element_type_id": "6620f7f2da264508a1fc1c3a", "twin_id": "4ce61a51-2ef0-444c-a9da-1fa84de0bf10", "created_at": "2024-04-18T10:45:58.446000+00:00", "updated_at": "2024-04-18T10:45:58.446000+00:00", "id": "6620f9e6ec65359a9d9e4695", "component_type_name": "Vibrations", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "VIBRATIONS" ] } ] }, { "name": "Presence Component", "component_type_id": "6620f89431ff57ca57c798fc", "element_id": "6620fa1d08a70b084d642b78", "element_type_id": "6620f893bbc2709d1a65ddd7", "twin_id": "5f97998d-305e-4fa3-b08a-ea647b4dfc19", "created_at": "2024-04-18T10:46:53.853000+00:00", "updated_at": "2024-04-18T10:46:53.853000+00:00", "id": "6620fa1d6dd74d0c63d3b445", "component_type_name": "Presence", "capabilities": [ { "kind": "SENSOR", "sensing_capabilities": [ "PRESENCE" ] } ] } ] Please list ids of selected components separated by commas: 6620f983f22cd2a1dda5be2c,6620f9e6ec65359a9d9e4695,6620fa1d6dd74d0c63d3b445 Do you want to add another one? [y/N]: n Do you want to specify the address? [y/N]: y Please provide address details: Provide line1: al. Niepodległości 18 Provide line2: Provide zip: 02-653 Provide city: Warsaw Provide region: Provide country: Poland Provide longitude: 21.460418626497578 Provide latitude: 52.30847862124759 Successfully created the asset! Results --------- The sample dashboard has been created! **Assets list** view should look like that: .. image:: images/assets-list.png :alt: Assets list view :width: 100% :align: center Individual dashboards ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Temperature """"""""""" .. image:: images/dashboard-final.png :alt: Temperature dashboard :width: 100% :align: center Humidity """"""""""" .. image:: images/dashboard-humidity.png :alt: Humidity dashboard :width: 100% :align: center Vibrations """""""""" .. image:: images/dashboard-vibrations.png :alt: Vibrations dashboard :width: 100% :align: center Presence """""""" .. image:: images/dashboard-presence.png :alt: Presence dashboard :width: 100% :align: center 8. Finally, you can clean up your tenant's database and remove all the component types, components and asset created during this tutorial. .. code-block:: bash ocli dc asset cleanup 649b6d603fd1bb1f70f4611b Asset deleted.