¶ LWM2M to Azure Digital Twins
This guide will walk you though integrating a LWM2M device to Azure Digital Twins using an available solution template.
¶ Pre-requisites
- Account on Tartabit IoT Bridge.
- Access to a Microsoft Azure subscription.
- Azure CLI.
- LWM2M device that supports registration or bootstrap with CoAP over DTLS.
- A pre-defined Azure Digital Twins instance.
¶ Details of this guide
- In this guide you will:
- Create the credentials needed to connect to your Azure Digital Twins instance.
- Import a solution template, this will create all of the required triggers, services, and endpoints required to connect your device.
- Connect a LWM2M device
- Verify that the device is properly reporting into the Azure IoT Hub.
¶ 1. Create a service principal for the IoT Bridge to use
- Login to the Azure CLI
- List your digital twins instances
az dt list --query "[].{name:name,id:id}"
- Find the Azure Digital Twins instance you wish to use and save the
idfield for use later. - Execute the following to create a service principal.
az ad sp create-for-rbac --name http://{name for sp} --scopes {id from #1} --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"
}
¶ 2. Define the twin model
We have created a sample model that can generically represent any device. This model is not practical for production use cases, but for the purposes of getting started it is highly effective. The steps below will walk you through importing the model to your digital twins instance.
¶ Generic Model
You can download the generic model here: model.json
{
"@id": "dtmi:com:tartabit:generic;1",
"@type": "Interface",
"@context": [
"dtmi:dtdl:context;2"
],
"displayName": "Generic Object",
"contents": [
{
"@type": "Property",
"name": "name",
"displayName": "Name",
"schema": "string"
},
{
"@type": "Property",
"name": "type",
"displayName": "Type",
"schema": "string"
},
{
"@type": "Property",
"name": "properties",
"displayName": "Properties",
"schema": {
"@type": "Map",
"mapKey": {
"name": "param",
"schema": "string"
},
"mapValue": {
"name": "value",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": {
"en": "Name"
},
"name": "metaName",
"schema": "string"
},
{
"displayName": {
"en": "Description"
},
"name": "metaDesc",
"schema": "string"
},
{
"displayName": {
"en": "Boolean"
},
"name": "boolean",
"schema": "boolean"
},
{
"displayName": {
"en": "Double"
},
"name": "double",
"schema": "double"
},
{
"displayName": {
"en": "String"
},
"name": "string",
"schema": "string"
},
{
"name": "location",
"displayName": {
"en": "Location"
},
"schema": {
"@type": "Object",
"fields": [
{
"displayName": {
"en": "Latitude"
},
"name": "lat",
"schema": "double"
},
{
"displayName": {
"en": "Longitude"
},
"name": "lon",
"schema": "double"
}
]
}
}
]
}
}
}
},
{
"@type": "Telemetry",
"name": "telemetry",
"displayName": "Telemetry",
"schema": {
"@type": "Map",
"mapKey": {
"name": "param",
"schema": "string"
},
"mapValue": {
"name": "value",
"schema": {
"@type": "Object",
"fields": [
{
"displayName": {
"en": "Name"
},
"name": "metaName",
"schema": "string"
},
{
"displayName": {
"en": "Description"
},
"name": "metaDesc",
"schema": "string"
},
{
"displayName": {
"en": "Boolean"
},
"name": "boolean",
"schema": "boolean"
},
{
"displayName": {
"en": "Double"
},
"name": "double",
"schema": "double"
},
{
"displayName": {
"en": "String"
},
"name": "string",
"schema": "string"
},
{
"name": "location",
"displayName": {
"en": "Location"
},
"schema": {
"@type": "Object",
"fields": [
{
"displayName": {
"en": "Latitude"
},
"name": "lat",
"schema": "double"
},
{
"displayName": {
"en": "Longitude"
},
"name": "lon",
"schema": "double"
}
]
}
}
]
}
}
}
},
{
"@type": "Relationship",
"@id": "dtmi:com:tartabit:device:rel_has_generics;1",
"name": "rel_has_generics",
"displayName": "generic has generics",
"target": "dtmi:com:tartabit:generic;1",
"properties": [
{
"@type": "Property",
"name": "desc",
"schema": "string"
}
]
}
]
}
¶ Importing via Azure CLI
- Download the model JSON file above and save it to your computer.
- Execute the following command:
az dt model create -n {instance_or_hostname} --models {path_to_downloaded_file}
¶ Importing via Digital Twin Explorer
- Launch the Azure Digital Twin Explorer
- Click the
upload modelbutton to import the model JSON file.
¶ 3. Import the solution template
- Log into the IoT Bridge.
- Navigate to
Solution Tempatesat the bottom of the window.
- Select the
LWM2M to Azure Digital Twinstemplate.
- Click
import. - Enter the information from above to complete the template:
- Hostname: The hostname for your ADT instance.
- Client ID: The Client ID for the service credential created above.
- Tenant: The Client ID for the service credential created above.
- Secret Key: The Client ID for the service credential created above. - Select
Start triggersto start the triggers upon import and clickimport.
¶ 4. Verify the import was successful
You should receive an import result like this:
¶ 5. Review the application
Let's review the key elements of this solution:
¶ 5.1 Azure Digital Twins service
The ADT service connector enables both sending updates to ADT (via the Azure Digital Twins API) and receiving updates from ADT via events from an Event Hub. At this time, we have only configured the ADT API, and have not configured the Event Hub connection to receive twin change events.
¶ 5.2 Azure Digital Twin - Send trigger
This trigger listens for lwm2m-simple-data generic events and publishes data to ADT. It will attempt to update the twin first, and if that does not succeed it will create a new twin with the endpoint key ad the ID of the twin. This uses the generic data format.
¶ 5.3 Azure Digital Twin - Handle Changes
This trigger listens on an event hub for changes to the twin and returns the JSON-Patch data to the trigger for processing. Specifically it is handling changes to the /properties/command/string field to accept a set of comma separated parameters. The trigger will reply in /properties/commandReply/string field.
- Example: 'write,3/0/15,UTC' will write the string 'UTC' to 3/0/15 (timezone).
- Example: 'exec,1/0/8' will execute the registration update.
¶ 6. Connect your device
- Connect your LWM2M device to the IoT Bridge.
- Verify that your device is connected from the
Endpointspage. - Verify that the triggers have executed from the
Triggerspage.
¶ 7. Check the Azure Digital Twins Explorer
At this point you can log into the Azure Digital Twins explorer and browse your device in the twin.
- Launch the Digital Twin Explorer from the Azure Portal.
- Query the latest data by clicking the
Querybutton in the top right. - Click on your twin and you can see the data in the Properties section on the right side of the view.
¶ You are done!
Congratulations!
¶ Next steps
While this guide did not specifically address processing twin changes, you can check out the Azure Digital Twin - Handle Changes trigger. To enable changes, follow the steps below:
- Create an event hub for use by Digital Twins.
- In your ADT instance, create an endpoint for the Event Hub you wish to use.
- Create an event route for the newly created endpoint that routes events to the Event Hub, I recommend a filter of "true" to get all events to start.
- Edit the Azure Digital Twin service definition in the IoT Bridge and enter your event hub credentials and a consumer group.
- Start the
Azure Digital Twin - Handle Changestrigger. - You can now edit the
/properties/command/stringvalue and set it towrite,3/0/15,UTCto try to write to the device. - Check the
/properties/commandReply/stringto see the result.
¶ Notes
Ensure that the trigger
LWM2M - Flatten device datais present and started. If you do not see this trigger, then re-import theLWM2M Quickstartsolution template to get the latest version of the triggers.