edits

Author: v-thepet

articles/iot-hub-device-update/create-update-group.md

@@ -1,19 +1,21 @@
 ---
-title: Manage device groups in Azure Device Update for IoT Hub | Microsoft Docs
-description: Learn how to configure device groups in Azure Device Update for IoT Hub by using device twin tags in Azure CLI or the Azure portal.
+title: Manage device groups for Azure Device Update for IoT Hub | Microsoft Docs
+description: Learn how to configure Azure Device Update for IoT Hub device groups by using the ADUGroup tag in the Azure portal or with Azure CLI.
 author: vimeht
 ms.author: vimeht
-ms.date: 01/08/2025
+ms.date: 01/09/2025
 ms.topic: how-to
 ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
-# Manage device groups in Azure Device Update for IoT Hub
+# Manage device groups for Azure Device Update for IoT Hub
 
-You can deploy updates to your IoT devices by using the default group that Azure Device Update for IoT Hub creates, or by optionally defining groups of devices to deploy to. You can assign a user-defined tag to devices. Device Update automatically creates groups based on the assigned tags and the device compatibility properties. A group can have multiple subgroups with different device classes.
+Azure Device Update for IoT Hub deploys updates to devices based on their assignment to a device group. You can deploy updates to your IoT devices by using the default group that Device Update creates, or optionally by defining groups of devices to deploy to.
 
-This article describes how to create and use tags to manage user-defined groups in the Azure portal or with Azure CLI. To deploy to the default group instead of creating tags and user-defined groups, see [Deploy a device update](deploy-update.md).
+You can create and assign user-defined tag values to devices, and Device Update automatically creates groups based on the assigned tags and device compatibility properties. A device group can have multiple subgroups that have different device classes.
+
+This article describes how to use the Azure portal or Azure CLI to manage user-defined Device Update groups and tags. To deploy updates to user-defined groups, or to deploy to the default group without specifying user-defined groups and tags, see [Deploy a device update](deploy-update.md).
 
 ## Prerequisites
 
@@ -23,22 +25,21 @@ This article describes how to create and use tags to manage user-defined groups
 
 ## Tag properties and limitations
 
-Tags have the following properties and limitations:
+The `ADUGroup` tag that determines Device Update group assignment has the following properties and limitations:
 
-- You can add any value to your tag except the reserved values `Uncategorized` and `$default`.
-- A device can only have one tag with the name `ADUGroup`. Adding a tag with that name overrides any existing value for tag name `ADUGroup`.
+- You can add any value to the tag except the reserved values `Uncategorized` and `$default`.
+- 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.
 - The tag value can't exceed 200 characters.
 - The tag value can contain alphanumeric characters and the following special characters: `. - _ ~`.
-- Tag and group names are case-sensitive.
-- A device can belong to only one group.
+- The `ADUGroup` tag name and group name values are case-sensitive.
 
 ## Add tags to your devices
 
-To create a device group, you add a tag to the target set of devices in IoT Hub. The devices must be connected to Device Update.
+To create a Device Update device group, you add an `ADUGroup` tag to the target set of devices in IoT Hub. The devices must be connected to Device Update.
 
-Add tags 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. For more information and examples of twin JSON syntax, see [Understand and use device twins](../iot-hub/iot-hub-devguide-device-twins.md) or [Understand and use module twins](../iot-hub/iot-hub-devguide-module-twins.md).
+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. For more information and examples of twin JSON syntax, see [Understand and use device twins](../iot-hub/iot-hub-devguide-device-twins.md) or [Understand and use module twins](../iot-hub/iot-hub-devguide-module-twins.md).
 
-Device Update tags use a key-value format as shown in the following device or module twin:
+The Device Update `ADUGroup` tag uses a key-value format, as shown in the following device or module twin example:
 
 ```json
 "etag": "",
@@ -50,34 +51,33 @@ Device Update tags use a key-value format as shown in the following device or mo
 }
 ```
 
-The following sections describe several ways to add and update tags.
+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:
 
-- [Learn how to add tags using a sample .NET app.](../iot-hub/iot-hub-csharp-csharp-twin-getstarted.md).
-- [Learn about tag properties and formats](../iot-hub/iot-hub-devguide-device-twins.md#tags-and-properties-format).
+- [Get started with device twins using .NET](../iot-hub/iot-hub-csharp-csharp-twin-getstarted.md)
+- [Understand tags and properties format](../iot-hub/iot-hub-devguide-device-twins.md#tags-and-properties-format)
 
 ### Add tags using jobs
 
-You can schedule a job on multiple devices to add or update Device Update tags. For examples of job operations, see [Schedule jobs on multiple devices](../iot-hub/iot-hub-devguide-jobs.md). 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](../iot-hub/iot-hub-csharp-csharp-schedule-jobs.md).
+You can schedule a job to add or update Device Update tags on multiple devices. For examples of job operations, see [Schedule jobs on multiple devices](../iot-hub/iot-hub-devguide-jobs.md). 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](../iot-hub/iot-hub-csharp-csharp-schedule-jobs.md).
 
 > [!NOTE]
-> This action 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](../iot-hub/iot-hub-devguide-quotas-throttling.md).
+> This job 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](../iot-hub/iot-hub-devguide-quotas-throttling.md).
 
 ### Add tags by updating twins
 
