Device Update for IoT Hub and IoT Plug and Play

Article
1/26/2022

Device Update for IoT Hub uses IoT Plug and Play to discover and manage devices that are over-the-air update capable. The Device Update service sends and receives properties and messages to and from devices using IoT Plug and Play interfaces. Device Update for IoT Hub requires IoT devices to implement the following interfaces and model ID.

For more information:

Understand the IoT Plug and Play device client.
See how the Device Update agent is implemented.

Device Update core interface

The DeviceUpdateCore interface is used to send update actions and metadata to devices and receive update status from devices. The DeviceUpdateCore interface is split into two object properties.

The expected component name in your model is "deviceUpdate" when this interface is implemented. Learn more about Azure IoT Plug and Play components.

Agent metadata

The Device Update agent uses agent metadata fields to send information to Device Update services.

Name	Schema	Direction	Description	Example
deviceProperties	Map	device to cloud	The set of properties that contain the manufacturer, model, and other device information.	See Device properties section for details.
compatPropertyNames	String (comma separated)	device to cloud	The device reported properties that are used to check for compatibility of the device to target the update deployment. Limited to five device properties.	"compatPropertyNames": "manufacturer,model"
lastInstallResult	Map	device to cloud	The result reported by the agent. It contains result code, extended result code, and result details for main update and other step updates.
resultCode	integer	device to cloud	A code that contains information about the result of the last update action. Can be populated for either success or failure.	700
extendedResultCode	integer	device to cloud	A code that contains additional information about the result. Can be populated for either success or failure.	0x80004005
resultDetails	string	device to cloud	Customer-defined free form string to provide additional result details. Returned to the twin without parsing
stepResults	map	device to cloud	The result reported by the agent containing result code, extended result code, and result details for step updates.	"step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	integer	device to cloud	An integer that indicates the current state of the Device Update agent.	See State section for details.
workflow	complex	device to cloud	A set of values that indicate which deployment the agent is currently working on, ID of current deployment, and acknowledgment of any retry request sent from service to agent.	"workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	device to cloud	An ID of the update that is currently installed (through Device Update). This value is a string capturing the Update ID JSON or null for a device that has never taken an update through Device Update.	installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}"

Device properties

The deviceProperties field contains the manufacturer and model information for a device.

Name	Schema	Direction	Description
manufacturer	string	device to cloud	The device manufacturer of the device, reported through `deviceProperties`. This property is read from one of two places - first, the DeviceUpdateCore interface attempts to read the 'aduc_manufacturer' value from the Configuration file. If the value isn't populated in the configuration file, it defaults to reporting the compile-time definition for ADUC_DEVICEPROPERTIES_MANUFACTURER. This property is reported only at boot time. Default value: 'Contoso'.
model	string	device to cloud	The device model of the device, reported through `deviceProperties`. This property is read from one of two places - first, the DeviceUpdateCore interface attempts to read the 'aduc_model' value from the Configuration file. If the value isn't populated in the configuration file, it defaults to reporting the compile-time definition for ADUC_DEVICEPROPERTIES_MODEL. This property is reported only at boot time. Default value: 'Video'
interfaceId	string	device to cloud	This property is used by the service to identify the interface version being used by the Device Update agent. The interface ID is required by Device Update service to manage and communicate with the agent. Default value: 'dtmi:azure:iot:deviceUpdate;1' for devices using DU agent version 0.8.0.
aduVer	string	device to cloud	Version of the Device Update agent running on the device. This value is read from the build only if ENABLE_ADU_TELEMETRY_REPORTING is set to 1 (true) during compile time. Customers can choose to opt out of version reporting by setting the value to 0 (false). How to customize Device Update agent properties.
doVer	string	device to cloud	Version of the Delivery Optimization agent running on the device. The value is read from the build only if ENABLE_ADU_TELEMETRY_REPORTING is set to 1 (true) during compile time. Customers can choose to opt out of the version reporting by setting the value to 0 (false). How to customize Delivery Optimization agent properties.
Custom compatibility Properties	User Defined	device to cloud	Implementer can define other device properties to be used for the compatibility check while targeting the update deployment.

