Device Configuration (and State)

The Device Configuration is a set of value 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 use freely with JSON data type (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.

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

• Channel Azure IoTHub uses the Device Twin mechanism to push the configurations and get the reported states.
• Channels HTTP and HTTP on Behalf channels expose API 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

Synthesis table

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 configuration are sent immediately after have been 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 - IotHub

Permission

• Inherit from Request desired configuration

Feature

• A requested configuration on a Device with IotHub Channel configured is sent immediately using the Azure IoT Hub Device Twin mechanism.
• IotHub device twin desired properties are used
• The desired configuration is not saved if synchronizing with IoT Hub Device Twins 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 it with the keys and the current timestamp.
• A device can report a state even if no desired configuration exist. 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 Channel 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 - IoTHub

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 IoTHub channel based on the Device Twin properties.
• IotHub 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 user to report value on behalf of a device
• User need the dedicated permission
• Use a dedicated HTTP end point 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 it 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

Log Configuration change as Event

Permission

• Not applicable

Feature

• The system automatically logs a dedicated event as soon as a desired Configuration or a state is reported.
• Event is associated with the Device
• Desired configuration event is "config_apply" and the payload contains only the key
• Reported state event is "config_state_received" and the payload contains only the key