What OSConfig users need to know about "plain desired/reported" vs "DTDL enhanced" toolchains

When reading OSConfig docs and trying out scenarios through different tools, it can be helpful to understand that in the Azure IoT ecosystem there are two perspectives for describing twin contents.

Perspective 1: Plain desired/reported

Desired and reported properties make up the core IoT Hub object model. Most tools and services use this plain desired/reported perspective. For example:

• The IoT Hub Query service
• The IoT Hub Configurations service
• The az iot hub module-twin commands
• The Iot Hub twin views in the Azure portal
• The plain twin views in IoT Explorer

The plain desired/reported perspective could be described as a JSON document where:

1. Actual state (such as current configuration or status) is reported by code on the device under the properties.reported section
2. Desired state (such as configuration settings from the administrator), if any, is added by admin tools in the cloud under the properties.desired section
3. If any desired state was specified from the cloud side, the responsible code on the device acknowledges the same through additional properties in the properties.reported section.

The following example is a simplified excerpt from a device's OSConfig module twin in IoT Hub:

1. The OSConfig agent on the device always reports the current host name as properties.reported.HostName.name
2. Additionally, the administrator wanted to ensure a specific value, so on the cloud side they populated properties.desired.HostName.desiredName
3. In response to properties.desired.HostName.desiredName being populated by the admin, the OSConfig agent on the device acknowledges receipt of the same as properties.reported.HostName.desiredName.

Perspective 2: Digital Twin Definition Language (DTDL) enhanced modeling

DTDL (along with related patterns such as Azure IoT Plug and Play [PnP]) enables apps and services to anticipate, validate, and better contextualize twin contents beyond plain JSON. Tools and services which use this DTDL enhanced perspective include:

• The "Plug and Play" views in IoT Explorer
• The Azure Digital Twins service

A DTDL enhanced view of the above twin contents could be described as:

• This device/module has a component called HostName which implements the OSConfig HostName interface

• Within the HostName component/interface, there is a read-only property¹ called name whose value should be a string

• Also within the HostName component, there is a writeable property² called desiredName whose value should be a string

  ¹ In the DTDL context as applied to device agents like OSConfig, "read-only" means that the property is reported by the device, not set (directly) by the admin in the cloud
  ² In the DTDL context as applied to device agents like OSConfig, "writeable" means that the property can be set by the admin in the cloud, and that when this is received by the device there will be an acknowledgement.

The following screenshot of IoT Explorer is an example of a tool using DTDL. In this example, IoT Explorer is letting the admin know that desiredName is available to be set under HostName. The admin might not have known this was an option, especially given that the properties.desired section of the underlying twin is blank by default.

Which perspective does OSConfig documentation describe?

In OSConfig reference documentation we default to describing the plain desired/reported perspective. Where additional context for DTDL enhanced tools is applicable, that information is included in parenthesis.

For example, in CommandRunner: commandArguments (set by admin) the possible values of action are described as "1 (reboot), 2 (shutdown), 3 (RunCommand), or 4 (refreshCommandStatus)". In a plain desired/reported experience like az iot hub module-twin show you would see the numerical values. In a DTDL enhanced experience like IoT Explorer's IoT Plug and Play views, you would see the labels ("reboot", etc.)

How do I (or a tool I am using, like IoT Explorer) find the latest OSConfig DTDL models (DTMI)?

In IoT Explorer, under Home > IoT Plug and Play Settings, choose to Add a configurable repository, with the following path: raw.githubusercontent.com/Azure/azure-osconfig/main. See the following screen capture for an example.

If you want to inspect the models directly, rather than loading them in IoT Explorer, the URI is: https://github.com/Azure/azure-osconfig/tree/main/dtmi/osconfig.

Next steps

For an overview of OSConfig scenarios and capabilities, see:

• What is OSconfig for IoT

For specific practical examples, see:

• Create an OSConfig (with Azure IoT) lab environment in 5 minutes
• Quickstart: Query examples for getting started with OSConfig and Azure IoT
• What can I provision and manage?