Quick start tutorial

Complete the tutorial to perform some basic tasks.

The first tasks to complete when you start to use the product include getting data into the data lake, applying a calculation to the data, and displaying the results on a dashboard.

In the tutorial, you are simulating a room sensor in a conference room to measure room occupancy and room temperature. Room occupancy is provided as a percentage of room capacity, and temperature is measured in Centigrade. You configure a dashboard to monitor the levels of occupancy and the deviations in temperature values over a 24-hour period.

Step 1: Add a device type

Before you can register and connect your devices to Platform Service or IoT Tool, you must create a device type.

From the side menu, click Connect.
Select Device types.
Click Add new device type.
Assign the name Room_sensor to the device type.
Click Create Device type.

Step 2: Add a device

Select Connect and then click Add a device.
Find the Room_sensor device type.
Assign the name Room_sensor_1 device ID to the device and click Next.
Assign an authentication token to the device. If you don't assign one, a token is autogenerated for you.
Write down the unique device ID and token that you configure for the device. These parameters are used to reference your device.
Click Save and finish.

Step 3: Send data

Before you send data, go to the Recent events section of your device page to monitor recent events as they arrive.

Use the following Messaging API to send device events to the platform:

POST /device/types/{typeId}/devices/{deviceId}/events/{eventName}

Open Postman.
Click New > Request.
Assign a name to the request.
Select POST from the request drop-down.
Enter the API endpoint URL.
Example:
https://{orgId}.messaging.internetofthings.ibmcloud.com/api/v0002/device/types/{typeId}/devices/{deviceId}/events/{eventName} Where:
{orgId} Is the unique six-character organization ID that was generated when you registered the Platform Service. For example: POST /device/types/Room_sensor/devices/Room_sensor_1/events/room_status
Select the Authorization tab.
1. Set the type to Basic Auth.
2. Set Username to use-token-auth.
3. Use the token that you created when you registered the device as the password.
Select the Headers tab and set Content-Type to application/json.
Select the Body tab and add the following JSON payload:
```
 {
 "occupancy": random(0, 100), 
 "temp": random(15, 35)
 }
```
Keep your Postman session open. You will send some more events later after you create the physical and logical interfaces.
Check that the event appears in the Recent events section of the View Device page.

Step 4: Add the event type to the physical interface

From the side menu, select Connect.
Select Device Types.
Find the Room_sensor device type.
Click Edit.
Add a new event type from received events. Find the room_status event.
Click Create.
Click Save and finish.

Step 5: Create the logical interface

From the side menu, select Connect and click Interfaces.
Click Add new interface.
Assign the name room_status to the interface.
Add the properties occupancy and temp as integers.
Click Create interface.

Step 6: Add the logical interface to your device type

From the side menu, select Connect and click Device type.
Find your device type and open it.
Click Edit.
Add the room_status logical interface that you created to the Room_sensor device type.
Map each property of the logical interface to a field on the physical interface. For occupancy, use $event.occupancy in the mapping field. For temp, use $event.temp.
Click Close.
Click Save and finish.
Click View and activate interfaces.
Click Activate all.

Step 7: Explore device metrics

Your device types are automatically generating entity types and storing the corresponding device data in the data lake.

Important: The data lake contains historical data and is populated as your devices contribute data. A time lag occurs between when you connect a device for the first time and when the data starts appearing.

From the side menu, select Monitor.
Select the Room_Sensor_1 device type.
Select the Data tab to look at the data that is stored in the data lake.
Two data points correspond to the device payload that is directly mapped by the logical interface and that includes the following device properties:
- occupancy - Number representing the occupancy level percentage in the range 0-100.
- temp - Number representing temperature in the range 15-35 C.
Select the temp data item from the Data column to view the temp input data for the device.

Your device data is now flowing into the data lake, and you add a calculation by using a built-in function.

Step 8: Add calculations

Add use calculations to the input data. Calculate the standard deviation of temperature data.

From the side menu, select Monitor.
Select the Room_Sensor_1 device type.
Select the Data tab to look at the data that is stored in the data lake.
Click .
Browse the function catalog and select the StandardDeviation function.
Select the temp metric as the source and name the calculated metric temp_sigma.
Select the granularity to use for the calculation, for example Daily.
Wait a couple of minutes for the scheduled calculations to run and then return to the Data tab and look at your new calculated metric.

Step 9: Add a device dashboard

You can create a dashobard from the user interface. Alternatively, you can create a JSON file with the following dashboard configuration. The dashboard includes two line graph cards. The first card plots occupancy of the device over the last 24 hours. The second card plots the mean and maximum temperature over the last 24 hours.

Note: The dashboard creates the mean and maximum aggregate functions.

In the JSON example, the dataSource/attributes/attribute entry corresponds to the room_status_occupancy data item and the temp_sigma data item.

{
    "title": "Room Sensor Graph",
    "cards": [{
            "id": "room_sensor_occupancy",
            "size": "LARGE",
            "title": "Room occupancy - input values",
            "type": "TIMESERIES",
            "content": {
                "series": [{
                        "dataSourceId": "occupancyID",
                        "label": "Occupancy "
                    }
                ],
                "unit": "%"
            },
            "dataSource": {
                "attributes": [{
                        "attribute": "room_status_occupancy",
                        "id": "occupancy_ID"
                    }
                ],
                "range": {
                    "count": -24,
                    "interval": "hour"
                }
            }
        },
        {
            "id": "room_sensor_temp",
            "size": "LARGE",
            "title": "Temperature stanard deviation data mean vs max",
            "type": "TIMESERIES",
            "content": {
                "series": [{
                    "dataSourceId": "temp_sigma_ID",
                    "label": "Temp - standard deviation"
                }]
            },
            "dataSource": {
                "attributes": [{
                    "attribute": "temp_sigma",
                    "id": "temp_sigma_ID"
                }],
                "range": {
                    "count": -24,
                    "interval": "hour"
                }
            }
        }
    ]
}

From the side menu, select Monitor.
Select the Room_Sensor device type.
Select a device.
Click the plus icon to add a dashboard and assign a name to the dash
Import the JSON dashboard configuration file.
Verify that the dashboard looks as expected and then click Save.

Step 10: View metrics for your assets

Visualize the data as cards by using the monitoring dashboard feature.

On the Device type tab, select the Room_Sensor device type.
Select aRoom_Sensor_1 device and open the dashboard that you created.
Verify that you can monitor occupancy data from this dashboard.
Change the time range to show the last 7 days of occupancy data.
Change the anchor time on the dashboard to yesterday and see how the time range on all cards is impacted.