What is device twin in Azure IoT Hub? — JSON state for device sync

Question

What is device twin in Azure IoT Hub? — JSON state for device sync

Dhruvesh Sheladiya 0 Microsoft Employee

I am trying to understand the concept of device twins in Azure IoT Hub, specifically how they are used to maintain and synchronize device state between cloud applications and IoT devices using a JSON-based structure.

Environment Details

Azure Service: Azure IoT Hub
Feature: Device Twin
Data Format: JSON document
Communication Pattern: Cloud ↔ Device synchronization
Device State Management: Desired vs Reported state

Investigation Details / Observations

A device twin is a JSON document maintained by IoT Hub for each device. [learn.microsoft.com]
It stores device metadata, configuration, and runtime state. [learn.microsoft.com]
Device twins are automatically created when a device identity is registered. [learn.microsoft.com]
It acts as a cloud-side representation of the physical device. [oneuptime.com]
It enables state synchronization between device and backend apps, even when the device is offline. [oneuptime.com]

Core Components Observed

Tags

Metadata managed by backend apps only

Used for organizing and querying devices

Not visible to the device

Desired Properties

- Configuration/state defined by the cloud

   - Device reads and applies these settings

      - Example: telemetry interval, firmware version

      **Reported Properties**

         - Actual state reported by the device

            - Backend reads this to monitor device status

               - Example: battery level, current config

These properties work together to synchronize expected state vs actual state. [learn.microsoft.com]

Steps Followed / Investigation Done

Reviewed IoT Hub documentation on device twins
Explored device twin JSON structure
Analyzed how desired and reported properties interact
Observed lifecycle tied to device identity
Checked how backend and device apps use the twin

Mitigation / Considerations Explored

Using device twins for remote configuration of devices
Leveraging reported properties for monitoring device health/state
Using tags for querying and grouping large device fleets
Considering offline scenarios where device sync happens later

Challenges / Confusions

Difference between device twin vs direct messaging
How conflicts are resolved between desired and reported states
How often synchronization occurs between cloud and device
Limitations on size and frequency of updates

Ask / Clarification Needed

What is the best way to design desired vs reported properties?
How does IoT Hub handle synchronization when devices are offline?
What are best practices for using device twins at scale?I am trying to understand the concept of device twins in Azure IoT Hub, specifically how they are used to maintain and synchronize device state between cloud applications and IoT devices using a JSON-based structure.
Environment Details
- Azure Service: Azure IoT Hub
  - Feature: Device Twin
    - Data Format: JSON document
      - Communication Pattern: Cloud ↔ Device synchronization
        
        Device State Management: Desired vs Reported state
Investigation Details / Observations
- A device twin is a JSON document maintained by IoT Hub for each device. [learn.microsoft.com]
  - It stores device metadata, configuration, and runtime state. [learn.microsoft.com]
    - Device twins are automatically created when a device identity is registered. [learn.microsoft.com]
      - It acts as a cloud-side representation of the physical device. [oneuptime.com]
        
        It enables state synchronization between device and backend apps, even when the device is offline. [oneuptime.com]
Core Components Observed
Tags
```
     - Metadata managed by backend apps only

           - Used for organizing and querying devices

                 - Not visible to the device

                    **Desired Properties**

                          - Configuration/state defined by the cloud

                                - Device reads and applies these settings

                                      - Example: telemetry interval, firmware version

                                         **Reported Properties**

                                               - Actual state reported by the device

                                                     - Backend reads this to monitor device status

                                                           - Example: battery level, current config
```
These properties work together to synchronize expected state vs actual state. [learn.microsoft.com]
Steps Followed / Investigation Done
- Reviewed IoT Hub documentation on device twins
  - Explored device twin JSON structure
    - Analyzed how desired and reported properties interact
      - Observed lifecycle tied to device identity
        
        Checked how backend and device apps use the twin
Mitigation / Considerations Explored
- Using device twins for remote configuration of devices
  - Leveraging reported properties for monitoring device health/state
    - Using tags for querying and grouping large device fleets
      - Considering offline scenarios where device sync happens later
Challenges / Confusions
- Difference between device twin vs direct messaging
  - How conflicts are resolved between desired and reported states
    - How often synchronization occurs between cloud and device
      - Limitations on size and frequency of updates
