¶ Azure IoT Hub
This page contains detailed information about the Azure IoT Hub service in the Tartabit IoT Bridge. This service lets you integrate LPWAN devices as devices in Azure HoT Hub. The Tartabit IoT Bridge acts as a proxy, when an action is executed on an Azure IoT service instance, the platform will connect to Azure IoT Hub. The connector can use DPS or a service connection to establish device connections
Connections to an Azure IoT Hub instance are managed at two levels:
- The Azure IoT Hub Service in the IoT Bridge contains the key information to establish a service connection to the Azure IoT Hub. To connect to multiple Azure IoT Hub instances, you can define multiple services. You will select which service to use by specifying the appropriate service key when you invoke an action.
- Device in the Azure IoT Hub is referenced by a deviceID, this field is available in both actions and events. The most common paradigm is to map the deviceID with the endpoint key in the IoT Bridge by using the event.endpoint.key as the deviceID when calling actions.
¶ Features
- Connection management
- When an action is executed on a service, the platform will establish a connection to Azure IoT Hub.
- Connections will be maintained until the timeout value (see below) is reached. If there is no activity within the alloted window, the connection will be terminated.
- If the device does not exist in the IoT Hub instance, then the platform will automatically create a new device on the user's behalf.
- Supported messaging
- Send device-to-cloud
- Receive cloud-to-device
- Retrieve twin updates
- Send twin updates
- Receive direct methods
- Direct methods
- NOT supported today: file uploads
- Service connection (does not work with DPS based authentication)
- Retrieve device twin
- Update device tags and desired properties
- Get device information
¶ Service
The Azure IoT Hub service contains the information required to establish a service connection to Azure for the purpose of dynamically creating and retrieving device configurations.
¶ Service Parameters
¶ General
- Authentication: Select between
ServiceAccountorDPSto select between which mechanism should be used to manage and create device connections to your IoT Hub. - Connection String: If you use
ServiceAccountauthentication, then you must supply a connection string from your Azure IoT Hub instance. The connection string requires The shared access policy must haveRegistry Read,Registry Write,Service Connect, andDevice Connectpermissions. - DPS ID Scope: If you use
DPSauthentication, then you need to supply the ID Scope associated with your DPS registration. - DPS Access Key: If you use
DPSauthentication, then you need to supply the access key associated with a group enrollment in your DPS account. - Activity timeout: Timeout used to disconnect idle IoT Hub connections, value is in seconds.
- Subscribe for twin updates: Subscribe for updates for changes that occur to the device twin.
- DTDL Model ID: The Digital Twin Definition Language (DTDL) model ID used for Azure PNP. Each device will report this model ID when connecting. If devices need to report a different model, you can define multiple services.
¶ Trigger Events
¶ azure-iot-direct-method
This event fires when a direct method is executed on a connected device. A common design paradigm is to filter the trigger by the method name. You can apply the filter by defining a custom rule method == mymethod. Currently only an exact match is supported.
{
"payload":{
"key1":"abc",
"key2":456
},
"method":"mymethod",
"replyId":"alskdfjaawper"
}
- payload: An object containing the JSON data sent in the method invokation. The method must send a JSON payload.
- method: The name of the method being invoked.
- replyId: A replyId handle required by the azure_iot.method_complete() call to complete the method request.
¶ azure-iot-event
This event fires whenever a cloud-to-device message is received.
{
"deviceId": "mydevice",
"data":{
"key1":"abc",
"key2":456
},
"properties":{
"prop1":"fast"
}
}
- deviceId: The deviceId in Azure IoT Hub for the device targetted by the method.
- data: Data can be either an object, a string, or a hex-encoded string based on the input data to the event. If the data is JSON it will be returned as an object, if the data is not JSON, but is a valid UTF-8 encoded string it will be supplied as a string, otherwise it will be returned as a hex encoded string for you to process.
- properties: Properties is an optional object that will be populated with any properties sent in the C2D message to the device.
¶ azure-iot-twin-update
This event fires when twins are updated.
{
"deviceId": "mydevice",
"state": {
"field1": "abc",
"field2": "def"
}
}
- deviceId: The deviceId in Azure IoT Hub for the device targetted by the method.
- state: The desired state sent in the update.
¶ Trigger Actions
¶ Common input parameters
- serviceKey: The platform endpoint key to find the client to communicate with. Note that this is the platform endpoint, not the LWM2M endpoint key.
- deviceId: The deviceId within Azure IoT Hub.
¶ azure_iot.send(serviceKey, deviceId, payload[, properties])
Send telemetry data as a device to cloud message.
// Send telemetry message from 'mydevice'.
azure_iot.send('mydevice','mydevice', {"field1": "abc", "field2": 456})
// Send telemetry message from 'mydevice' with properties.
azure_iot.send('mydevice','mydevice', {"field1": "abc", "field2": 456}, {"prop1": "value"})
- payload: Payload can be text or JSON data that is to be sent to the IoT Hub.
- properties: Optional object that contains key/value pairs to be sent as properties with the message.
¶ azure_iot.twin_retrieve(serviceKey, deviceId)
Retrieve the current state of a device twin.
// Update 'mydevice' twin with new data.
var twin = azure_iot.twin_retrieve('myservice', 'mydevice')
- twin: The return from this function will be an object with two properties
desiredandreportedcontaining objects with the relevelant twin properties.
¶ azure_iot.twin_update(serviceKey, deviceId, state)
Send an update to the reported state of the device twin.
// Update 'mydevice' twin with new data.
azure_iot.twin_update('myservice', 'mydevice',{"field1":"abc123", "field2": "def456"})
- state: The state is an object that represents the new data you want to update in the device twin. It will update only the values that were submitted.
- data: Data should be an object that represents the instance to be created.
¶ azure_iot.method_complete(serviceKey, deviceId, replyId, reply)
Complete a direct method that was received for a device. This call must be invoked or the method will timeout on the server. A common pattern is to invoke this function within a trigger that handles the incoming method receiver.
// Reply to a method from within a trigger fired when a method is received.
azure_iot.method_complete('myservice', 'mydevice', event.data.replyId,{"replyField":"reply value"})
- replyId: The unique ID for the method request that must be sent in the response.
- reply: An object that contains data to be passed back to the server as the response to the method.
On 2021-02-25 the iot_hub.method_update() function signature was changed. It now requires 4 paremeters instead of 2, after the upgrade, your triggers will fail until you update your triggers to supply the new parameters. This fixes a problem with method replies being lost.
¶ azure_iot.device_get(serviceKey, deviceId)
Use the service API to get the device definition from IoT Hub. Note this function does not work if using DPS.
// Get "mydevice" from IoT Hub
var dev = azure_iot.device_get('myservice', 'mydevice')
- return object return object is defined by Microsoft and is subject to change over time: https://learn.microsoft.com/en-us/rest/api/iothub/service/devices/get-identity
{
"authentication": {
"symmetricKey": {
"primaryKey": "<key>",
"secondaryKey": "<key>"
},
"type": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
}
},
"capabilities": {
"iotEdge": false
},
"cloudToDeviceMessageCount": 0,
"connectionState": "Connected",
"connectionStateUpdatedTime": "2022-09-28T14:20:00.8680052Z",
"deviceId": "mydevice",
"etag": "NTE4MDc1NDc4",
"generationId": "637970416805287223",
"lastActivityTime": "0001-01-01T00:00:00Z",
"status": "enabled",
"statusReason": null,
"statusUpdatedTime": "0001-01-01T00:00:00Z"
}
¶ azure_iot.device_update(serviceKey, deviceId, desired, tags)
Use the service API to set the desired twin properties and/or tags on a device. Note this function does not work if using DPS.
// Update 'mydevice' with desired twin properties and tags.
azure_iot.device_update('myservice', 'mydevice',{"field1":"abc123", "field2": "def456"}, {"tag1", "value1"})
// Update 'mydevice' with only desired twin properties.
azure_iot.device_update('myservice', 'mydevice',{"field1":"abc123", "field2": "def456"}, {"tag1", "value1"})
- desired: The desired argument is an object that represents the new data you want to set as desired changes in the device twin. It will update only the values that were submitted.
- tags: Tags is an object with key/value pairs that must be strings to add tags to a device.
¶ azure_iot.twin_get(serviceKey, deviceId)
Use the service API to get the twin from IoT Hub using the service API. Note this function does not work if using DPS.
// Get "mydevice" from IoT Hub
var twin = azure_iot.twin_get('myservice', 'mydevice')
- return object return object is defined by Microsoft and is subject to change over time: https://learn.microsoft.com/en-us/rest/api/iothub/service/devices/get-twin
{
"authenticationType": "sas",
"capabilities": {
"iotEdge": false
},
"cloudToDeviceMessageCount": 0,
"connectionState": "Connected",
"deviceEtag": "NTE4MDc1NDc4",
"deviceId": "mydevice",
"etag": "AAAAAAAAAAI=",
"lastActivityTime": "0001-01-01T00:00:00Z",
"properties": {
"desired": {
},
"reported": {
}
},
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00Z",
"tags": {
"tag1": "foo"
},
"version": 7,
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
}
}
¶ Notes for IoT Central
¶ Telemetry properties
The following properties can be added on an azure_iot.send() call to enrich the data for IoT Central.
- iothub-creation-time-utc: Timestamp in RFC3339 format that will be used to indicate the time that telemetry was received.
- $.sub: The sub-component of the mdoel to publish to, note that you can only publish to one component in a message.
¶ Twin properties
- Twin properties need to be wrapped in an object with the name of the component:
var props = { mycomponent: { '__t': 'c', myprop: 'value'}}
¶ Billable events
The following events are considered billable:
- Send device-to-cloud message
- Receive cloud-to-device message
- Receive direct method
- Receiving twin updates
- Sending twin updates
The following events are NOT billable:
- Completing methods (calling azure_iot.method_complete())
¶ Notes
Once established, connections will automatically reconnect until the activity timer expires. This can create issues if you attempt to connect to IoT Hub using the same deviceId as the two will continue to compete for the connection.
On 2021-02-25 the iot_hub.method_update() function signature was changed. It now requires 4 paremeters instead of 2, after the upgrade, your triggers will fail until you update your triggers to supply the new parameters.