Device Update for IoT Hub and IoT Plug and Play

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 will send and receive 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 as described below.

Concepts:

ADU Core Interface

The 'ADUCoreInterface' interface is used to send update actions and metadata to devices and receive update status from devices. The 'ADU Core' interface is split into two Object properties.

The expected component name in your model is "azureDeviceUpdateAgent" when implementing this interface. Learn more about Azure IoT Plug and Play Components

Agent Metadata

Agent Metadata contains fields that the device or Device Update agent uses to send information and status to Device Update services.

Name Schema Direction Description Example
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 and should follow http status code specification. 500
extendedResultCode integer device to cloud A code that contains additional information about the result. Can be populated for either success or failure. 0x80004005
state integer device to cloud It is an integer that indicates the current state of the Device Update Agent. See below for details Idle
installedUpdateId string device to cloud An ID of the update that is currently installed (through Device Update). This value will be a string capturing the Update Id JSON or null for a device that has never taken an update through Device Update. "{"provider":"contoso","name":"image-update","version":"1.0.0"}"
deviceProperties Map device to cloud The set of properties that contain the manufacturer and model. See below for details

State

It is the status reported by the Device Update Agent after receiving an action from the Device Update Service. State is reported in response to an Action (see Actions below) sent to the Device Update Agent from the Device Update Service. See the overview workflow for requests that flow between the Device Update Service and the Device Update Agent.

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.
DownloadSucceeded 2 A successful download.
InstallSucceeded 4 A successful install.
Failed 255 A failure occurred during updating.

Device Properties

It is the set of properties that contain the manufacturer and model.

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-the 'AzureDeviceUpdateCore' interface will first attempt to read the 'aduc_manufacturer' value from the Configuration file file. If the value is not populated in the configuration file, it will default to reporting the compile-time definition for ADUC_DEVICEPROPERTIES_MANUFACTURER. This property will only be reported 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-the AzureDeviceUpdateCore interface will first attempt to read the 'aduc_model' value from the Configuration file file. If the value is not populated in the configuration file, it will default to reporting the compile-time definition for ADUC_DEVICEPROPERTIES_MODEL. This property will only be reported at boot time. Default value 'Video'
aduVer string device to cloud Version of the Device Update agent running on the device. This value is read from the build only if during compile time ENABLE_ADU_TELEMETRY_REPORTING is set to 1 (true). 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 during compile time ENABLE_ADU_TELEMETRY_REPORTING is set to 1 (true). Customers can choose to opt-out of the version reporting by setting the value to 0 (false).How to customize Delivery Optimization agent properties.

IoT Hub Device Twin sample

 "azureDeviceUpdateAgent": {
                           "__t": "c",
                           "client": {
                                     "state": 0,
                                     "resultCode": 200,
                                     "extendedResultCode": 0,
                                     "deviceProperties": {
                                                         "manufacturer": "Contoso",
                                                         "model": "Video",
                                                         "aduVer": "DU;agent/0.6.0",
                                                         "doVer": "DU;lib/v0.4.0,DU;agent/v0.4.0,DU;plugin-apt/v0.2.0"
                                                         },
                                     "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"SampleUpdate1\",\"version\":\"1.0.4\"}"
                                     },
                            }

Note: The device or module must add the {"__t": "c"} marker to indicate that the element refers to a component, learn more here.

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 It is an integer that corresponds to an action the agent should perform. Values listed below.
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 FileHash to DownloadUri. Tells the agent, which files to download and the hash to use to verify the files were downloaded correctly.

Action

Actions below represents the actions taken by the Device Update Agent as instructed by the Device Update Service. The Device Update Agent will report a State (see State section above) processing the Action received. See the overview workflow for requests that flow between the Device Update Service and the Device Update Agent.

Name Value Description
Download 0 Download published content or update and any other content needed
Install 1 Install the content or update. Typically this means calling the installer for the content or update.
Apply 2 Finalize the update. It signals the system to reboot if necessary.
Cancel 255 Stop processing the current action and go back to Idle. Will also be used to tell the agent in the Failed state to go back to Idle.

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 about Device Information interface, see this example.

The expected component name in your model is deviceInformation when implementing this interface. 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 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:AzureDeviceUpdate;1" as part of the device connection. Learn how to announce a model ID.