Deploy an update by using Device Update for Azure IoT Hub

Learn how to deploy an update to an IoT device by using Device Update for Azure IoT Hub.

Prerequisites

• Access to an IoT Hub with Device Update for IoT Hub enabled. We recommend that you use an S1 (Standard) tier or above for your IoT Hub.
• An imported update for the provisioned device.
• An IoT device (or simulator) provisioned for Device Update within IoT Hub.
• The device is part of at least one default group or user-created update group.

Azure portal

Supported browsers:

• Microsoft Edge
• Google Chrome

Azure CLI

An Azure CLI environment:

• Use the Bash environment in Azure Cloud Shell.

  

• Or, if you prefer to run CLI reference commands locally, install the Azure CLI

  1. Sign in to the Azure CLI by using the az login command.
  2. Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
  3. When prompted, install Azure CLI extensions on first use. The commands in this article use the azure-iot extension. Run az extension update --name azure-iot to make sure you're using the latest version of the extension.

Tip

The Azure CLI commands in this article use the backslash \ character for line continuation so that the command arguments are easier to read. This syntax works in Bash environments. If you're running these commands in PowerShell, replace each backslash with a backtick ```, or remove them entirely.

Deploy the update

Azure portal

1. In the Azure portal, navigate to your IoT hub.

2. Select Updates from the navigation menu to open the Device Update page of your IoT Hub instance.

   

3. Select the Groups and Deployments tab at the top of the page. For more information, see Device groups.

   

4. View the update compliance chart and group list. You should see a new update available for your tag based or default group. You might need to refresh once. For more information, see Device Update compliance.

5. Select Deploy next to the one or more updates available, and confirm that the descriptive label you added when importing is present and looks correct.

6. Confirm that the correct group is selected as the target group and select Deploy.

7. To start the deployment, go to the Current deployment tab. Select the Deploy link next to the desired update from the Available updates section. The best available update for a given group is denoted with a Best highlight.

   

8. Schedule your deployment to start immediately or in the future.

   Tip

   By default, the Start date and time is set to Immediately. Be sure to select a different date and time if you want the deployment to begin later.

   

9. Create an automatic rollback policy if needed. Then select Create.

10. In the deployment details, Status turns to Active. The deployed update is marked with (deploying).

    

11. View the compliance chart to see that the update is now in progress.

    

12. After your device is successfully updated, you see that your compliance chart and deployment details updated to reflect the same.

    

Azure CLI

The az iot du device group list to verify the best available update for your group. The command takes the following arguments:

• --account: The Device Update account name.
• --instance: The Device Update instance name.
• --group-id: The device group ID that you're targeting with this deployment. This ID is the value of the ADUGroup tag, or $default for devices with no tag.
• --best-updates: This flag indicates the command should fetch the best available updates for the device group including a count of how many devices need each update.
• `--resource-group -g': Device Update account resource group name.
• '--update-compliance': This flag indicates the command should fetch device group update compliance information such as how many devices are on their latest update, how many need new updates, and how many are in progress on receiving a new update.

az iot du device group list \
    --account <Device Update account name> \
    --instance <Device Update instance name>\
    --gid <device group id>\
    --best-updates {false, true}

Use az iot du device deployment create to create a deployment for a device group.

The device deployment create command takes the following arguments:

• --account: The Device Update account name.
• --instance: The Device Update instance name.
• --group-id: The device group ID that you're targeting with this deployment. This ID is the value of the ADUGroup tag, or $default for devices with no tag.
• --deployment-id: An ID to identify this deployment.
• --update-name, --update-provider, and --update-version: These three parameters define the updateId object that is a unique identifier for the update that you're using in this deployment.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version>

Optional arguments allow you to configure the deployment. For the full list, see Optional parameters

If you want to create an automatic rollback policy, add the following parameters:

• --failed-count: The number of failed devices in a deployment that will trigger a rollback.
• --failed-percentage: The percentage of failed devices in a deployment that will trigger a rollback.
• --rollback-update-name, --rollback-update-provider, --rollback-update-version: The updateID for the update that the device group will use if a rollback is initiated.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version> \
    --failed-count 10 \
    --failed-percentage 5 \
    --rollback-update-name <rollback update name> \
    --rollback-update-provider <rollback update provider> \
    --rollback-update-version <rollback update version>

If you want the deployment to start in the future, use the --start-time parameter to provide the target datetime for the deployment.

az iot du device deployment create \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id> \
    --deployment-id <deployment id> \
    --update-name <update name> \
    --update-provider <update provider> \
    --update-version <update version> \
    --start-time "2022-12-20T01:00:00"

Monitor an update deployment

Azure portal

1. Select the group you deployed to, and go to the Current updates or Deployment history tab to confirm that the deployment is in progress

   

2. Select Details next to the deployment you created. Here you can view the deployment details, update details, and target device class details. You can optionally add a friendly name for the device class.

   

3. Select Refresh to view the latest status details.

4. You can go to the group basics view to search the status for a particular device, or filter to view devices that have failed the deployment

Azure CLI

Use az iot du device deployment list to view all deployment for a device group.

az iot du device deployment list \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group id>

Use az iot du device deployment show to view the details of a particular deployment.

az iot du device deployment show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group ID> \
    --deployment-id <deployment ID>

Add the --status flag to return information about how many devices in the deployment are in progress, completed, or failed.

az iot du device deployment show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <device group ID> \
    --deployment-id <deployment ID> \
    --status

Retry an update deployment

If your deployment fails for some reason, you can retry the deployment for failed devices.

Azure portal

1. Go to the Current deployment tab on the Group details screen.

   

2. Select Retry failed devices and acknowledge the confirmation notification.

Azure CLI

Use az iot du device deployment retry to retry a deployment for a target subgroup of devices.

This command takes the --class-id argument, which is generated from the model ID and compatibility properties reported by the device update agent.

az iot du device deployment retry \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --deployment-id <deployment ID> \
    --group-id <device group ID> \
    --class-id <device class ID>

Next steps

Troubleshoot common issues