-You can also add or update tags directly in device or module twins.
+You can also add or update the `ADUGroup` tag directly in the device or module twin.
 
 # [Azure portal](#tab/portal)
 
 1. In the [Azure portal](https://portal.azure.com), navigate to your IoT hub.
 1. Select **Devices** under **Device management** in the left navigation pane. If you have an IoT Edge device, select **IoT Edge** instead.
 1. On the **Devices** page, select your device.
 1. 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.
-1. In the twin, delete any existing Device Update tag value by setting it to `null`, and then select **Save**.
-1. Add a new Device Update tag value as follows:
+1. 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.
 
    ```JSON
        "tags": {
@@ -88,7 +88,7 @@ You can also add or update tags directly in device or module twins.
 
 # [Azure CLI](#tab/cli)
 
-You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) to run the Azure CLI commands. Select **Launch Cloud Shell** to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.
+You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) to run the following Azure CLI commands. Select **Launch Cloud Shell** to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.
 
 :::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::
 
@@ -99,7 +99,7 @@ You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quick
 >1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
 >1. 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`.
 
-Use [az iot hub device-twin update](/cli/azure/iot/hub/device-twin#az-iot-hub-device-twin-update) or [az iot hub module-twin update](/cli/azure/iot/hub/module-twin#az-iot-hub-module-twin-update) to add the tag to the device or module twin.
+Use [az iot hub device-twin update](/cli/azure/iot/hub/device-twin#az-iot-hub-device-twin-update) or [az iot hub module-twin update](/cli/azure/iot/hub/module-twin#az-iot-hub-module-twin-update) to add the `ADUGroup` tag to the device or module twin with an appropriate value.
 
 For both `update` commands, the `--tags` argument accepts either inline JSON or a path to a JSON file.
 
@@ -125,11 +125,11 @@ az iot hub module-twin update \
 
    :::image type="content" source="media/create-update-group/ungrouped-devices.png" alt-text="Screenshot of ungrouped devices." lightbox="media/create-update-group/ungrouped-devices.png":::
 
-1. 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.](device-update-compliance.md).
+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.](device-update-compliance.md).
 
-   :::image type="content" source="media/create-update-group/updated-view.png" alt-text="Screenshot of update compliance view." lightbox="media/create-update-group/updated-view.png":::
+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 the **Deploy** button next to the group.
 
-You should see existing groups and any available updates for the devices in those groups in the group list. If there are devices that don't meet the device class requirements of the group, they appear in a corresponding invalid group. You can deploy the best available update to a group from this view by selecting the **Deploy** button next to the group.
+:::image type="content" source="media/create-update-group/updated-view.png" alt-text="Screenshot of update compliance view." lightbox="media/create-update-group/updated-view.png":::
 
 # [Azure CLI](#tab/cli)
 
@@ -151,14 +151,14 @@ You can use the `--order-by` argument to order the returned list by aspects like
 
 1. From the **Groups and Deployments** tab, select the name of the group.
 
-1. The **Group details** shows the list of devices that are part of the group along with their device update properties. You can also see the update compliance information for all devices that are members of the group. The compliance chart shows the count of devices in various states of compliance.
+   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.
 
    :::image type="content" source="media/create-update-group/group-details.png" alt-text="Screenshot of device group details view." lightbox="media/create-update-group/group-details.png":::
 
-1. Select an individual device within a group to go to the device details page in IoT Hub.
+1. Select an individual device within a group to go to its device details page in IoT Hub.
 
    :::image type="content" source="media/create-update-group/device-details.png" alt-text="Screenshot of device details view." lightbox="media/create-update-group/device-details.png":::
-   
+
    :::image type="content" source="media/create-update-group/device-details-2.png" alt-text="Screenshot of device details view in IoT hub." lightbox="media/create-update-group/device-details-2.png":::
 
 # [Azure CLI](#tab/cli)
@@ -180,23 +180,23 @@ az iot du device group show \
 
 ## Remove a device from a device group
 
-To remove a device from a device group, change the group tag value to `null` in the twin, and select **Save**.
+To remove a device from a device group, change the `ADUGroup` tag value to `null` in the twin, and select **Save**.
 
 ```JSON
     "tags": {
             "ADUGroup": "null"
             }
 ```
-This action deletes the group tag from the device twin and removes the device from its device group.
+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, but it retains groups, device classes, and deployments for historical records or other user needs, and doesn't automatically clean them up. You can delete device groups through the Azure portal by individually selecting and deleting the desired groups, or by calling the [`az iot du device group delete`](/cli/azure/iot/du/device/group#az-iot-du-device-group-delete) API on the group.
+Device Update automatically creates device groups, but it retains device groups, device classes, and deployments for historical records or other user needs, and doesn't automatically clean 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`](/cli/azure/iot/du/device/group#az-iot-du-device-group-delete) API 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 should have a `ADUGroup` tag with a value matching the group's name.
+- Must have no member devices. That is, no device provisioned in the Device Update instance can have a `ADUGroup` tag with a value matching the group's name.
 - Must have no associated active or canceled deployments.
 
 > [!NOTE]
@@ -206,10 +206,9 @@ To be deleted, a group must meet the following requirements:
 > 1. In the Azure portal, navigate to your IoT hub.
 > 1. Select **Updates** from the left navigation and then select the **Diagnostics** tab.
 > 1. Expand the **Find missing devices** section.
-> 
-> If you have unhealthy devices tagged as part of the group, you need to modify the tag value or delete the device before you can delete your group.
+> If you have unhealthy devices tagged as part of the group, you need to modify the tag value or delete the device before you can delete the group.
 
-If a device is ever assigned to this deleted group name again, the group is automatically recreated, but there's no associated device or deployment history.
+If a device is ever assigned to a deleted group name again, the group is automatically recreated, but there's no associated device or deployment history.
 
 ## Related content