IoT 中心的设备更新和 IoT 即插即用

2022-01-26

IoT 中心的设备更新使用 IoT 即插即用以发现和管理支持无线更新的设备。设备更新服务使用 IoT 即插即用接口在不同设备之间收发属性和消息。 Device Update for IoT Hub 要求 IoT 设备实现以下接口和型号 ID。

参考信息：

了解 IoT 即插即用设备客户端。
查看如何实现设备更新代理。

Device Update 核心接口

“DeviceUpdateCore”接口用于向设备发送更新操作和元数据，并从设备接收更新状态。 “DeviceUpdateCore”接口拆分为两个对象属性。

实现此接口时，模型中的预期组件名称为“deviceUpdate”。详细了解 Azure IoT 即插即用组件。

代理元数据

Device Update 代理使用代理元数据字段将信息发送到 Device Update 服务。

名称	架构	方向	说明	示例
deviceProperties	映射	设备到云	一组属性，其中包含制造商、型号和其他设备信息。	有关详细信息，请参阅设备属性部分。
compatPropertyNames	字符串（以英文逗号分隔）	设备到云	设备报告用于检查设备兼容性的属性，以针对更新部署。限制为五个设备属性。	"compatPropertyNames": "manufacturer,model"
lastInstallResult	映射	设备到云	代理报告的结果。它包含结果代码、扩展结果代码以及主要更新和其他步骤更新结果的详细信息。
resultCode	integer	设备到云	此代码包含上次更新操作结果的信息。可能填充成功，也可能填充失败。	700
extendedResultCode	integer	设备到云	此代码包含结果的其他信息。可能填充成功，也可能填充失败。	0x80004005
resultDetails	字符串	设备到云	客户定义的自由格式字符串，用于提供更多结果详细信息。已返回到未解析的孪生体
stepResults	map	设备到云	由包含结果代码、扩展结果代码和步骤更新结果详细信息的代理报告的结果。	"step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	integer	设备到云	此整数用于指示 Device Update 代理的当前状态。	有关详细信息，请参阅状态部分。
工作流	complex	设备到云	一组值，用于指示代理当前正在处理的部署、当前部署的 ID 以及从服务发送到代理的任何重试请求的确认。	"workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	设备到云	当前（通过设备更新）安装的更新 ID。此值是一个字符串，用于捕获更新 ID JSON，对于从未通过 Device Update 进行更新的设备，此值将为 NULL。	installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}"

设备属性

deviceProperties 字段包含设备的制造商和型号信息。

名称	架构	方向	描述
制造商	string	设备到云	设备的制造商，通过 `deviceProperties` 报告。可以从两个位置的任何一个位置读取此属性 - DeviceUpdateCore 接口首先尝试从配置文件中读取“aduc_manufacturer”值。如果未在配置文件中填充该值，默认情况下会报告 ADUC_DEVICEPROPERTIES_MANUFACTURER 的编译时定义。仅在启动时报告此属性。默认值：“Contoso”。
模型	string	设备到云	设备的型号，通过 `deviceProperties` 报告。可以从两个位置的任何一个位置读取此属性 - DeviceUpdateCore 接口首先尝试从配置文件中读取“'aduc_model”值。如果未在配置文件中填充该值，默认情况下会报告 ADUC_DEVICEPROPERTIES_MODEL 的编译时定义。仅在启动时报告此属性。默认值：“Video”
interfaceId	字符串	设备到云	服务使用此属性来标识设备更新代理使用的接口版本。 Device Update 服务需要接口 ID 来管理代理并与代理通信。默认值：“dtmi:azure:iot:deviceUpdate;1”（针对使用 DU 代理版本 0.8.0 的设备）。
aduVer	string	设备到云	设备上运行的设备更新代理的版本。仅在编译时 ENABLE_ADU_TELEMETRY_REPORTING 设置为 1 (true) 的情况下，才从生成中读取该值。客户可以通过将该值设置为 0 (false) 选择退出版本报告。如何自定义设备更新代理属性。
doVer	string	设备到云	设备上运行的传递优化代理的版本。仅在编译时 ENABLE_ADU_TELEMETRY_REPORTING 设置为 1 (true) 的情况下，才从生成中读取该值。客户可以通过将该值设置为 0 (false) 选择退出版本报告。如何自定义传递优化代理属性。
自定义兼容性属性	用户定义	设备到云	实现者可以定义其他设备属性，以便在针对更新部署时用于兼容性检查。

