edits

Author: v-thepet

articles/iot-hub-device-update/device-update-apt-manifest.md

@@ -16,9 +16,9 @@ This article describes the apt manifest, a JSON file that describes update detai
 
 When you deliver an apt manifest to a Device Update agent as an update, the agent processes the manifest and carries out the necessary operations. These operations include downloading and installing the packages specified in the apt manifest file and their dependencies from a designated repository.
 
-Device Update supports the apt `updateType` and apt [update handler](device-update-agent-overview.md#update-handlers). This support allows the Device Update agent to evaluate the installed Debian packages and update the necessary packages.
+Device Update supports the apt update type and [update handler](device-update-agent-overview.md#update-handlers). This support allows the Device Update agent to evaluate the installed Debian packages and update the necessary packages.
 
-You can use an apt manifest to update the Device Update agent and its dependencies. List the device update agent name and desired version in the apt manifest as you would any other package. You can then import this apt manifest and deploy it through the Device Update pipeline.
+You can use an apt manifest to update the Device Update agent itself and its dependencies. List the device update agent name and desired version in the apt manifest as you would any other package. You can then import this apt manifest and deploy it through the Device Update pipeline.
 
 ## Schema
 
@@ -58,29 +58,30 @@ For example:
 
 Each apt manifest includes the following properties:
 
-- **Name**: A name for this apt manifest, which can be whatever name or ID is meaningful for your scenarios. For example, `contoso-iot-edge`.
-- **Version**: A version number for this apt manifest, for example, `1.0.0.0`.
+- **Name**: A name for this apt manifest, which can be any meaningful name or ID for your scenario. For example, `contoso-iot-edge`.
+- **Version**: A version number for this apt manifest, for example `1.0.0.0`.
 - **Packages**: A list of objects containing package-specific properties.
   - **Name**: The package name or ID, for example `iotedge`.
-  - **Version**: The desired package version criteria, for example, `1.0.8-2`. The version value shouldn't contain an equal sign. If version is omitted, Device Update installs the latest available version of the specified package.
+  - **Version**: The desired package version criteria, for example, `1.0.8-2`.
 
 ### Versioning
 
-The apt manifest supports only exact version numbers. The version number is the desired Debian package version in format `[epoch:]upstream_version[-debian_revision]`, where `epoch` is an unsigned `int` and `upstream_version` can include alphanumerics and characters such as `.`, `,`, `+`, `-`, and `~`. The number should start with a digit.
+The apt manifest supports only exact version numbers. The version number is the desired Debian package version in format `<epoch>:<upstream_version>-<debian_revision>`, where `epoch` is an unsigned int and `upstream_version` starts with a digit and can include alphanumerics and characters such as `.`, `,`, `+`, `-`, and `~`. The version value shouldn't contain an equal sign.
 
-For example, `"name":"iotedge"` and `"version":"1.0.8-2"` is equivalent to installing a package using command `apt-get install iotedge=1.0.8-2`. For more information about how Debian packages are versioned, see the [Debian policy manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version).
+For example, `"name":"iotedge"` and `"version":"1.0.8-2"` is equivalent to installing a package using command `apt-get install iotedge=1.0.8-2`. Version `1.0.8` is equal to `1.0.8-0`.
 
-> [!NOTE]
-> `1.0.8` is equal to `1.0.8-0`.
+If version is omitted, Device Update installs the latest available version of the specified package. For more information about how Debian packages are versioned, see the [Debian policy manual](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-version).
 
 > [!NOTE]
-> The apt package manager ignores versioning requirements given by a package when the dependent packages to install are being automatically resolved. Unless explicit versions of dependent packages are given, the package manager uses the latest, even though the package itself may specify a strict requirement (`=`) on a given version. This automatic resolution can lead to errors regarding unmet dependencies. For more information, see [apt-get not properly resolving a dependency on a fixed version in a Debian/Ubuntu package](https://unix.stackexchange.com/questions/350192/apt-get-not-properly-resolving-a-dependency-on-a-fixed-version-in-a-debian-ubunt).
+> Unless explicit versions of dependent packages are given, the apt package manager installs the latest versions, even if the package itself specifies a strict requirement (`=`) on a given version. The package manager ignores the package versioning requirements when automatically resolving the dependent packages to install. This automatic resolution can lead to errors regarding unmet dependencies.
+> 
+> Ideally, when you install a specific version of a package, also include the explicit versions of the dependent packages to install. For more information, see [apt-get not properly resolving a dependency on a fixed version in a Debian/Ubuntu package](https://unix.stackexchange.com/questions/350192/apt-get-not-properly-resolving-a-dependency-on-a-fixed-version-in-a-debian-ubunt).
 
 If you update a specific version of the Azure IoT Edge security daemon, you should include the desired version of the `aziot-edge` package and its dependent `aziot-identity-service` package in your apt manifest. For more information, see [How to update IoT Edge](../iot-edge/how-to-update-iot-edge.md#update-the-security-subsystem).
 
-## Installed criterion
+## Installed criteria
 
-The installed criterion for an apt manifest is `<name>-<version>`, where `<name>` is the name of the apt manifest and `<version>` is its version. For example, `contoso-iot-edge-1.0.0.0`.
+The installed criteria for an apt manifest is `<name>-<version>`, where `<name>` is the name of the apt manifest and `<version>` is its version. For example, `contoso-iot-edge-1.0.0.0`.
 
 ## Package removal
 
@@ -112,8 +113,8 @@ Keep the following guidelines in mind when you create an apt manifest:
 - For the desired state of each individual package, specify the exact name and version of the package you want to install on your device. Always validate the values against the contents of the source package repository.
 - List the packages in the apt manifest in the order they should be installed or removed.
 - Always validate the installation of packages on a test device to ensure the desired outcome.
-- When you install a specific version of a package, for example `iotedge 1.0.9-1`, also include the explicit versions of the dependent packages to install, for example, `libiothsm 1.0.9-1`.
-- While not required, it's best to always make your apt manifest cumulative, to avoid getting your device into an unknown state. A cumulative update ensures that your devices have the desired version of every relevant package, even if the device skipped an update because of installation failure or being offline.
+- When you install a specific version of a package, for example `iotedge 1.0.9-1`, also include the explicit versions of the dependent packages to install, for example `libiothsm 1.0.9-1`.
+- While not required, always making your apt manifest cumulative avoids getting devices into an unknown state. A cumulative update ensures that your devices have the desired version of every relevant package, even if the device skipped an update because of installation failure or being offline.
 
   For example, consider the following base apt manifest:
 
@@ -145,7 +146,7 @@ Keep the following guidelines in mind when you create an apt manifest:
   }
   ```
 
-  The following version 2.0 update is better because it includes both the `contoso1` and `contoso2` packages:
+  The following version 2.0 cumulative update includes both the `contoso1` and `contoso2` packages:
 
   ```JSON
   {

articles/iot-hub-device-update/device-update-control-access.md

@@ -11,7 +11,9 @@ ms.subservice: device-update
 
 # Azure RBAC and Azure Device Update for IoT Hub
 
-For users and applications to access Azure Device Update for IoT Hub, they must be granted access to the Device Update resource. The Device Update service principal must also get access to the IoT hub to deploy updates and manage devices. This article explains how Device Update uses Azure role-based access control (Azure RBAC) to provide authentication and authorization for users and service APIs.
+For users and applications to access Azure Device Update for IoT Hub, they must be granted access to the Device Update resource. The Device Update service principal must also get access to its associated IoT hub to deploy updates and manage devices.
+
+This article explains how Device Update and Azure IoT Hub use Azure role-based access control (Azure RBAC) to provide authentication and authorization for users and service APIs. The article also describes Microsoft Entra ID authentication for Device Update REST APIs, and support for managed identities in Device Update and Azure IoT Hub.
 
 ## Device Update access control roles
 
@@ -26,13 +28,13 @@ Device Update supports the following RBAC roles:
 |  Device Update Deployments Administrator | Can manage deployments of updates to devices|
 |  Device Update Deployments Reader| Can view deployments of updates to devices |
 
-You can assign a combination of roles to provide the right level of access. For example, the Device Update Content Administrator role can import and manage updates, but you need the Device Update Deployments Reader role to view the progress of an update. Conversely, the Device Update Reader role can view all updates, but you need the Device Update Deployments Administrator role to deploy an update to devices.
+You can assign a combination of roles to provide the right level of access. For example, you can use the Device Update Content Administrator role to import and manage updates, but you need the Device Update Deployments Reader role to view the progress of an update. Conversely, with the Device Update Reader role you can view all updates, but you need the Device Update Deployments Administrator role to deploy an update to devices.
 
 ## Device Update service principal access to IoT Hub
 
-Device Update communicates with the IoT hub it's associated with to deploy and manage updates at scale. To enable this communication, you need to grant the Device Update service principal IoT Hub Data Contributor access to the IoT hub.
+Device Update communicates with its associated IoT hub to deploy and manage updates at scale. To enable this communication, you need to grant the Device Update service principal access to the IoT hub with IoT Hub Data Contributor role.
 
-Setting this permission allows the following deployment, device and update management, and diagnostic actions:
+Granting this permission allows the following deployment, device and update management, and diagnostic actions:
 
 - Create deployment
 - Cancel deployment
@@ -53,8 +55,8 @@ To integrate an application or service with Microsoft Entra ID, first [register
 - To call Device Update from a mobile or desktop application, select **Public client/native (mobile & desktop)** in **Select a platform** and enter `https://login.microsoftonline.com/common/oauth2/nativeclient` for the **Redirect URI**.
 - To call Device Update from a website with implicit sign-on, use **Web** platform. Under **Implicit grant and hybrid flows**, select **Access tokens (used for implicit flows)**.
 
->[!NOTE]
->Use the most secure authentication flow available. Implicit flow authentication requires a high degree of trust in the application, and carries risks that aren't present in other flows. You should use this flow only when other more secure flows, such as managed identities, aren't viable.
+  >[!NOTE]
+  >Use the most secure authentication flow available. Implicit flow authentication requires a high degree of trust in the application, and carries risks that aren't present in other flows. You should use this flow only when other more secure flows, such as managed identities, aren't viable.
 
 ### Configure permissions
 

articles/iot-hub-device-update/device-update-plug-and-play.md

@@ -19,7 +19,7 @@ For more information, see the [IoT Plug and Play device developer guide](../iot/
 
 Smart devices use IoT Plug and Play model IDs to advertise their capabilities to Azure IoT applications. Device Update requires the IoT Plug and Play smart device to announce a model ID as part of the device connection. For more information, see [Model ID announcement](../iot/concepts-developer-guide-device.md#model-id-announcement).
 
-Device Update has several IoT Plug and Play models defined that support Device Update features. The Device Update model `**dtmi:azure:iot:deviceUpdateContractModel;3**` supports core Device Update functionality and uses the Device Update core interface to send update actions and metadata to devices and receive update status from devices.
+Device Update has several defined IoT Plug and Play models that support Device Update features. The Device Update model `**dtmi:azure:iot:deviceUpdateContractModel;3**` supports core Device Update functionality and uses the Device Update core interface to send update actions and metadata to devices and receive update status from devices.
 
 The other supported model is `**dtmi:azure:iot:deviceUpdateModel;3**`, which extends `**deviceUpdateContractModel;3**` and also uses IoT Plug and Play interfaces that send device property information and enable diagnostic features. For these and other versions, see [Azure IoT Plug and Play Device Update Models](https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).
 
@@ -90,7 +90,7 @@ The **deviceProperties** field contains the manufacturer and model information f
 |model|string|device to cloud|The device model of the device, reported through `deviceProperties`. The `DeviceUpdateCore` interface first attempts to read the `aduc_model` value from the [configuration file](device-update-configuration-file.md).  If the value isn't populated in the configuration file, the interface defaults to reporting the compile-time definition for `ADUC_DEVICEPROPERTIES_MODEL`. This property is reported only at boot time. <br> Default value: 'Video'|
 |contractModelId|string|device to cloud|Property the service uses to identify the base model version the Device Update agent is using to manage and communicate with the agent.<br>Value: `dtmi:azure:iot:deviceUpdateContractModel;3` for devices using Device Update agent version 1.1.0. <br>**Note:** Agents using `dtmi:azure:iot:deviceUpdateModel;2` must report the `contractModelId` as `dtmi:azure:iot:deviceUpdateContractModel;3`, because `deviceUpdateModel;3` is extended from `deviceUpdateContractModel;3`.|
 |aduVer|string|device to cloud|Version of the Device Update agent running on the device. This value is read from the build only if `ENABLE_ADU_TELEMETRY_REPORTING` is set to `1` (true) during compile time. You can choose to opt out of version reporting by setting the value to `0` (false). For more information, see [How To Build the Device Update Agent](https://github.com/Azure/iot-hub-device-update/blob/main/docs/agent-reference/how-to-build-agent-code.md).|
-|doVer|string|device to cloud|Version of the Delivery Optimization agent running on the device. The value is read from the build only if `ENABLE_ADU_TELEMETRY_REPORTING` is set to `1` (true) during compile time.|
+|doVer|string|device to cloud|Version of the Delivery Optimization agent running on the device. The value is read from the build only if `ENABLE_ADU_TELEMETRY_REPORTING` is set to `1` (true) during compile time. You can choose to opt out of version reporting by setting the value to `0` (false).|
 |Custom compatibility properties|User-defined|device to cloud|Other user-defined device properties to use for the compatibility check when targeting the update deployment.|
 
 #### State

includes/device-update-for-iot-hub-limits.md

@@ -7,7 +7,7 @@ ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
-If a given resource or operation doesn't have adjustable limits, the default and the maximum limits are the same. For adjustable limits, the limits can be raised above the default limit but not above the maximum limit.
+If a given resource or operation doesn't have adjustable limits, the default and the maximum limits are the same. Adjustable limits can be raised above the default limits but not above maximum limits.
 
 Limits can be adjusted only for the Standard SKU. Free SKU limit adjustment requests aren't accepted, and Free SKU instances can't be upgraded to Standard SKU instances.
 
@@ -29,7 +29,7 @@ The following table shows the limits associated with various Device Update opera
 | Number of devices per instance | 1 million | 10 | Yes |
 | Number of device groups per instance | 100 | 10 | Yes |
 | Number of device classes per instance | 80 | 10 | Yes |
-| Number of active deployments per instance | 50, including one reserved deployment for cancellations | 5, including one reserved deployment for cancellations | Yes |
+| Number of active deployments per instance | 50, including one reserved for cancellations | 5, including one reserved for cancellations | Yes |
 | Number of total deployments per instance, including all active, inactive, and cancelled deployments that aren't deleted | 100 | 20 | No |
 | Number of update providers per instance | 25 | 2 | No |
 | Number of update names per provider per instance | 25 | 2 | No |