Ask / Clarification Needed
- What is the best way to design desired vs reported properties?
- How does IoT Hub handle synchronization when devices are offline?
- What are best practices for using device twins at scale?

Karnam Venkata Rajeswari 2,800 Reputation points Microsoft External Staff Moderator

2026-05-14T19:56:27.7233333+00:00
Hello @Dhruvesh Sheladiya ,

Welcome to Microsoft Q&A .Thank you for reaching out to us.

A device twin in Azure IoT Hub is a cloud‑maintained JSON document automatically created for every registered device. It acts as a persistent digital representation of a physical device and enables reliable, state‑based synchronization between cloud applications and devices, even when connectivity is intermittent or unavailable.

A key principle is that a device twin always stores only the latest known state, not a history of changes. This makes it a state synchronization mechanism rather than a messaging or event system.

Please refer the following

Understand Azure IoT Hub device twins - Azure IoT Hub | Microsoft Learn

The device twins are structured as follows -

Each device twin consists of the following components:

Device Identity Metadata - Read‑only fields maintained by IoT Hub, such as device ID and generation ID, representing the device identity in the registry.

Tags - Cloud‑only metadata used for device grouping, filtering, and querying at scale. Tags are not visible to device applications and are managed exclusively by back‑end applications.

Desired Properties (Cloud > Device Intent) - Desired properties represent the target configuration or expected state defined by cloud applications. Examples include telemetry intervals, target firmware versions, and configuration policies. Only the latest desired state is stored, and intermediate updates are not queued. Devices receive the latest desired configuration when connectivity is available.

Reported Properties (Device > Cloud Reality) - Reported properties represent the actual device state reported by the device application. This includes applied configuration, runtime status, and health indicators such as battery level or firmware version. These properties allow cloud applications to compare expected versus actual state.

Metadata and Versioning - Each desired and reported section includes a $version field, and the twin uses an etag to support optimistic concurrency control. Versioning ensures consistent updates when multiple services interact with the same twin.

Synchronization works as follows -

Device twin synchronization is event‑driven and eventually consistent and not real‑time.

When a device is online, desired property updates are delivered immediately through the active IoT Hub connection. The device applies the configuration and updates reported properties to confirm the applied state.

When a device is offline, IoT Hub does not queue individual desired property notifications. Instead, only the latest desired state is retained. Upon reconnection, the device retrieves the full twin document, receives the latest desired properties snapshot, applies the configuration, and updates reported properties accordingly. Intermediate updates are not replayed, ensuring the device always converges to the most recent state.

Please refer the following - Understand Azure IoT Hub device twins - Azure IoT Hub | Microsoft Learn

For designing desired vs reported properties effectively -

Desired properties should model configuration intent, remain stable, and avoid high‑frequency or runtime data. Reported properties should reflect actual device state, confirm applied configurations, and include timestamps or error details where relevant.

A simple guiding principle applies: desired properties represent what is intended, while reported properties represent what is actually achieved. This separation enables reliable configuration tracking and rollout validation.

As for Device Twins vs Direct Methods :

Device twins are designed for persistent state synchronization and configuration management, supporting offline scenarios and long‑term reconciliation of device state. In contrast, direct methods are intended for immediate, time‑sensitive commands such as rebooting a device or running diagnostics and require the device to be online at the time of invocation. Device twins do not provide real‑time responses, while direct methods do. As a result, device twins are best suited for configuration, compliance tracking, and firmware rollout scenarios, whereas direct methods are appropriate for operational commands.

For using using device twins at scale

For large device fleets, the following practices are recommended:

Use tags to group devices by region, type, or business context

Use queries to target subsets of devices

Perform bulk updates using IoT Hub Jobs

Avoid frequent or high‑volume twin updates

Use etag and $version to ensure safe concurrent updates

Please refer the following - https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-query-language

Limits and troubleshooting considerations:

The total device twin size limit is approximately 64 KB, with 8 KB for tags, 32 KB for desired properties, and 32 KB for reported properties. Property nesting depth is limited to five levels, and update rates are subject to IoT Hub tier‑based throttling.

Please check the following troubleshooting steps if in need-

Verifying that desired property $version increments after updates

Confirming that device SDK callbacks receive desired property changes