IoT 中心设备孪生示例：

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "interfaceId": "dtmi:azure:iot:deviceUpdateModel;1",
                        "aduVer": "DU;agent/0.8.0-rc1-public-preview",
                        "doVer": "DU;lib/v0.6.0+20211001.174458.c8c4051,DU;agent/v0.6.0+20211001.174418.c8c4051"
                    },
                    "compatPropertyNames": "manufacturer,model",
                    "lastInstallResult": {
                        "resultCode": 700,
                        "extendedResultCode": 0,
                        "resultDetails": "",
                        "stepResults": {
                            "step_0": {
                                "resultCode": 700,
                                "extendedResultCode": 0,
                                "resultDetails": ""
                            }
                        }
                    },
                    "state": 0,
                    "workflow": {
                        "action": 3,
                        "id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
                        "retryTimestamp": "2022-01-26T11:33:29.9680598Z"
                    },
                    "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
                },

注意

设备或模块必须添加 {"__t": "c"} 标记以指示元素引用组件。有关详细信息，请参阅 IoT 即插即用约定。

State

“状态”字段是指从 Device Update 服务接收操作后 Device Update (DU) 代理所报告的状态。系统会报告状态，以响应从 Device Update 服务发送到 Device Update 代理的操作（有关详细信息，请参阅操作部分）。若要详细了解在 Device Update 服务和 Device Update 代理之间流动的请求，请参阅概述工作流。

名称	值	说明
闲置	0	设备已准备就绪，可以接收来自设备更新服务的操作。更新成功后，状态返回到 `Idle`。
DeploymentInprogress	6	正在进行部署。
已失败	255	更新时出错。
DownloadSucceeded	2	下载成功。此状态仅由代理版本为 0.7.0 或更低的设备报告。
InstallSucceeded	4	安装成功。此状态仅由代理版本为 0.7.0 或更低的设备报告。

服务元数据

Device Update 服务会使用服务元数据中包含的字段向 Device Update 代理传达操作和数据。

名称	架构	方向	说明
action	integer	云到设备	此整数与代理应执行的操作相对应。有关详细信息，请参阅操作部分。
updateManifest	string	云到设备	用于描述更新的内容。根据导入清单生成。
updateManifestSignature	JSON 对象	云到设备	JSON Web 签名 (JWS)，具有用于源验证的 JSON Web 密钥。
fileUrls	映射	云到设备	`FileID` 到 `DownloadUrl` 的映射。告知代理要下载的文件以及用于验证文件是否正确下载的哈希。

操作

action 字段表示 Device Update 代理按照 Device Update 服务的指示所执行的操作。 Device Update 代理将报告处理收到的操作状态。若要详细了解在 Device Update 服务和 Device Update 代理之间流动的请求，请参阅概述工作流。

名称	值	说明
applyDeployment	3	应用更新。它向设备发出信号以应用已部署的更新
cancel	255	停止处理当前操作，并返回到 `Idle`，或告知状态为 `Failed` 的代理返回到 `Idle`。
下载	0	下载已发布的内容或更新以及任何其他所需内容。此操作仅发送到代理版本为 0.7.0 或更旧版本的设备。
安装	1	安装内容或更新。通常，此操作意味着调用内容或更新的安装程序。此操作仅发送到代理版本为 0.7.0 或更旧版本的设备。
apply	2	完成更新。必要时，它会指示系统重新启动。此操作仅发送到代理版本为 0.7.0 或更旧版本的设备。

设备信息接口

设备信息接口是 IoT 即插即用体系结构中使用的概念。它包含设备到云的属性，这些属性提供有关设备硬件和操作系统的信息。 Device Update for IoT Hub 使用 DeviceInformation.manufacturer 和 DeviceInformation.model 属性进行遥测和诊断。若要了解详细信息，请参阅此设备信息接口示例。

实现此接口时，模型中的预期组件名称是 deviceInformation。了解 Azure IoT 即插即用组件

名称	类型	架构	方向	说明	示例
制造商	属性	string	设备到云	设备制造商的公司名称。此属性可能与原始设备制造商 (OEM) 的名称相同。	Contoso
模型	属性	string	设备到云	设备型号名称或 ID。	IoT Edge 设备
swVersion	属性	string	设备到云	设备上的软件版本。 swVersion 可能是固件版本。	4.15.0-122
osName	属性	string	设备到云	设备上的操作系统名称。	Ubuntu Server 18.04
processorArchitecture	属性	string	设备到云	设备上处理器的体系结构。	ARM64
processorManufacturer	属性	string	设备到云	设备上处理器制造商的名称。	Microsoft
totalStorage	属性	string	设备到云	设备上的可用存储总量（以千字节为单位）。	2048
totalMemory	属性	string	设备到云	设备上的可用内存总量（以千字节为单位）。	256

模型 ID

模型 ID 是智能设备通过 IoT 即插即用向 Azure IoT 应用程序发布其功能的方式。若要了解如何构建智能设备以向 Azure IoT 应用程序发布其功能的详细信息，请访问《IoT 即插即用设备开发人员指南》。

Device Update for IoT Hub 要求 IoT 即插即用智能设备在设备连接过程中公布值为“dtmi:azure:iot:deviceUpdateModel;1” 的模型 ID。了解如何公布模型 ID。

通过