How set desired and reported properties for device twin in IoT Plug and Play DTDL model

Question

I have this dtdl model I upload to local folder in IoT Plug and Play v0.15.4.0 (prior version behaviour is the same):

{
"@id": "dtmi:com:sergio:devkit;1",
"@type": "Interface",
"@context": [
    "dtmi:dtdl:context;2"
],
"displayName": "Machine Part -v1",
"description": "Machine Part data",
"contents": [
    {
        "@type": "Property",
        "name": "telemetryInterval",
        "displayName": "telemetryInterval",
        "description":  "The time interval of this data",
        "schema": "double",
        "writable": true
    },
    {
        "@type": "Property",
        "name": "PartId",
        "displayName": "PartId",
        "description": "The unique id of the machine part",
        "writable": true,
        "schema": "string"
    },

    {
        "@type": "Property",
        "name": "Alert",
        "displayName": "Alert",
        "description": "whether or not this machine part needs maintenance",
        "writable": true,
        "schema": "boolean"
    },
    {
        "@type": "Property",
        "name": "ledState",
        "displayName": "LED state",
        "description": "Returns the current state of the onboard LED.",
        "writable": true,
        "schema": "boolean"
    },
    {
        "@type": "Telemetry",
        "name": "Description",
        "schema": "string"
    },
    {
        "@type": "Telemetry",
        "name": "Code",
        "schema": "integer"
    },
    {
        "@type": "Telemetry",
        "name": "Temperature",
        "displayName": "Temperature",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "Humidity",
        "displayName": "Humidity",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "pressure",
        "displayName": "Pressure",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "magnetometerX",
        "displayName": "Magnetometer X / mgauss",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "magnetometerY",
        "displayName": "Magnetometer Y / mgauss",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "magnetometerZ",
        "displayName": "Magnetometer Z / mgauss",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "accelerometerX",
        "displayName": "Accelerometer X",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "accelerometerY",
        "displayName": "Accelerometer Y",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "accelerometerZ",
        "displayName": "Accelerometer Z",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "gyroscopeX",
        "displayName": "Gyroscope X",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "gyroscopeY",
        "displayName": "Gyroscope Y",
        "schema": "double"
    },
    {
        "@type": "Telemetry",
        "name": "gyroscopeZ",
        "displayName": "Gyroscope Z",
        "schema": "double"
    }
]

}

My expectation is that because properties ledState and Alert properties are writeable, these should be both reported and desired properties. However the IoT Hub Device in Azure portal (see below) shows them differently and I don't know why. How do I set the properties in the DTDL model I upload to IoT P&P to be reported or desired?

{
"deviceId": "mymxchip",
"etag": "AAAAAAAAAAk=",
"deviceEtag": "NDU1NDk0NDM4",
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00Z",
"connectionState": "Connected",
"lastActivityTime": "2023-01-09T07:26:48.611708Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
},
"modelId": "dtmi:com:sergio:devkit;1",
"version": 164,
"properties": {
    "desired": {
        "telemetryInterval": 5,
        "Alert": true,
        "$metadata": {
            "$lastUpdated": "2023-01-08T07:27:01.9659284Z",
            "$lastUpdatedVersion": 9,
            "telemetryInterval": {
                "$lastUpdated": "2023-01-08T06:54:11.9502921Z",
                "$lastUpdatedVersion": 8
            },
            "Alert": {
                "$lastUpdated": "2023-01-08T07:27:01.9659284Z",
                "$lastUpdatedVersion": 9
            }
        },
        "$version": 9
    },
    "reported": {
        "deviceInformation": {
            "__t": "c",
            "manufacturer": "MXCHIP",
            "model": "AZ3166",
            "swVersion": "1.0.0",
            "osName": "Azure RTOS",
            "processorArchitecture": "Arm Cortex M4",
            "processorManufacturer": "STMicroelectronics",
            "totalStorage": 1024,
            "totalMemory": 128
        },
        "ledState": false,
        "telemetryInterval": {
            "ac": 200,
            "av": 1,
            "value": 5
        },
        "$metadata": {
            "$lastUpdated": "2023-01-09T07:28:26.0068306Z",
            "deviceInformation": {
                "$lastUpdated": "2023-01-09T07:28:25.4599426Z",
                "__t": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "manufacturer": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "model": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "swVersion": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "osName": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "processorArchitecture": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "processorManufacturer": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "totalStorage": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                },
                "totalMemory": {
                    "$lastUpdated": "2023-01-09T07:28:25.4599426Z"
                }
            },
            "ledState": {
                "$lastUpdated": "2023-01-09T07:28:25.7411971Z"
            },
            "telemetryInterval": {
                "$lastUpdated": "2023-01-09T07:28:26.0068306Z",
                "ac": {
                    "$lastUpdated": "2023-01-09T07:28:26.0068306Z"
                },
                "av": {
                    "$lastUpdated": "2023-01-09T07:28:26.0068306Z"
                },
                "value": {
                    "$lastUpdated": "2023-01-09T07:28:26.0068306Z"
                }
            }
        },
        "$version": 155
    }
},
"capabilities": {
    "iotEdge": false
}

}

Dominic Betts · Accepted Answer · 2023-01-12T06:37:23.060

You're correct that a DTDL writable property will appear as both a reported and desired property in the device twin. However, this is dependant and the behavior of the device.

If you set a desired property using a service API, that updates the desired property value in the device twin. The device should then send an Ack when it's received and processed the desired property - in your example above, it looks as if the device has done this for the telemetryInterval property. The device hasn't acknowledged the Alert desired property update.

When the device sends a reported property, the device twin is updated with the value sent by the device. In the example above, the device has sent deviceInformation, ledState, and telemetryInterval reported properties. The telemetryInterval was sent in response to a desired property.

You can find more details here:

https://learn.microsoft.com/en-us/azure/iot-develop/concepts-convention#writable-properties
https://learn.microsoft.com/en-us/azure/iot-develop/concepts-developer-guide-device#writable-properties (device code samples in multiple languages)

To following samples for a thermostat device all illustrate how to follow the PnP conventions for writable properties:

Thank you @Dominic Betts , I'm trying to understand how it's supposed to work: should I ensure both the desired and reported properties in the device twin are updated each time a writable property is updated? i.e. they both hold the same value and are therefore synchronized? — Sergio Solorzano, Jan 10 '23 at 16:26
Hi @sergio-solorzano - that's correct. When a device receives a desired property update request - it should acknowledge that it received the update and update the reported property. I'll a list of sample code projects that illustrate this to the answer above. — Dominic Betts, Jan 12 '23 at 06:33

How set desired and reported properties for device twin in IoT Plug and Play DTDL model

1 Answers1