This page contains detailed information about the Azure Digital Twin service in the Tartabit IoT Bridge. This service lets you integrate LPWAN devices directly as twins in the Azure Digital Twin (ADT) service.
Before you can integrate, you need to have an Azure Digital Twin instance, and a service principal with access to the instance.
The following command will create a new service principal for your ADT instance. Save the output of this command to configure the service below.
az ad sp create-for-rbac --name http://myname --scopes /subscriptions/<subscription>/resourceGroups/<resourcegroup>/providers/Microsoft.DigitalTwins/digitalTwinsInstances/<adt instance name> --role bcd981a7-7f74-457b-83e1-cceb9e632ffe
{
"appId": "bffc9e45-xxxxx",
"displayName": "http://qwerty-adt-data-access",
"name": "bffc9e45-5a3f-xxxxxxx",
"password": "XGR.lE~xxxxxxxxxW-O2p56aFI",
"tenant": "3b48acfa-3149-xxxxxxxx"
}
The Azure Digital Twin service contains the information required to establish a connection to Azure. There are two possible connections to make, first, you need to supply the general connection information to permit access to the Azure Digital Twins API, and optionally, you can provide access to an Event Hub to receive real-time changes from the Digital Twin instance. Configuring event routes can be found here: https://docs.microsoft.com/en-us/azure/digital-twins/how-to-manage-routes
This event fires when a twin change event is received on the event hub. Several different operations can occur that generate different input data.
{
"data": {
"properties": {}
},
"id": "tracker100",
"model": "dtmi:com:tartabit:generic;1",
"op": "create"
}
{
"changes": [
{
"op": "add",
"path": "/properties/speed",
"value": {
"double": 888.2
}
}
],
"id": "tracker100",
"model": "dtmi:com:tartabit:generic;1",
"op": "update"
}
{
"data": {
"properties": {
"speed": {
"double": 888.2
}
}
},
"id": "tracker99",
"model": "dtmi:com:tartabit:generic;1",
"op": "delete"
}
create and delete only) The property data from the twin.update only) The JSON-Patch changes for the twin.This event fires when telemetry is published from a twin.
{
"data": {
"telemetry": {
"push_button_application_type": {
"string": "Push button 1"
},
"push_button_digital_input_counter": {
"double": 0
},
"push_button_digital_input_state": {
"boolean": false
},
"push_button_timestamp": {
"string": "1970-01-01T00:00:00Z"
},
}
},
"id": "tracker99",
"model": "dtmi:com:tartabit:generic;1"
}
This event fires when a relationship betweent two twins changes.
{
"op": "create",
"relId": "tracker100",
"relName": "rel_has_generics",
"sourceId": "geofence-avro",
"targetId": "tracker100"
}
{
"changes": [
{
"op": "replace",
"path": "",
"value": {}
}
],
"op": "update",
"relId": "tracker100",
"sourceId": "geofence-avro"
}
{
"op": "delete",
"relId": "tracker100",
"relName": "rel_has_generics",
"sourceId": "geofence-avro",
"targetId": "tracker100"
}
create and delete only) The property data from the relationship.update only) The JSON-Patch changes for the relationship.azure_twin.get() which is always synchronous.This function adds a twin to your ADT instance.
// add a new twin to your ADT instance. If the twin already exists it is replaced.
azure_twin.add('myservice', 'device1', 'dtmi:com:tartabit:assettracker;1', { field1: 'abc', field2: '123' })
This function adds a relationship between two twins in your ADT instance.
// add a new twin to your ADT instance. If the twin already exists it is replaced.
azure_twin.add_relationship('myservice', 'device1', 'rel1', 'group1', 'rel_has_devices', { field1: 'abc', field2: '123' })
id.This function deletes a twin from your ADT instance.
// delete a twin from your ADT instance.
azure_twin.delete('myservice', 'device1')
This function adds a relationship between two twins in your ADT instance.
// delete a twin relationship from your ADT instance.
azure_twin.delete_relationship('myservice', 'device1', 'rel1')
This function retreives a twin from the ADT instance.
// get a twin from the ADT instance
var twin = azure_twin.get('myservice', 'device1')
This function retreives a twin from the ADT instance.
// send telemetry related to a twin
zure_twin.send('myservice', 'device1', {temperature: 23.5})
This function updates an existing twin. Please refer to the Microsoft documentation for formatting of the change object, it confirms to JSON-Patch.
// update the twin by adding a new property "property1", removing "property2", and updating "property3.subProperty1" with a new value.
var change = [
{
"op": "add",
"path": "/property1",
"value": 1
},
{
"op": "remove",
"path": "/property2"
},
{
"op": "replace",
"path": "/property3/subProperty1",
"value": "new value"
}
]
azure_twin.update('myservice', 'device1', change)
add, remove, replace.This function updates an existing twin. Please refer to the Microsoft documentation for formatting of the change object, it confirms to JSON-Patch.
// update the twin relationship by adding a new property "property1", removing "property2", and updating "property3.subProperty1" with a new value.
var change = [
{
"op": "add",
"path": "/property1",
"value": 1
},
{
"op": "remove",
"path": "/property2"
},
{
"op": "replace",
"path": "/property3/subProperty1",
"value": "new value"
}
]
azure_twin.update_relationship('myservice', 'device1', 'rel1', change)
add, remove, replace.The following events are considered billable: