Sensor Data
Introduction
The sensor data service offers REST APIs to third-party sensor manufacturers and data sources to integrate their sensors with iTwin IoT platform.
This document focuses on importing generic sensors into iTwin IoT and concentrates on the persona, where the sensor manufacturers will be able to push their data into sensor data service.
Entities Hierarchy
The first step to visualizing data on the platform is to add a connection to a project, then attach subsequent devices and sensors. Your network is broken up into three distinct levels of entities: Connections, Devices, and Sensors.
A connection is simply a connection to your data source. It aggregates the data from all associated devices and sensors and sends the information to the platform. Connections can be hardware-based, such as cell phones or radios, or software-based, such as an API or FTP.
The device can then read the array of associated sensors and store their data, or it can house the sensor datasets being transmitted from the file transfer connection.
A sensor will physically collect the data from the field and they also represent the data aggregation and storage node in the app.
Prerequisites
To create a Bentley account if you don't already have one, iTwin IoT and complete the registration process.
Use the following steps to integrate your sensors with the iTwin IoT platform.
- Create an application in iTwin Platform
- Obtaining Authorization Token
- Register an asset in iTwin IoT
Create an Application in iTwin Platform
Steps to create an application in iTwin Platform can be found at Register a service application.
During the registration process, you may need to choose
Administration
andDigital Twin Management
API associations. Additionally, all requests require anAuthorization
header with a valid Bearer token withitwin-platform
scope.
Obtain Authorization Token
You can use the generated client id, client secret and scopes to Obtain an access token.
Register an Asset in iTwin IoT
To create an asset you must have at least one of the following roles assigned in User Management: Account Administrator
, Co-Administrator
, or CONNECT Services Administrator
. Then you can register an asset in iTwin IoT and make sure to enable Allow external team members
. Add the user that got created, while registering an application in iTwin Platform (example@apps.imsoidc.bentley.com) into the created asset with IoT Creator
role (refer below screenshots).
The address bar in the below screenshot displays the iTwin IoT asset id which is needed to make API calls.
When an asset (iTwin) is registered via iTwin IoT, IOT capabilities are set up behind the scenes.
Create, Update and Delete Node, Device(s), and Sensor(s)
You can use this API to create, update and delete node, device(s) and sensor(s) all together.
If none of the provided device template or sensor template meet the requirements, you can use IMPORT_DEVICE_SDE
for device and GENERIC_SENSOR_SDE
for sensor.
If you delete a node or device(s) or sensor(s) all the underlying sensor observation will be deleted.
POST https://api.bentley.com/sensor-data/integrations/integrate?iTwinId=<Your asset id>
Request parameters
curl --location 'https://api.bentley.com/sensor-data/integrations/integrate?iTwinId=<Your asset id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your access token>' \
--data '{
"integration": {
"changeState": "new",
"devices": [
{
"changeState": "new",
"props": {
"INTEGRATION_ID": "IMPORT_DEVICE_SDE",
"NAME": "Device-1"
},
"sensors": [
{
"changeState": "new",
"props": {
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"NAME": "Sensor-1",
"UNKNOWN_UNITS": {
"0": "millimeter",
"1": "millimeter"
},
"UNKNOWN_METRICS": {
"0": "Alignment_Left_SD",
"1": "Alignment_Right_SD"
}
}
},
{
"changeState": "new",
"props": {
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"NAME": "Sensor-2",
"UNKNOWN_UNITS": {
"0": "millimeter",
"1": "millimeter"
},
"UNKNOWN_METRICS": {
"0": "Alignment_Left_SD",
"1": "Alignment_Right_SD"
}
}
}
]
}
]
}
}
'
Request definitions
new
; to remove set to remove
(Although this property is not necessary, failing to provide will result in a 422 error)new
; to update set to update
to remove set to remove
. Generic sensors
If you have sensors that you would like to import into iTwin IoT, but the sensors don't match any of the existing iTwin IoT Sensor templates, set GENERIC_SENSOR_SDE
to the props.INTEGRATION_ID
property.
Generic sensors MUST have their metrics and units defined on the sensor during the time of creation. Most scenarios which opt to use a generic sensor use free form custom string for both metrics and unit.
Example of unknown metric and unknown unit
{
"changeState": "new",
"refId": "{{$guid}}",
"props": {
"NAME": "Unknown metrics and units",
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"UNKNOWN_UNITS": {
"0": "abcUnit"
},
"UNKNOWN_METRICS": {
"0": "abc"
}
}
}
Example known metric and known unit:
Other scenarios might use both known metrics and known units however, the ordering of metrics list slightly differs from a defined sensor template this might look like the sample below.
{
"changeState": "new",
"refId": "{{$guid}}",
"props": {
"NAME": "Known metrics and units",
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"KNOWN_UNITS": {
"0": "Hz",
"1": "mm"
},
"KNOWN_METRICS": {
"0": "f",
"1": "cum_distance"
}
}
}
Example unknown metric and known unit:
Final scenarios might use known units with unknown metrics.
{
"changeState": "new",
"refId": "{{$guid}}",
"props": {
"NAME": "Known metrics and units",
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"KNOWN_UNITS": {
"0": "Hz",
"1": "mm"
},
"UNKNOWN_METRICS": {
"0": "abc",
"1": "def"
}
}
}
Get Integrations
This API can be used to retrieve information like all devices and sensors of given a node id.
POST https://api.bentley.com/sensor-data/integrations/integrate
curl --location 'https://api.bentley.com/sensor-data/integrations/integrate' \
--header 'Authorization: Bearer <your access_token>' \
--header 'Content-Type: application/json' \
--data ' {
"integration": {
"nodeId": "/api/11C4EA/node"
}
}'
Upload Sensor Observations
To upload readings to a specified sensor requires sensor id and timestamp of the observation recorded and an object values containing required supported metrics with a key-value. You can find the required metrics along with units using Metrics and Units.
POST https://api.bentley.com/sensor-data/data/upload
curl --location 'https://api.bentley.com/sensor-data/data/upload' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your access token> ' \
--data '{
"observations": [
{
"sensorId": "/api/B08851/node/dynamic/AB10E2/device/D76619/sensor",
"timestamp": "2024-02-20T04:35:23.653Z",
"values": {
"Alignment_Left_SD": 0.23,
"Alignment_Right_SD": 0.84
}
},
]
}'
Request definitions
In iTwin IoT, you can confirm the uploaded observations. When you open the asset, navigate to theData
tab, click on the tables
, choose the desired sensor, and all of the submitted observations will be shown.
Choose Device Template
You can see the list of supported Device templates and choose the suitable device template with the help of this REST API.
GET https://iiot.bentley.com/api/devices/types?excludeLegacy=true
curl --location 'https://iiot.bentley.com/api/devices/types?excludeLegacy=true' \
--header 'Authorization: Bearer <Your access token>'
Choose Sensor Template
You can see the list of supported Sensor templates and choose the suitable sensor template with the help of this REST API.
GET https://iiot.bentley.com/api/sensors/types?excludeLegacy=true
curl --location 'https://iiot.bentley.com/api/sensors/types?excludeLegacy=true' \
--header 'Authorization: Bearer <Your access token>'
In the response you can see the id
field of the sensor template. Which will be needed to create a new sensor.
Metrics and Units
To view the catalog of all standard/known metrics and units use this REST request. For example, the temperature sensor above TEMPERATURE_SDE
Stores readings for a single metric Temperature
which has a metric Id of T
the supported units for this metric are Celsius (C) kelvin (K) and Fahrenheit (F).
GET https://iiot.bentley.com/api/metrics/types?excludeLegacy=true
curl --location 'https://iiot.bentley.com/api/metrics/types?excludeLegacy=true' \
--header 'Authorization: Bearer <Your access token>'
Obtain Required Metrics and Supported Units for a Sensor
POST https://iiot.bentley.com/api/sensors/metrics?projectIds=<Your asset id>
curl --location 'https://iiot.bentley.com/api/sensors/metrics?projectIds=<Your asset id>&filters=raw' \
--header 'Authorization: Bearer <Your access token> ' \
--header 'Content-Type: application/json' \
--data '{
"ids": [
"/api/B08851/node/dynamic/AB10E2/device/D76619/sensor"
]
}'