Azure IoT Device Twins Explained: Desired vs Reported Properties
Sarah Jenkins
Principal IoT Solutions Architect
Managing the configuration of a remote IoT fleet requires a reliable, asynchronous way to sync state between your backend applications and physical edge devices. In Azure IoT Hub, this is accomplished using Device Twins.
If you are transitioning from traditional REST APIs to IoT MQTT paradigms, mastering Device Twins is essential for building a robust management layer.
What is a Device Twin?
A Device Twin is a JSON document that Azure IoT Hub maintains for every single device provisioned in your registry. It stores device state information, including metadata, configurations, and current operating conditions.
Unlike telemetry—which is fleeting and typically consumed immediately by stream analytics—the Device Twin acts as a persistent database record that can be queried even when the physical device is completely offline.
The Three Components of a Device Twin
A Device Twin consists of three main sections:
1. Tags
Tags are invisible to the physical device. They are solely meant for your backend application to organize, group, and filter devices.
Example: Tagging a device with {"region": "North America", "facility": "Plant A"} allows you to execute bulk firmware updates targeted specifically at that facility.
2. Desired Properties
Desired properties are set by the Cloud Backend and read by the Device. They represent the configuration the device should adopt.
Example: Your backend sets a desired property {"telemetryInterval": "60s"}.
3. Reported Properties
Reported properties are set by the Device and read by the Cloud Backend. They represent the device's actual current state.
Example: The device receives the new interval, updates its internal loop, and then reports back {"telemetryInterval": "60s"} to confirm the configuration was applied successfully.
The Twin Synchronization Loop
The true power of Device Twins lies in the synchronization loop:
- Command: The cloud sets a desired property (e.g.,
"targetFirmware": "v2.1"). - Action: The device comes online, receives the desired property, and begins downloading the firmware.
- Acknowledgment: Once the installation finishes, the device updates its reported property (
"currentFirmware": "v2.1"). - Validation: Your cloud application queries the twin. If
desired.targetFirmware == reported.currentFirmware, the sync is successful.
Monitoring Twin Drift
When managing tens of thousands of devices, it is inevitable that some devices will go offline or fail to apply configurations, leading to Twin Drift (where the desired state does not match the reported state).
With platforms like IoTHubX, you can automatically monitor this sync state. The Device Monitoring engine can instantly flag devices suffering from Twin Drift, ensuring your fleet remains fully compliant with your desired configurations.
Track Twin Synchronization at Scale
Don't rely on manual queries. Automatically detect offline sensors, firmware drift, and failed configuration updates.
Explore Device MonitoringFrequently Asked Questions
What is the difference between telemetry and a device twin?
Telemetry consists of high-frequency, read-only event streams (like temperature readings) sent from the device to the cloud. A Device Twin is a JSON document stored in the cloud that represents the persistent state and configuration (like firmware version or alert thresholds) of the device.
Can a device update its desired properties?
No. The backend application sets desired properties (e.g., updating a target temperature). The device can only read desired properties and update its reported properties (e.g., acknowledging that the target temperature was successfully changed).