Configuring IoT sensors

IBM® TRIRIGA® Building Insights ingests data from other devices and systems, including IoT sensors. To enable Building Insights access to IoT sensor data, you must configure the IoT sensors in your Building Insights environment.

In some instances, for bandwidth, security, or other reasons, IoT sensors use gateways to communicate sensor data to the cloud. Gateway devices act on behalf of sensor devices and act as bridges between sensor devices and the cloud. In Watson IoT Platform, gateways are a specialization of devices that have extra permission to register new devices and act on behalf of a device that is assigned to the gateway. To enable Building Insights access to data from sensors that use gateways, you must configure the gateway in your Building Insights environment.

To configure IoT sensors, complete the steps and use the API requests in following section Configuring IoT sensors.

To configure IoT sensor gateways, complete the steps and use the API requests in the following section Configuring IoT sensor gateways.

For more information about the APIs, payloads and response types, see Data Transformation Layer REST API.

Prerequisites

Complete preceding tasks and steps in Configuring the product.

Configuring IoT sensors

As the TRIRIGA Administrator, complete the following steps to configure IoT sensors.

Create a specification for the IoT sensor. a. Create a specification and device type for the IoT sensor, call the following API.
```
POST {{Data Transformation Layer URL}}/api/v2/device-specifications
```
Example API payload:
```
{
        "name": "piribmegl8c",
        "id": "piribmegl8c",
        "specClass": "Electrical Equipment",
        "serviceClass": "Hardware", 
        "modelNum": "C350",
        "currency": "Euro",
        "itemUnits": "each"
}
```
The API completes the following operations: - Creates a specification in TRIRIGA. - Creates a device type for the specification in Watson IoT Platform. - Maps both the specification and device type in Building Insights for the sensor. b. Verify creation of the specification, call the following API.
```
GET {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}
```
c. Check status of the specification creation operation, call the following API.
```
GET {{Data Transformation Layer URL}}/api/v2/device-specifications/status
```
d. Optionally, if you want to delete a specification, call the following API. Before you can delete a specification, you must delete the related asset and interface.
```
DELETE {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}
```

Add the physical interface and logical interface to the device type that is created in Watson IoT Platform, call the following API.

POST {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/transformer

Example API payload:

{
"event": "status",
"physicalInterface": {
	"title": "device physical schema",
	"description": "device physical schema",
	"properties": {
		"time": {
			"type": "string",
			"format": "date-time"
		},
		"occupancycount": {
			"type": "number"
		}
	}
},
"logicalInterface": {
	"occupancy": {
		"title": "Occupancy logical schema",
		"description": "Occupancy logical schema stores occupancy data required by TBI",
		"properties": {
			"time": {
				"type": "string",
				"format": "date-time"
			},
			"occupancycount": {
				"type": "number"
			}
		},
		"mapping": {
			"time": "$event.time",
			"occupancycount": "$exists($event.occupancycount)?$event.occupancycount:null"
		}
	}
}

} Optionally, if you want to delete the interface, call the following API. Before you can delete the interface, you must delete the related asset. DELETE {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/transformer ```

Create assets and devices for the IoT sensors. Create assets in TRIRIGA and create devices in Watson IoT Platform and Building Insights.

Retrieve the asset template CSV file, call the following API.

GET {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/template

The CSV file template can have the following content types in the header row.

id,name,serialNum,primLoc,gatewayId,authToken

Create the assets with the asset template CSV file, call the following API.

POST {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/bulk

The asset CSV file has the following types of entries.

id,name,serialNum,primLoc,gatewayId,authToken
EGLC6F-100,Desktop Sensor A,s001, \\Locations\\Offices\\North America\\Charlotte Building\\02 - Second Floor\\02-BG06,,password
EGLC6F-101,Desktop Sensor B,s001, \\Locations\\Offices\\North America\\Charlotte Building\\02 - Second Floor\\02-BE26,,password

Verify asset creation with one of the following APIs.

Verify the bulk creation of assets, call the following API.

GET {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/status

Verify the creation of a single asset, call the following API.

GET {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/{{asset id}}

Optionally, if you want to delete an asset, call the following API.

DELETE {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/{{asset id}}

For deletion of assets in bulk with the asset template CSV file, call the following API.

DELETE {{Data Transformation Layer URL}}/api/v2/device-specifications/{{specification id}}/assets/bulk

The asset CSV file has the following types of entries:

id, authToken
EGLC6F-100, password

Configuring IoT sensor gateways

As the TRIRIGA Administrator, complete the following steps to configure gateways.

Create a specification for the gateway.
1. Create a specification and device type for the gateway, call the following API. The API completes the following operations:
- Creates a specification in TRIRIGA.
- Creates a device type for the specification in Watson IoT Platform.
- Maps both the specification and device type in Building Insights for the gateway.
```
POST {{Data Transformation Layer URL}}/api/v2/gateway-specifications
```
Example API payload:
```
{
    "name": "MOD_IBMGWSPE_1M",
    "id": "MOD_IBMGWSPE_1M",
    "specClass": "Electrical Equipment",
    "serviceClass": "Hardware",
    "modelNum": "M130",
    "currency": "Euro",
    "itemUnits": "each"
}
```
1. Verify creation of the specification, call the following API.
```
GET {{Data Transformation Layer URL}}/api/v2/gateway-specifications/{{specId}}
```
1. Check status of the specification creation operation, call the following API.
```
GET {{Data Transformation Layer URL}}/api/v2/gateway-specifications/status
```
1. Optionally, if you want to delete a specification, call the following API. Before you can delete a specification, you must delete the related asset and interface.
```
DELETE {{Data Transformation Layer URL}}/api/v2/gateway-specifications/{{specId}}
```
Create assets and devices for the gateways. Create assets in TRIRIGA and create devices in Watson IoT Platform and Building Insights.
1. Create assets and devices, call the following API.
```
POST {{Data Transformation Layer URL}}/api/v2/gateway-specifications/{specId}/assets/{assetId}
```
1. Verify asset creation, call the following API.
```
GET {{Data Transformation Layer URL}}/api/v2/gateway-specifications/{specId}/assets/{assetId}
```
1. Optionally, if you want to delete an asset, call the following API.
```
DELETE {{Data Transformation Layer URL}}/api/v2/gateway-specifications/{specId}/assets/{assetId}
```