Rediger

Del via

Manage device groups for Azure Device Update for IoT Hub

  • Artikkel

Azure Device Update for IoT Hub allows deploying updates to user-defined groups of IoT devices. Every Device Update managed device is a member of a device group, but defining device groups is optional. You can alternatively deploy to the default device group that Device Update provides.

If you create and assign user-defined Device Update tag values to devices, Device Update automatically creates groups based on the assigned tags and device compatibility properties. For each device group, Device Update can create multiple subgroups that have different device classes. Device Update places devices that have no tags in the default device group.

This article describes how to use the Azure portal or Azure CLI to create and manage user-defined Device Update device tags and groups. To deploy updates to user-defined or default device groups, see Deploy a device update.

Prerequisites

Add tags to your devices

To assign a Device Update device group, you add the ADUGroup tag to a target set of Device Update connected devices in IoT Hub. Add the tag to the device twin if your Device Update agent is provisioned with device identity, or to the corresponding module twin if the Device Update agent is provisioned with a module identity.

The Device Update ADUGroup tag uses a key-value format, as shown in the following device or module twin example:

"etag": "",
"deviceId": "",
"deviceEtag": "",
"version": <version>,
"tags": {
   "ADUGroup": "<CustomTagValue>"
}

For more information and examples of twin JSON syntax, see Understand and use device twins or Understand and use module twins.

The ADUGroup tag has the following properties and limitations:

  • A device can only have one ADUGroup tag and belong to only one Device Update group at a time. Adding another tag named ADUGroup overrides the existing ADUGroup value.
  • You can use any value for the tag except the reserved values Uncategorized and $default.
  • The tag value can't exceed 200 characters.
  • The tag value can contain alphanumeric characters and the following special characters: . - _ ~.
  • The ADUGroup tag name and group name values are case-sensitive.

The following sections describe several ways to add and update the tag.

Add tags with SDKs

You can update the device or module twin with the appropriate tag using RegistryManager after you enroll the device with Device Update. For more information, see the following articles:

Add tags using jobs

You can schedule jobs to add or update Device Update tags on multiple devices. For examples of job operations, see Schedule jobs on multiple devices. You can update either device twins or module twins using jobs, depending on whether the Device Update agent is provisioned with a device or module identity. For more information, see Schedule and broadcast jobs.

Note

This operation counts against your IoT Hub messages quota. If you change 50,000 or more device or module twin tags at a time, you might exceed your daily IoT Hub message quota and need to buy more IoT Hub units. For more information, see Quotas and throttling.

Add tags by updating twins

You can also add or update the ADUGroup tag directly in the device or module twin.

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

  2. Select Devices under Device management in the left navigation pane. If you have an IoT Edge device, select IoT Edge instead.

  3. On the Devices page, select your device.

  4. On the device page, either select Device twin from the top menu, or select the module identity under Module identities and then select the module twin.

  5. In the twin, add the ADUGroup tag with a user-defined value, as follows. To update an existing ADUGroup tag value, overwrite it with a different user-defined value.

        "tags": {
            "ADUGroup": "<CustomTagValue>"
            }

  6. Select Save.

View device groups

  1. In the Azure portal, navigate to the IoT hub connected to your Device Update instance.

  2. Select the Updates option under Device Management in the left navigation.

  3. Select the Groups and Deployments tab.

    Screenshot of ungrouped devices.

Once you create a group, the compliance chart and group list update. The Device Update compliance chart shows the count of devices in various states of compliance: On latest update, New updates available, and Updates in progress. For more information, see Device Update compliance.

Existing Device Update groups and any available updates for the devices in those groups appear in the group list. Any devices that don't meet the device class requirements of the group appear in a corresponding invalid group. You can deploy the best available update to a group from this view by selecting Deploy next to the group.

Screenshot of update compliance view.

View device details for a group

  1. From the Groups and Deployments tab, select the name of the group.

    The Group details page shows the update compliance chart with the count of group member devices in various states of compliance, and the list of group member devices with their device update properties.

    Screenshot of device group details view.

  2. Select an individual device within a group to go to its device details page in IoT Hub.

    Screenshot of device details view.

    Screenshot of device details view in IoT hub.

Remove a device from a device group

To remove a device from a device group, change the ADUGroup tag value to null in the twin, and select Save.

    "tags": {
            "ADUGroup": "null"
            }

This action deletes the group tag from the device twin and removes the device from the device group.

Delete a device group

Device Update automatically creates device groups, and it retains device groups, device classes, and deployments for historical records or other user needs, rather than automatically cleaning them up. You can delete device groups through the Azure portal by individually selecting and deleting the groups, or by calling the az iot du device group delete Azure CLI command on the group.

To be deleted, a group must meet the following requirements:

  • Must not be a default group.
  • Must have no member devices. That is, no device provisioned in the Device Update instance can have an ADUGroup tag with a value matching the group's name.
  • Must have no associated active or canceled deployments.

Note

If you're unable to delete a group that meets the preceding requirements, check whether you have any unhealthy devices tagged as part of the group. Unhealthy devices can't receive a deployment, so they don't appear directly in the list of member devices in a group.

To check whether you have any unhealthy devices:

  1. In the Azure portal, navigate to your IoT hub.
  2. Select Updates from the left navigation and then select the Diagnostics tab.
  3. Expand the Find missing devices section.

If you have unhealthy devices tagged as part of the group, you must change the tag value or delete the device before you can delete the group.

If a device is ever assigned to a deleted group name again, Device Update automatically recreates the group, but there's no associated device or deployment history.

Related content