Skip to content

Device configurations synchronization

Overview

Device configurations are useful for:

  • setting desired configurations for a device

  • receiving device state from a device

Depending on how the device is provisioned, the means of communication will be different for these operations.

IoT Hub

The device will be able to receive desired configurations by listening to the desired IoT Hub Twin property changes.

It will send its device state by updating its reported IoT Hub Twin properties.

HTTP

The device will read and update its configuration directly by calling the Management API, authenticating itself with its HTTP secret.

On-behalf

A user can update the device's state by calling the same Management API endpoints, authenticating with its own Bearer token.


This piece of documentation will walk you through how the device configurations gets updated, especially when it involves an intermediary tool such as IoT Hub Twins.

Desired configurations

Only users can update desired configurations for devices.

IoT Hub

Any change to the desired configuration will get updated in the IoT Hub Twins, as long as the device is provisioned on IoT Hub.

When a device with an existing desired configuration gets provisioned on IoT Hub, the current desired configuration will be forwarded to the IoT Hub Twins after the provisioning.

HTTP

Changes made to a desired device configuration are not forwarded anywhere for the HTTP channel.

Devices poll for changes by calling the API directly.

On-behalf

Desired configurations cannot be read on-behalf: you can simply view the current desired configuration as a user.

Synchronization

Overall, desired configurations do not get out of sync by only using the API, since only users can initiate a desired configuration change.

The device's desired IoT Hub Twin properties and its desired configuration in the API can get out of sync:

  • If the device's desired Twin property is changed manually on the IoT Hub, which bypasses the API

If needed, you can fix inconsistencies like this:

Example

Desired configuration on the API:

temperature: 45

Desired Twin properties:

temperature: 44
h: 23

But we want the configuration on both sides to be:

temperature: 45
humidity: 23

You can solve this situation by:

  • Sending a PUT request to the API to replace the existing configuration with temperature: 45 and humidity: 23. This will completely replace all existing desired configuration on both the API and IoT Hub Twins.

Device state

Devices can update their state by communicating through their channel (possibly multiple channels), and users can update a device state by doing so on behalf of a device, as long as they have the necessary access rights.

IoT Hub

Devices send their state by using their IoT Hub Twin reported properties.

The API listens to all IoT Hub reported Twin changes and updates the current state accordingly.

Each Twin change is held in a Service Bus topic before being processed by the API. This way, the API can be shut down and restarted without missing out on Twin updates.

HTTP

Devices report their state by calling the API directly.

On-behalf

Users can report a device's state by calling the API directly.

Synchronization

Since there are multiple ways to update a device's state, it is important to interpret the known state carefully.

The device's reported IoT Hub Twin properties and its reported state in the API can get out of sync:

  • If the device is deprovisioned then provisioned again on IoT Hub. The IoT Hub reported Twins will be empty, but the API will still remember its state.
  • If the device's state is updated on-behalf
  • If the device's state is updated by HTTP (when the device is also provisioned on HTTP)

However it is not necessarily an issue if the reported state in the API is different from the reported Twins in IoT Hub.

As a simple rule: all reported changes are updated in the API, but the API does not forward these changes to the device's channels. The API only reflects the last known device state, by aggregating state from all the channels it gets updates from.