Skip to content

Device Configuration (and State)

The Device Configuration is a set of values that can be used by the platform user to:

  • Remotely configure a Device
  • Get a device state

Interpretation of the value is done by the device and the business application and can be used freely with JSON data types (boolean, number, string and complex object).

A configuration is composed of 5 elements:

  • Key: a unique identifier of the configuration/state. Should not exceed 255 characters and not contain whitespace, #, $ or ..
  • Desired configuration value: Cloud to Device desired configuration value for the specific key
  • Desired configuration value timestamp: a timestamp of the desired configuration value definition
  • Reported state value: a Device to Cloud reported state by the Device for the specific key
  • Reported state timestamp: a timestamp of the reported value

All timestamps are managed on Cloud side.

State and Configuration can be used jointly or independently depending on the needs.

Configuration value is optional, a Device can report a State without Desired Configuration. The State value is optional, a Desired Configuration can be defined without reported State.

Example

A Device has a Device Configuration that contains 3 elements:

  • a temperature setpoint
  • a temperature alert
  • a sensor state

Configuration keys are: temperature_setpoint, temperature_alert and sensor_state

  • Desired configuration value of temperature_setpoint is set by a user at Tue Apr 26 15:03:45 2022 for a number of 15.
    • Device will report a state at Tue Apr 26 15:05:52 2022 to confirm the value of 15 has been correctly applied.
  • Desired configuration value of temperature_alert is set by a user at Tue Apr 26 15:03:45 2022 for a JSON object of {"threshold":15}
    • There is no confirmation in a state, user cannot confirm the temperature_alert is correctly applied.
  • A reported state sensor_state is sent by the device with a string OPERATIONAL at Tue Apr 27 16:25:22 2022 to indicate the device is working well.
Key Desired configuration Reported state
temperature_setpoint 15 at Tue Apr 26 15:03:45 2022 15 at Tue Apr 26 15:05:52 2022
temperature_alert {"threshold":15} at Tue Apr 26 15:03:45 2022
sensor_state OPERATIONAL at Tue Apr 27 16:25:22 2022

There is a link between Device configuration and Channels. Indeed, the Desired Configurations are sent to the Devices through all Channels that support Cloud to Device communication.

  • Channel Azure IoT Hub uses the Device Twin mechanism to push the configurations and get the reported states.
  • Channels HTTP and HTTP on Behalf channels expose APIs to get and set configurations and states values.

To ensure consistency during device configuration, multiple values can be applied at once.

There are no predefined configurations, Users can configure each Device as expected.

Device Configuration Features

Request desired configuration

Permission

  • write.device configuration

Feature

  • a User can create and update a set of key + desired configuration value for a specific Device.
  • New keys can be created as expected without limitation
  • Configuration can be updated partially or completely
  • The configurations are sent immediately after being updated/created (No buffer or pre-configuration)
  • A timestamp is associated to the configuration to indicate when the configuration has been requested
  • All timestamps are managed on cloud side by the platform
  • Configuration is applied device per device
  • Configuration value is JSON data type (boolean, number, string and object). See example above.

Send desired configuration - IoT Hub

Permission

  • Inherit from Request desired configuration

Feature

  • A requested configuration on a Device with IoT Hub Channel configured is sent immediately using the Azure IoT Hub Device Twin mechanism.
  • IoT Hub device twin desired properties are used
  • The desired configuration is not saved if synchronizing with IoT Hub Device Twins fails.

Send desired configuration - MQTT

Permission

  • Inherit from Request desired configuration

Feature

  • A requested configuration on a Device with MQTT Channel configured is sent immediately to the MQTT Broker (RabbitMQ).
  • See the MQTT page for the topics to use.
  • The desired configuration is not saved if synchronizing with the MQTT broker fails.

Send desired configuration - HTTP

Permission

  • Inherit from Request desired configuration

Feature

  • A requested configuration on a Device with HTTP channel configured is immediately available through the dedicated device HTTP interface.
  • There is no notification mechanism in HTTP, the Device should check and pull the new configuration.

Ingest reported state

Permission

  • No permission applicable, the Device has to be authenticated depending on the Channel used (after provisioning).

Feature

  • The platform ingests all states reported by a Device and associates them with the keys and the current timestamp.
  • A device can report a state even if no desired configuration exists. The key is created on the fly with the corresponding reported Key name.
  • Reported value timestamp is given by the platform
  • Ingestion can be done on multiple Channels in parallel, the latest received value is the one available.
  • There is no historical version of the reported State. You can use Telemetries if you want a history.

Ingest reported state - IoT Hub

Permission

  • No permission applicable, the Device has to be authenticated depending on the Channel used (after provisioning).

Feature

  • The platform ingests all states reported by a Device on the IoT Hub channel based on the Device Twin properties.
  • IoT Hub device twin reported properties are used

Ingest reported state - MQTT

Permission

  • No permission applicable, the Device has to be authenticated depending on the Channel used (after provisioning).

Feature

  • The platform ingests all states reported by a Device on the MQTT channel.
  • See the MQTT page for the topics to use.
  • IoT Hub device twin reported properties are used

Ingest reported state - HTTP

Permission

  • No permission applicable, the Device has to be authenticated depending on the Channel used (after provisioning).

Feature

  • The platform ingests all states reported by a Device on the dedicated device HTTP endpoint.

Ingest reported state - On Behalf

Permission

  • write on-behalf.device configuration

Feature

  • The platform ingests all states reported by a User on the dedicated HTTP endpoint.
  • HTTP on Behalf allows users to report states on behalf of a device.
  • User needs the dedicated permission.
  • Use a dedicated HTTP endpoint for the User

Delete a desired configuration

Permission

  • write.configuration

Feature

  • A User can delete a desired configuration for a specific Device.
  • The desired configuration is removed with the key (except if there exists a reported state, in that case, only the desired configuration is removed).
  • The Device is informed when a configuration is removed.
  • The reported value is NOT removed. Device can continue to send information even if the desired value does not exist.

Read configuration and state

Permission

  • read.configuration

Feature

  • A User can read the current information including desired configuration and reported state.
  • The associated timestamp is returned with the values
  • One specific key or all keys can be read for a dedicated Device