Device connectivity and telemetry ingress

  • Article

Important

A new version of the Azure Digital Twins service has been released. In light of the new service's expanded capabilities, the original Azure Digital Twins service (described in this documentation set) has been retired.

To view the documentation for the new service, visit the active Azure Digital Twins Documentation.

The telemetry data sent by devices and sensors form the backbone of any IoT solution. How to represent these different resources and manage them within the context of a location are chief concerns in IoT app development. Azure Digital Twins simplifies the process of developing IoT solutions by uniting devices and sensors with a spatial intelligence graph.

To get started, create an Azure IoT Hub resource at the root of the spatial graph. The IoT Hub resource allows all devices beneath the root space to send messages. After the IoT Hub is created, register devices with sensors within the Digital Twins instance. The devices can send data to a Digital Twins service via the Azure IoT device SDK.

For a step-by-step guide on how to bring devices onboard, read the Tutorial to deploy and configure Digital Twins. At a glance, the steps are:

  • Deploy a Digital Twins instance from the Azure portal.
  • Create spaces in your graph.
  • Create an IoT Hub resource, and assign it to a space in your graph.
  • Create devices and sensors in your graph, and assign them to the spaces created in the previous steps.
  • Create a matcher to filter telemetry messages based on conditions.
  • Create a user-defined function, and assign it to a space in the graph for custom processing of your telemetry messages.
  • Assign a role to allow the user-defined function to access the graph data.
  • Get the IoT Hub device connection string from the Digital Twins Management APIs.
  • Configure the device connection string on the device with the Azure IoT device SDK.

In the following sections, you learn how to get the IoT Hub device connection string from the Digital Twins Management API. You also learn how to use the IoT Hub telemetry message format to send sensor-based telemetry. Digital Twins requires each piece of telemetry that it receives to be associated with a sensor within the spatial graph. This requirement makes sure the data is processed and routed within the appropriate spatial context.

Get the IoT Hub device connection string from the Management API

In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Name Replace with
YOUR_INSTANCE_NAME The name of your Azure Digital Twins instance
YOUR_LOCATION The region your instance is hosted on

Do a GET call on the Device API with an includes=ConnectionString parameter to get the IoT Hub device connection string. Filter by the device GUID or the hardware ID to find the given device.

YOUR_MANAGEMENT_API_URL/devices/YOUR_DEVICE_GUID?includes=ConnectionString
Parameter Replace with
YOUR_DEVICE_GUID The device ID 
YOUR_MANAGEMENT_API_URL/devices?HardwareIds=YOUR_DEVICE_HARDWARE_ID&includes=ConnectionString
Parameter value Replace with
YOUR_DEVICE_HARDWARE_ID The device hardware ID

In the response payload, copy the device's connectionString property. You use it when you call the Azure IoT device SDK to send data to Digital Twins.

Device-to-cloud message

You can customize your device's message format and payload to fit your solution's needs. Use any data contract that can be serialized into a byte array or stream that's supported by the Azure IoT Device Client Message class, Message(byte[] byteArray). The message can be a custom binary format of your choice, as long as you decode the data contract in a corresponding user-defined function. There's only one requirement for a device-to-cloud message. Maintain a set of properties to make sure your message is routed appropriately to the processing engine.

Telemetry properties

The payload contents of a Message can be arbitrary data up to 256 KB in size. There are a few requirements expected for properties of the Message.Properties type. The table shows the required and optional properties supported by the system.

Property name Value Required Description
DigitalTwins-Telemetry 1.0 Yes A constant value that identifies a message to the system.
DigitalTwins-SensorHardwareId string(72) Yes A unique identifier of the sensor that sends the Message. This value must match an object's HardwareId property for the system to process it. For example, 00FF0643BE88-CO2.
CreationTimeUtc string No An ISO 8601 formatted date string that identifies the sampling time of the payload. For example, 2018-09-20T07:35:00.8587882-07:00.
CorrelationId string No A UUID that's used to trace events across the system. For example, cec16751-ab27-405d-8fe6-c68e1412ce1f.

Send your message to Digital Twins

Use the DeviceClient SendEventAsync or SendEventBatchAsync call to send your message to Digital Twins.

Next steps