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
Postmanthat 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
GET
https://qa-ims.bentley.com/connect/token
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.
POST
https://dev-api.bentley.com/integrations/integrate
Request parameters for create a node, device(s) and sensor(s)
Name
Required?
Description
iTwinId
Yes
iTwin Project or Asset.
Request definitions
Name
Type
Required?
Description
props.INTEGRATION_ID
string
Yes
Data Source API Import Id (NODE_API_SDE for generic type)
refId
string
Yes
Unique id can be used to update or delete devices or sensors.
integration.changeState
string
No
To create a node set changeState to
new (Although this property is not necessary, failing to provide will result in a 422 error)devices[].changeState or sensors[].changeState
string
No
To create an device or sensor set changeState to
new; to update set to update to remove set to removeprops.NAME
string
No
Device or sensor name
props.LOCATION
object
No
X, Y & Z coordinates of device or sensor
sensors[].props.UNKNOWN_UNITS
object
No
Unknown units of a sensor
sensors[].props.UNKNOWN_METRICS
object
No
Arbitrary metrics of a sensor
sensors[].props.KNOWN_UNITS
object
No
Known units of a sensor
sensors[].props.KNOWN_METRICS
object
No
Known metrics of a sensor
props.NOTES
string
No
Additional information of devices and sensors
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)
Name
Required?
Description
iTwinId
Yes
iTwin Project or Asset.
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
changeStateproperty toremove - If you want to delete a sensors from an existing device make sure to set
changeStateproperty 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)
Name
Required?
Description
iTwinId
Yes
iTwin Project or Asset.
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.