Deploy an update by using Azure Device Update for IoT Hub

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

2. Select Updates under Device management in the left navigation.

   

3. On the Updates page, select the Groups and Deployments tab and view the update compliance chart and device group list. You might need to refresh the view to see recently imported updates available for your device group.

4. Under Status in the group list, select Deploy next to One or more new updates are available for this group.

   

5. 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.

6. Select Deploy next to the one or more updates available status.

7. From the list on the right, select the desired update to deploy.

   

8. For Download security, select HTTPS (recommended) or HTTP. This setting controls the protocol that devices use to download the update content. HTTPS is the default and encrypts update content in transit.

   For guidance on choosing a protocol and preparing your devices, see Understand download security (TLS) in Device Update for IoT Hub.

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

   Tip

   By default, the Start date and time is 24 hours from your current time. Be sure to select a different date and time if you want the deployment to begin sooner or later.

   

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

11. In the Current updates tab, you can view the status of your deployment.

    

12. In the Group basics view, the compliance chart shows that the update is now in progress.

    After your device successfully updates, your compliance chart and deployment details update to reflect that status.

You can use the Bash environment in Azure Cloud Shell to run the following commands. Select Launch Cloud Shell to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.

Or, if you prefer, you can run the Azure CLI commands locally:

1. Install Azure CLI. Run az version to see the installed Azure CLI version and dependent libraries, and run az upgrade to install the latest version.
2. Sign in to Azure by running az login.
3. Install the azure-iot extension when prompted on first use. To make sure you're using the latest version of the extension, run az extension update --name azure-iot.

Verify update availability

1. Use the az iot du device group list command to identify your device group.

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

2. Then use az iot du device group show to show 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, which is either the value of the ADUGroup tag, or $default for devices with no tag.
   • --resource-group: The Device Update account resource group name.
   • --best-updates: Returns the best available updates for the device group, including a count of how many devices need each update.
   • --update-compliance: Returns device group update compliance information, such as how many devices are on their latest update, how many need new updates, and how many are currently receiving a new update.

   To verify the best available update for your group, run the command as follows:

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

Create the deployment

Use az iot du device deployment create to create a deployment for the device 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, which is either 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: The parameters that define the updateId object, a unique identifier for the update in this deployment.

Run the command as follows:

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>

Devices download update content over HTTPS by default. To use HTTP instead, add the optional --download-security parameter described in Use optional arguments.

Use optional arguments

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

To create an automatic rollback policy, add the following parameters:

• --failed-count: The number of failed devices in a deployment that triggers a rollback.
• --failed-percentage: The percentage of failed devices in a deployment that triggers a rollback.
• --rollback-update-name, --rollback-update-provider, --rollback-update-version: The parameters for the update to use if a rollback is initiated.

Run the command as follows:

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>

To set the deployment start time, use the --start-time parameter to provide the target date and time for the deployment, as follows:

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"

To choose the protocol that devices use to download the update content, add the optional --download-security parameter. Accepted values are HTTPS (recommended) and HTTP. If you omit the parameter, the deployment uses the default HTTPS. For guidance on choosing a protocol and preparing your devices, see Understand download security (TLS) in Device Update for IoT Hub.

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> \
    --download-security <HTTPS or HTTP>

1. On the Groups and Deployments tab of the Updates page, select the group you deployed to.

2. On the Group details page, go to the Current deployment or Deployment history tab to confirm that a deployment is in progress.

   

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

4. Select Refresh to view the latest status details.

   

Go to the Group basics tab of the Group details page to search for the status of a particular device, or filter to view devices that failed the deployment.

Use az iot du device deployment list to view all deployments 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

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

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

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>