Introduction
This tutorial will take you through the process of how you can create, update & delete device(s) and sensor(s) and focuses on importing generic sensors into iTwin IoT and concentrates on the persona, where the you will be able to push the data into sensor data service. You will learn the following:
- How to Create node, device(s) and sensor(s)
- How to Update device(s) and sensor(s)
- How to Delete device(s) and sensor(s)
Before you begin
This tutorial assumes that you already have:
- A Bentley IMS account
- Create an application in iTwin platform
- Register an Asset in iTwin IoT
- A tool, such as
Postman
that can be used to execute HTTP calls.
Set up your tutorial environment
This section guides you through the pre-requisite steps for the tutorial so you can make sample API requests. It also provides sample data for you to use during the tutorial.
Authorize your requests
curl --location 'https://ims.bentley.com/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<Your client id> ' \
--data-urlencode 'client_secret=<Your client secret> ' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=itwin-platform'
Create Node, Device(s), and Sensor(s)
You can create a new node, device(s), and sensor(s) in an asset.
Request parameters for create a node, device(s) and sensor(s)
Request definitions
new
(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
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",
"refId": "ecf7c340-7cef-43c8-9d5642-9096d2e45db5",
"props": {
"INTEGRATION_ID": "IMPORT_DEVICE_SDE",
"NAME": "Test Device",
"LOCATION": {
"type": "Point",
"coordinates": [
174.7805678,
-41.27834066,
20
]
}
},
"sensors": [
{
"changeState": "new",
"refId": "2ef86679-a18f-464500-9c78-4fa9c89c963f",
"props": {
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"NAME": "Test sensor",
"LOCATION": {
"type": "Point",
"coordinates": [
174.7805678,
-41.27834066,
20
]
},
"UNKNOWN_UNITS": {
"0": "millimeter",
"1": "millimeter"
},
"UNKNOWN_METRICS": {
"0": "Alignment_Left_SD",
"1": "Alignment_Right_SD"
},
"NOTES":"Generic sensor"
}
}
]
}
]
}
}
'
Update Device(s) and Sensor(s)
You can use this API endpoint to update the device(s) and sensor(s), request body is similar to create node, device(s) and sensor(s) request but make sure you have provided the nodeId
, refId
that was used while creating devices or sensors and set the changeState
property to update
.
Request parameters for update device(s) or sensor(s)
Update device(s) and sensor(s) CURL
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": {
"nodeId": "<Your node id>",
"devices": [
{
"changeState": "update",
"refId": "ecf7c340-7cef-43c8-9d5642-9096d2e45db5",
"props": {
"INTEGRATION_ID": "IMPORT_DEVICE_SDE",
"NAME": "Test Device - UPDATED",
"NOTES":"Demo device - Updated"
},
"sensors": [
{
"changeState": "update",
"refId": "2ef86679-a18f-464500-9c78-4fa9c89c963f",
"props": {
"NAME": "Test Sensor - UPDATED",
"INTEGRATION_ID": "GENERIC_SENSOR_SDE",
"NOTES":"Generic sensor - Updated"
}
}
]
}
]
}
}
'
Delete Device(s) and Sensor(s)
You can use this API endpoint to delete the device(s) and sensor(s),
- To delete device(s) and sensor(s), make sure to set
changeState
property toremove
- If you want to delete a sensors from an existing device make sure to set
changeState
property of that device toupdate
- If you delete a node all underlying device(s) and sensor(s) will be deleted
- If you delete a node or device(s) or sensor(s) all underlying the sensor observations will be deleted
Request parameters for delete device(s) and sensor(s)
Delete device(s) and sensor(s) CURL
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": {
"nodeId": "<Your node id>",
"devices": [
{
"changeState": "remove",
"refId": "ecf7c340-7cef-43c8-9d5642-9096d2e45db5",
"sensors": [
{
"changeState": "remove",
"refId": "2ef86679-a18f-464500-9c78-4fa9c89c963f"
}
]
}
]
}
}
'
What you've learned
In this tutorial, you should have learned how to create, update & delete the device(s) and sensor(s) in the sensor data service.