IoT Hub device twin example:

"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\"}"
                },

Note

The device or module must add the {"__t": "c"} marker to indicate that the element refers to a component. For more information, see IoT Plug and Play conventions.

State

The State field is the status reported by the Device Update (DU) agent after receiving an action from the Device Update service. State is reported in response to an Action (see Action section for details) sent to the Device Update agent from the Device Update service. For more information about requests that flow between the Device Update service and the Device Update agent, see the overview workflow.

Name	Value	Description
Idle	0	The device is ready to receive an action from the Device Update service. After a successful update, state is returned to the `Idle` state.
DeploymentInprogress	6	A deployment is in progress.
Failed	255	A failure occurred during updating.
DownloadSucceeded	2	A successful download. This status is only reported by devices with agent version 0.7.0 or older.
InstallSucceeded	4	A successful install. This status is only reported by devices with agent version 0.7.0 or older.

Service metadata

Service metadata contains fields that the Device Update services uses to communicate actions and data to the Device Update agent.

Name	Schema	Direction	Description
action	integer	cloud to device	An integer that corresponds to an action the agent should perform. See Action section for details.
updateManifest	string	cloud to device	Used to describe the content of an update. Generated from the Import manifest.
updateManifestSignature	JSON Object	cloud to device	A JSON Web Signature (JWS) with JSON Web Keys used for source verification.
fileUrls	Map	cloud to device	Map of `FileID` to `DownloadUrl`. Tells the agent which files to download and the hash to use to verify that the files were downloaded correctly.

Action

The action field represents the actions taken by the Device Update agent as instructed by the Device Update service. The Device Update agent will report a state for processing the action received. For more information about requests that flow between the Device Update service and the Device Update agent, see the overview workflow.

Name	Value	Description
applyDeployment	3	Apply the update. It signals to the device to apply the deployed update
cancel	255	Stop processing the current action and go back to `Idle`, or tell an agent in the `Failed` state to go back to `Idle`.
download	0	Download published content or update and any other content needed. This action is only sent to devices with agent version 0.7.0 or older.
install	1	Install the content or update. Typically this action means to call the installer for the content or update. This action is only sent to devices with agent version 0.7.0 or older.
apply	2	Finalize the update. It signals the system to reboot if necessary. This action is only sent to devices with agent version 0.7.0 or older.

Device information interface

The device information interface is a concept used within IoT Plug and Play architecture. It contains device-to-cloud properties that provide information about the hardware and operating system of the device. Device Update for IoT Hub uses the DeviceInformation.manufacturer and DeviceInformation.model properties for telemetry and diagnostics. To learn more, see this example of the device information interface.

The expected component name in your model is deviceInformation when this interface is implemented. Learn about Azure IoT Plug and Play Components

Name	Type	Schema	Direction	Description	Example
manufacturer	Property	string	device to cloud	Company name of the device manufacturer. This property could be the same as the name of the original equipment manufacturer (OEM).	Contoso
model	Property	string	device to cloud	Device model name or ID.	IoT Edge Device
swVersion	Property	string	device to cloud	Version of the software on your device. swVersion could be the version of your firmware.	4.15.0-122
osName	Property	string	device to cloud	Name of the operating system on the device.	Ubuntu Server 18.04
processorArchitecture	Property	string	device to cloud	Architecture of the processor on the device.	ARM64
processorManufacturer	Property	string	device to cloud	Name of the manufacturer of the processor on the device.	Microsoft
totalStorage	Property	string	device to cloud	Total available storage on the device in kilobytes.	2048
totalMemory	Property	string	device to cloud	Total available memory on the device in kilobytes.	256

Model ID

Model ID is how smart devices advertise their capabilities to Azure IoT applications with IoT Plug and Play.To learn more on how to build smart devices to advertise their capabilities to Azure IoT applications visit IoT Plug and Play device developer guide.

Device Update for IoT Hub requires the IoT Plug and Play smart device to announce a model ID with a value of "dtmi:azure:iot:deviceUpdateModel;1" as part of the device connection. Learn how to announce a model ID.

Share via