Ensuring reported properties are updated after configuration is applied

Checking throttling or quota errors during bulk updates

Validating reconnect behavior for offline devices

Confirming correct etag usage when multiple services update the same twin

Please let us know if the above response was helpful

Thank you
Karnam Venkata Rajeswari 2,800 Reputation points Microsoft External Staff Moderator

2026-05-15T18:45:34.5833333+00:00

Hello @Dhruvesh Sheladiya ,

Checking in to see if the above response was helpful

Thank you

1 answer

Your answer

Karnam Venkata Rajeswari 2,800 Reputation points Microsoft External Staff Moderator

2026-05-15T18:45:34.5833333+00:00

Hello @Dhruvesh Sheladiya ,

Checking in to see if the above response was helpful

Thank you

Answer 1

A device twin in Azure IoT Hub is a JSON document that IoT Hub maintains for each device identity. It stores device-related information such as metadata, configuration, and state, and is used by device apps and back-end apps to synchronize device conditions and configuration and to query and target long-running operations.

Key characteristics:

Automatically created and deleted with the device identity in the IoT Hub identity registry.
Used to store and sync:
- Device-specific metadata (for example, location, device type).
- Configuration and runtime state (for example, connectivity method, firmware rollout state).
Enables back-end apps to manage devices even when they are offline; the device reconciles state when it reconnects.

Structure of a device twin JSON document:

Device identity properties (root)
- Read-only properties that mirror the corresponding device identity in the identity registry.
Tags
- Cloud-only metadata.
- Read/write by back-end apps; not visible to device apps.
- Used to organize and query devices (for example, by location, function, or device type).
Desired properties
- Set by back-end apps to express the desired configuration or state.
- Read by device apps; device apps can subscribe to change notifications.
- Used together with reported properties to synchronize configuration or conditions (for example, desired firmware version, telemetry interval).
Reported properties
- Set by device apps to report current configuration or state.
- Read and queried by back-end apps.
- Used together with desired properties to track progress and actual state (for example, current firmware version, battery level, connectivity method).
Metadata and versioning
- Desired and reported properties include $version values that are guaranteed to be incremental.
- The twin has an etag for optimistic concurrency.

Synchronization and offline behavior:

Device twins support optimistic concurrency using etag on the twin and $version on desired/reported properties.
IoT Hub does not preserve desired property update notifications for disconnected devices.
Recommended reconnection flow for a device app:
1. Connect to IoT Hub.
2. Subscribe for desired property update notifications.
3. Retrieve the full desired properties document.
The device can ignore notifications whose $version is less than or equal to the version of the retrieved document, because versions always increment.
This pattern ensures that devices converge to the latest desired configuration after being offline.

Designing desired vs reported properties:

Desired properties:
- Model the configuration or target state that the back end wants devices to reach (for example, desired.telemetryInterval, desired.firmware.version).
- Back-end apps update desired properties; devices observe and apply them.
Reported properties:
- Model the actual state and capabilities of the device (for example, reported.telemetryInterval, reported.firmware.version, reported.batteryLevel).
- Devices update reported properties; back-end apps read and query them.
Together they allow the back end to compare expected vs actual state and drive workflows such as configuration rollout or firmware updates.

Using device twins at scale:

Tags and reported properties can be queried by back-end apps to select subsets of devices (for example, all devices in a region with a specific capability or state) and to target long-running operations.
Optimistic concurrency with etag and $version should be used to ensure consistent updates when multiple actors update twins.

Programming model:

Device apps and service (back-end) apps use Azure IoT SDKs (.NET, Node.js, Python, Java) to:
- Device apps: handle desired property updates and update reported properties.
- Service apps: update tags and desired properties and query devices based on twin values.

These behaviors and patterns are available only in the standard tier of IoT Hub.

References:

Share via

What is device twin in Azure IoT Hub? — JSON state for device sync

Environment Details

Investigation Details / Observations

Core Components Observed

Steps Followed / Investigation Done

Mitigation / Considerations Explored

Challenges / Confusions

Ask / Clarification Needed

Environment Details

Investigation Details / Observations

Core Components Observed

Steps Followed / Investigation Done

Mitigation / Considerations Explored

Challenges / Confusions

Ask / Clarification Needed

1 answer

Your answer