andrewbrown changes

Author: v-thepet

articles/iot-hub-device-update/delta-updates.md

@@ -3,18 +3,18 @@ title: Azure Device Update for IoT Hub delta updates | Microsoft Learn
 description: Understand key concepts for using delta or differential updates with Azure Device Update for IoT Hub.
 author: andrewbrownmsft
 ms.author: andbrown
-ms.date: 01/21/2025
+ms.date: 01/22/2025
 ms.topic: conceptual
 ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
 # Delta updates (Preview)
 
-Delta updates in Azure Device Update for IoT Hub allow you to generate small updates that represent only the changes between two full updates, a source image and a target image. This approach is ideal for reducing the bandwidth used to download an update to a device, especially if there are only a few changes between the source and target updates.
+Delta updates allow you to generate small updates that represent only the changes between two full updates, a source image and a target image. This approach is ideal for reducing the bandwidth used to download an update to a device, especially if there are only a few changes between the source and target updates.
 
 >[!NOTE]
->The delta update feature is currently in [public preview](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
+>The delta update feature in Azure Device Update for IoT Hub is currently in [public preview](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
 
 ## Requirements for using delta updates in Device Update for IoT Hub
 
@@ -33,11 +33,11 @@ The Device Update agent _orchestrates_ the update process on the device, includi
 
 ### Update handler
 
-An update handler integrates with the Device Update agent to perform the actual update install. For delta updates, start with the [`microsoft/swupdate:2` update handler](https://github.com/Azure/iot-hub-device-update/blob/main/src/extensions/step_handlers/swupdate_handler_v2/README.md) if you don't want to modify your own SWUpdate update handler.
+An update handler integrates with the Device Update agent to perform the actual update install. For delta updates, start with the [`microsoft/swupdate:2` update handler](https://github.com/Azure/iot-hub-device-update/blob/main/src/extensions/step_handlers/swupdate_handler_v2/README.md) if you don't already have your own SWUpdate update handler that you want to modify.
 
 ### Delta processor
 
-The delta processor at [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta) creates the original SWU image file on your device after the delta file downloads, so your update handler can install the SWU file. To add the delta processor component to your device image and configure it for use, you can download a Debian package for Ubuntu 20.04 and later from [https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0](https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0).
+The delta processor at [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta) re-creates the original SWU image file on your device after the delta file downloads, so your update handler can install the SWU file. To add the delta processor component to your device image and configure it for use, you can download a Debian package for Ubuntu 20.04 and later from [https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0](https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0).
 
 If you use another distro, follow the *README.md* instructions to use CMAKE to build the delta processor from source instead. From there, install the shared object *libadudiffapi.so* directly by copying it to the */usr/lib* directory, as follows:
 
@@ -46,9 +46,9 @@ sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
 sudo ldconfig
 ```
 
-### Source SWU image file on the device
+### Add a source SWU image file to your device
 
-After the delta update file downloads to a device, it compares against a valid `<source_archive>` previously cached on the device. This process enables the delta update to recreate the full target image.
+After the delta update file downloads to a device, it is compared against a valid `<source_archive>` previously cached on the device. This process enables the delta update to recreate the full target image.
 
 The simplest way to populate this cached image is to [import](import-update.md) and [deploy](deploy-update.md) a full image update to the device via the Device Update service. If the device is configured with Device Update agent version 1.0 or later and the delta processor, the agent caches the installed SWU file automatically for later delta update use.
 
@@ -60,7 +60,7 @@ If you want to directly prepopulate the source image on your device instead, the
 - `/` encoded as `octets _2F`  
 - `=` encoded as `octets _3D`
 
-## Delta updates using the DiffGen tool
+## Delta update generation using the DiffGen tool
 
 You can create delta updates by using the [Diff Generation (DiffGen) tool](https://github.com/Azure/iot-hub-device-update-delta?tab=readme-ov-file#diff-generation).
 
@@ -72,7 +72,7 @@ The following table shows the content needed, where to get it, and recommended i
 
 | Binary name | Where to acquire | How to install |
 |--|--|--|
-| DiffGen | [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0) GitHub repo |Download the version matching the OS and distro on the machine to be used to generate delta updates. |
+| DiffGen | [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0) GitHub repo |Download the version matching the OS or distro on the machine to be used to generate delta updates. |
 | .NETCore runtime, version 8.0.0 | Via Terminal or package managers | [Install .NET on Linux](/dotnet/core/install/linux). Only the runtime is required. |
 
 ### Delta update creation using DiffGen
@@ -83,19 +83,19 @@ The DiffGen tool runs with the following required arguments and syntax:
 
 The preceding command runs the *recompress_tool.py* script, which creates the `<recompressed_target_file>`. DiffGen then uses the `<recompressed_target_file>`instead of `<target_archive>` as the target file for creating the diff. Image files within the `<recompressed_target_archive>` are compressed with gzip.
 
-Most SWU files are signed, so they also require the `<signing_command>` argument in the DiffGen command:
+If your SWU files are signed, they also require the `<signing_command>` argument in the DiffGen command:
 
 `DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"`
 
-The DiffGenTool with signing command string parameter runs the *recompress_and_sign_tool.py* script. This script creates the `<recompressed_target_file>` and also signs the *sw-description* file within the archive to create a  *sw-description.sig* file.
+The DiffGenTool with signing command string parameter runs the *recompress_and_sign_tool.py* script. This script creates the `<recompressed_target_file>`. In addition, this script also signs the *sw-description* file within the archive to create a  *sw-description.sig* file.
 
 You can use the sample *sign_file.sh* script from the [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta/tree/main/src/scripts/signing_samples/openssl_wrapper) GitHub repo to create a diff between the input source file and a recompressed and re-signed target file. Open the script, edit it to add the path to your private key file, and save it. See the [Examples](#diffgen-examples) section for sample usage.
 
 The following table describes the arguments in more detail:
 
 | Argument | Description |
 |--|--|
-| `<source_archive>` | The image that the delta creation bases against when creating the delta. **Important**: This image must be identical to the image already present on the device, for example cached from a previous update. |
+| `<source_archive>` | The image that the delta creation is based on when creating the delta. **Important**: This image must be identical to the image already present on the device, for example cached from a previous update. |
 | `<target_archive>` | The image that the delta updates the device to. |
 | `<output_path>` | The path on the host machine to place the delta file in after creation, including desired name of the generated delta file. If the path doesn't exist, the tool creates it. |
 | `<log_folder>` | The path on the host machine to create logs in. It's best to define this location as a subfolder of the output path. If the path doesn't exist, the tool creates it. |
@@ -119,7 +119,7 @@ sudo ./DiffGenTool
 /mnt/o/temp/<recompressed target file to create>.swu
 ```  
 
-If you also use the signing parameter, which you must if your SWU file is signed, you can use the sample *sign_file.sh* script from the [Azure/iot-hub-device-update-delta](https://github.com/Azure/iot-hub-device-update-delta/tree/main/src/scripts/signing_samples/openssl_wrapper) GitHub repo. Open the script, edit it to add the path to your private key file, save the script, and then run DiffGen as follows.
+If you also use the signing parameter, which you must if your SWU file is signed, you can use the sample *sign_file.sh* script mentioned previously. Open the script, edit it to add the path to your private key file, save the script, and then run DiffGen as follows.
 
 The following code creates a diff between the input source file and a recompressed and re-signed target file:
 
@@ -134,9 +134,9 @@ sudo ./DiffGenTool
 /mnt/o/temp/<path to script>/<sign_file>.sh
 ```  
 
-## Import for generated delta updates
+## Generated delta update import
 
-The process of importing a delta update to the Device Update service is the same as for any other update. If you haven't already, be sure to review [How to prepare an update to be imported into Azure Device Update for IoT Hub](create-update.md).
+The basic process of importing a delta update to the Device Update service is the same as for any other update. If you haven't already, be sure to review [How to prepare an update to be imported into Azure Device Update for IoT Hub](create-update.md).
 
 ### Generate the import manifest
 
@@ -171,12 +171,7 @@ Use the `downloadHandler` object to specify how the Device Update agent orchestr
 You can use the Azure CLI [`az iot du update init v5`](/cli/azure/iot/du/update/init#az-iot-du-update-init-v5) command to generate an import manifest for your delta update. For more information, see [Create a basic import manifest](create-update.md#create-a-basic-device-update-import-manifest).
 
 ```azurecli
-az iot du update init v5
---update-provider <provider> --update-name <update name> --update-version <update version> \
---compat manufacturer=<value your device reports> model=<value your device reports> \
---step handler=microsoft/swupdate:2 properties=<JSON-formatted handler properties such as installedCriteria> \
---file path=<path(s) to update file(s), including full file names> downloadHandler=microsoft/delta:1 \
---related-file path=<path(s) to delta file(s), including full file names> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<source SWU image file hash>"}' 
+--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}' 
 ```
 
 Save your generated import manifest JSON with the file extension *.importmanifest.json*.
@@ -185,7 +180,7 @@ Save your generated import manifest JSON with the file extension *.importmanifes
 
 Once you create your import manifest, import the delta update by following the instructions in [Add an update to Device Update for IoT Hub](import-update.md#import-an-update). You must include the following items in the import:
 
-- The *\*importmanifest.json* file
+- The *\*importmanifest.json* file that you previously created in the earlier steps
 - The `<recompressed_target_file>` SWU image the DiffGen tool created
 - The `<delta file>` the DiffGen tool created
 
@@ -195,7 +190,7 @@ The delta update deployment experience in the Azure portal is the same as deploy
 
 Once you create the deployment for your delta update, the Device Update service and client automatically determine if there's a valid delta update for each device you're deploying to. If they find a valid delta, they download and install the delta update on that device.
 
-If they don't find a valid delta update, they download the full recompressed target SWU image update instead as a fallback. This approach ensures that all devices you deploy to get the appropriate version.
+If they don't find a valid delta update, the full image update (the recompressed target SWU image) is downloaded instead as a fallback. This approach ensures that all devices you're deploying the update to get to the appropriate version.
 
 There are three possible outcomes for a delta update deployment: