IoT Plug and Play DTDL模型中设备孪生期望与上报属性配置

问题背景 #

在IoT Plug and Play v0.15.4.0（旧版本表现一致）中上传了如下DTDL模型至本地文件夹：

{"@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"}]}

Azure门户中设备孪生显示内容：

{"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}}

用户认为ledState和Alert属性设置为writable:true后，应同时作为desired（期望）和reported（上报）属性，但设备孪生显示两者状态不同，询问如何在DTDL模型中设置属性为期望或上报类型。

核心说明与解决方案 #

1. DTDL中属性与desired/reported的映射逻辑 #

DTDL并没有直接设置属性为「期望」或「上报」的字段，而是通过writable标记属性的交互类型：

• writable: true：定义为可写属性，云端可设置该属性的desired值，设备需接收期望并上报包含状态的reported值（格式为{"ac": 状态码, "av": 期望版本, "value": 实际值}）。
• writable: false：定义为只读属性，设备仅需上报reported值，云端无法设置desired值。

你的DTDL对ledState和Alert的标记是正确的，问题出在设备端的逻辑实现，而非DTDL定义。

2. 当前设备孪生差异的原因 #

从提供的设备孪生数据来看：

• Alert：云端已设置desired值，但设备未上报对应的reported值（缺少状态码、版本和实际值），因此reported中无该属性条目。
• ledState：设备上报了reported值，但云端未设置过desired值，同时设备端未处理云端发送的desired更新请求，因此desired中无该属性条目。
• telemetryInterval：设备端实现了完整逻辑，所以同时存在desired和带状态的reported值。

3. 解决步骤 #

（1）无需修改DTDL

你的DTDL已正确标记writable: true，符合可写属性的定义要求。

（2）设备端补全可写属性逻辑

针对Alert和ledState，设备端需要实现以下逻辑：

• 监听云端发送的desired属性更新事件；
• 根据期望值执行对应操作（如控制LED开关、触发维护提醒）；
• 上报reported属性，格式需包含：
  • ac：状态码（200表示成功执行，400表示参数无效，500表示执行失败）；
  • av：对应云端desired属性的版本号；
  • value：执行后的实际属性值。

（3）云端设置对应属性的期望

在Azure门户或通过API给ledState设置desired值，设备端接收并上报后，即可在设备孪生中看到该属性的desired和reported条目。

内容的提问来源于stack exchange，提问作者Sergio Solorzano