|
| 1 | +--- |
| 2 | +title: How to prepare an update to be imported into Azure Device Update for IoT Hub | Microsoft Docs |
| 3 | +description: How-To guide for preparing to import a new update into Azure Device Update for IoT Hub. |
| 4 | +author: andrewbrownmsft |
| 5 | +ms.author: andbrown |
| 6 | +ms.date: 1/28/2022 |
| 7 | +ms.topic: how-to |
| 8 | +ms.service: iot-hub-device-update |
| 9 | +--- |
| 10 | + |
| 11 | +# Prepare an update to import into Device Update for IoT Hub |
| 12 | + |
| 13 | +Learn how to obtain a new update and prepare the update for importing into Device Update for IoT Hub. |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +* [Access to an IoT Hub with Device Update for IoT Hub enabled](create-device-update-account.md). |
| 18 | +* An IoT device (or simulator) [provisioned for Device Update](device-update-agent-provisioning.md) within IoT Hub. |
| 19 | +* [PowerShell 5](/powershell/scripting/install/installing-powershell) or later (includes Linux, macOS, and Windows installs) |
| 20 | +* Supported browsers: |
| 21 | + * [Microsoft Edge](https://www.microsoft.com/edge) |
| 22 | + * Google Chrome |
| 23 | + |
| 24 | +## Obtain an update for your devices |
| 25 | + |
| 26 | +Now that you've set up Device Update and provisioned your devices, you'll need the update file(s) that you'll be deploying to those devices. |
| 27 | + |
| 28 | +* If you’ve purchased devices from an Original Equipment Manufacturer (OEM) or solution integrator, that organization will most likely provide update files for you, without you needing to create the updates. Contact the OEM or solution integrator to find out how they make updates available. |
| 29 | + |
| 30 | +* If your organization already creates software for the devices you use, that same group will be the ones to create the updates for that software. |
| 31 | + |
| 32 | +When creating an update to be deployed using Device Update for IoT Hub, start with either the [image-based or package-based approach](understand-device-update.md#support-for-a-wide-range-of-update-artifacts) depending on your scenario. |
| 33 | + |
| 34 | +## Create a basic Device Update import manifest |
| 35 | + |
| 36 | +Once you have your update files, create an import manifest to describe the update. If you haven't already done so, be sure to familiarize yourself with the basic [import concepts](import-concepts.md). While it is possible to author an import manifest JSON manually using a text editor, this guide will use PowerShell as example. |
| 37 | + |
| 38 | +> [!TIP] |
| 39 | +> Try the [image-based](device-update-raspberry-pi.md), [package-based](device-update-ubuntu-agent.md), or [proxy update](device-update-howto-proxy-updates.md) tutorials if you haven't already done so. You can also just view sample import manifest files from those tutorials for reference. |
| 40 | +
|
| 41 | +1. [Clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) `Azure/iot-hub-device-update` [Git repository](https://github.com/Azure/iot-hub-device-update). |
| 42 | + |
| 43 | +2. Navigate to `Tools/AduCmdlets` in your local clone from PowerShell. |
| 44 | + |
| 45 | +3. Run the following commands after replacing the sample parameter values with your own. See [Import schema and API information](import-schema.md) for details on what values you can use. In particular, be aware that the same exact set of compatibility properties cannot be used with more than one Provider and Name combination. |
| 46 | + |
| 47 | + ```powershell |
| 48 | + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process |
| 49 | +
|
| 50 | + Import-Module ./AduUpdate.psm1 |
| 51 | +
|
| 52 | + $updateId = New-AduUpdateId -Provider Contoso -Name Toaster -Version 1.0 |
| 53 | +
|
| 54 | + $compat = New-AduUpdateCompatibility -Properties @{ deviceManufacturer = 'Contoso'; deviceModel = 'Toaster' } |
| 55 | +
|
| 56 | + $installStep = New-AduInstallationStep -Handler 'microsoft/swupdate:1'-HandlerProperties @{ installedCriteria = '1.0' } -Files 'path to your update file' |
| 57 | +
|
| 58 | + $update = New-AduImportManifest -UpdateId $updateId -Compatibility $compat -InstallationSteps $installStep |
| 59 | +
|
| 60 | + # Write the import manifest to a file, ideally next to the update file(s). |
| 61 | + $update | Out-File "./$($updateId.provider).$($updateId.name).$($updateId.version).importmanifest.json" -Encoding utf8 |
| 62 | + ``` |
| 63 | +
|
| 64 | +Once you've created your import manifest, if you're ready to import your update, you can scroll to the Next steps link at the bottom of this page. |
| 65 | +
|
| 66 | +## Create an advanced Device Update import manifest for a proxy update |
| 67 | +
|
| 68 | +If your update is more complex, such as a [proxy update](device-update-proxy-updates.md), you may need to create multiple import manifests. You can use the same PowerShell script from the previous section to create parent and child import manifests for complex updates. Run the following commands after replacing the sample parameter values with your own. See [Import schema and API information](import-schema.md) for details on what values you can use. |
| 69 | +
|
| 70 | + ```powershell |
| 71 | + Import-Module $PSScriptRoot/AduUpdate.psm1 -ErrorAction Stop |
| 72 | + |
| 73 | + # We will use arbitrary files as update payload files. |
| 74 | + $childFile = "$env:TEMP/childFile.bin.txt" |
| 75 | + $parentFile = "$env:TEMP/parentFile.bin.txt" |
| 76 | + "This is a child update payload file." | Out-File $childFile -Force -Encoding utf8 |
| 77 | + "This is a parent update payload file." | Out-File $parentFile -Force -Encoding utf8 |
| 78 | + |
| 79 | + # ------------------------------ |
| 80 | + # Create a child update |
| 81 | + # ------------------------------ |
| 82 | + Write-Host 'Preparing child update ...' |
| 83 | + |
| 84 | + $microphoneUpdateId = New-AduUpdateId -Provider Contoso -Name Microphone -Version $UpdateVersion |
| 85 | + $microphoneCompat = New-AduUpdateCompatibility -DeviceManufacturer Contoso -DeviceModel Microphone |
| 86 | + $microphoneInstallStep = New-AduInstallationStep -Handler 'microsoft/swupdate:1' -Files $childFile |
| 87 | + $microphoneUpdate = New-AduImportManifest -UpdateId $microphoneUpdateId ` |
| 88 | + -IsDeployable $false ` |
| 89 | + -Compatibility $microphoneCompat ` |
| 90 | + -InstallationSteps $microphoneInstallStep ` |
| 91 | + -ErrorAction Stop -Verbose:$VerbosePreference |
| 92 | + |
| 93 | + # ------------------------------ |
| 94 | + # Create another child update |
| 95 | + # ------------------------------ |
| 96 | + Write-Host 'Preparing another child update ...' |
| 97 | + |
| 98 | + $speakerUpdateId = New-AduUpdateId -Provider Contoso -Name Speaker -Version $UpdateVersion |
| 99 | + $speakerCompat = New-AduUpdateCompatibility -DeviceManufacturer Contoso -DeviceModel Speaker |
| 100 | + $speakerInstallStep = New-AduInstallationStep -Handler 'microsoft/swupdate:1' -Files $childFile |
| 101 | + $speakerUpdate = New-AduImportManifest -UpdateId $speakerUpdateId ` |
| 102 | + -IsDeployable $false ` |
| 103 | + -Compatibility $speakerCompat ` |
| 104 | + -InstallationSteps $speakerInstallStep ` |
| 105 | + -ErrorAction Stop -Verbose:$VerbosePreference |
| 106 | + |
| 107 | + # ------------------------------------------------------------ |
| 108 | + # Create the parent update which parents the child update above |
| 109 | + # ------------------------------------------------------------ |
| 110 | + Write-Host 'Preparing parent update ...' |
| 111 | + |
| 112 | + $parentUpdateId = New-AduUpdateId -Provider Contoso -Name Toaster -Version $UpdateVersion |
| 113 | + $parentCompat = New-AduUpdateCompatibility -DeviceManufacturer Contoso -DeviceModel Toaster |
| 114 | + $parentSteps = @() |
| 115 | + $parentSteps += New-AduInstallationStep -Handler 'microsoft/script:1' -Files $parentFile -HandlerProperties @{ 'arguments'='--pre'} -Description 'Pre-install script' |
| 116 | + $parentSteps += New-AduInstallationStep -UpdateId $microphoneUpdateId -Description 'Microphone Firmware' |
| 117 | + $parentSteps += New-AduInstallationStep -UpdateId $speakerUpdateId -Description 'Speaker Firmware' |
| 118 | + $parentSteps += New-AduInstallationStep -Handler 'microsoft/script:1' -Files $parentFile -HandlerProperties @{ 'arguments'='--post'} -Description 'Post-install script' |
| 119 | + |
| 120 | + $parentUpdate = New-AduImportManifest -UpdateId $parentUpdateId ` |
| 121 | + -Compatibility $parentCompat ` |
| 122 | + -InstallationSteps $parentSteps ` |
| 123 | + -ErrorAction Stop -Verbose:$VerbosePreference |
| 124 | + |
| 125 | + # ------------------------------------------------------------ |
| 126 | + # Write all to files |
| 127 | + # ------------------------------------------------------------ |
| 128 | + Write-Host 'Saving manifest and update files ...' |
| 129 | + |
| 130 | + New-Item $Path -ItemType Directory -Force | Out-Null |
| 131 | + |
| 132 | + $microphoneUpdate | Out-File "$Path/$($microphoneUpdateId.Provider).$($microphoneUpdateId.Name).$($microphoneUpdateId.Version).importmanifest.json" -Encoding utf8 |
| 133 | + $speakerUpdate | Out-File "$Path/$($speakerUpdateId.Provider).$($speakerUpdateId.Name).$($speakerUpdateId.Version).importmanifest.json" -Encoding utf8 |
| 134 | + $parentUpdate | Out-File "$Path/$($parentUpdateId.Provider).$($parentUpdateId.Name).$($parentUpdateId.Version).importmanifest.json" -Encoding utf8 |
| 135 | + |
| 136 | + Copy-Item $parentFile -Destination $Path -Force |
| 137 | + Copy-Item $childFile -Destination $Path -Force |
| 138 | + |
| 139 | + Write-Host "Import manifest JSON files saved to $Path" -ForegroundColor Green |
| 140 | + |
| 141 | + Remove-Item $childFile -Force -ErrorAction SilentlyContinue | Out-Null |
| 142 | + Remove-Item $parentFile -Force -ErrorAction SilentlyContinue | Out-Null |
| 143 | + ``` |
| 144 | + |
| 145 | +## Next steps |
| 146 | + |
| 147 | +* [Import an update](import-update.md) |
| 148 | +* [Learn about import concepts](import-concepts.md) |
0 commit comments