Device Update for Azure IoT Hub tutorial using the Ubuntu (18.04 x64) Simulator Reference Agent

Device Update for IoT Hub supports two forms of updates – image-based and package-based.

Image updates provide a higher level of confidence in the end-state of the device. It is typically easier to replicate the results of an image-update between a pre-production environment and a production environment, since it doesn’t pose the same challenges as packages and their dependencies. Due to their atomic nature, one can also adopt an A/B failover model easily.

This tutorial walks you through the steps to complete an end-to-end image-based update using Device Update for IoT Hub.

In this tutorial you will learn how to:

  • Download and install image
  • Add a tag to your IoT device
  • Import an update
  • Create a device group
  • Deploy an image update
  • Monitor the update deployment

Prerequisites

Download and install

  • Az (Azure CLI) cmdlets for PowerShell:
    • Open PowerShell > Install Azure CLI ("Y" for prompts to install from "untrusted" source)
PS> Install-Module Az -Scope CurrentUser

Enable WSL on your Windows device (Windows Subsystem for Linux)

  1. Open PowerShell as Administrator on your machine and run the following command (you might be asked to restart after each step; restart when asked):
PS> Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
PS> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

(You may be prompted to restart after this step)

  1. Go to the Microsoft Store on the web and install Ubuntu 18.04 LTS.

  2. Start "Ubuntu 18.04 LTS" and install.

  3. When installed, you'll be asked to set root name (username) and password. Be sure to use a memorable root name password.

  4. In PowerShell, run the following command to set Ubuntu to be the default Linux distribution:

PS> wsl --setdefault Ubuntu-18.04
  1. List all Linux distributions, make sure that Ubuntu is the default one.
PS> wsl --list
  1. You should see: Ubuntu-18.04 (Default)

Download Device Update Ubuntu (18.04 x64) Simulator Reference Agent

The Ubuntu reference agent can be downloaded from the Assets section from release notes here.

There are two versions of the agent. For this tutorial, since you're exercising the image-based scenario, use AducIotAgentSim-microsoft-swupdate. If you were going to exercise the package-based scenario instead, you would use AducIotAgentSim-microsoft-apt.

Install Device Update Agent simulator

  1. Start Ubuntu WSL and enter the following command (note that extra space and dot at the end).
explorer.exe .
  1. Copy AducIotAgentSim-microsoft-swupdate (or AducIotAgentSim-microsoft-apt) from your local folder where it was downloaded under /mnt to your home folder in WSL.

  2. Run the following command to make the binaries executable.

sudo chmod u+x AducIotAgentSim-microsoft-swupdate

or

sudo chmod u+x AducIotAgentSim-microsoft-apt

Device Update for Azure IoT Hub software is subject to the following license terms:

Read the license terms prior to using the agent. Your installation and use constitutes your acceptance of these terms. If you do not agree with the license terms, do not use the Device update for IoT Hub agent.

Add device to Azure IoT Hub

Once the Device Update Agent is running on an IoT device, the device needs to be added to the Azure IoT Hub. From within Azure IoT Hub, a connection string will be generated for a particular device.

  1. From the Azure portal, launch the Device Update IoT Hub.
  2. Create a new device.
  3. On the left-hand side of the page, navigate to 'IoT Devices' > Select "New".
  4. Provide a name for the device under 'Device ID'--Ensure that "Autogenerate keys" is checkbox is selected.
  5. Select 'Save'.
  6. Now, you'll be returned to the 'Devices' page and the device you created should be in the list. Select that device.
  7. In the device view, select the 'Copy' icon next to 'Primary Connection String'.
  8. Paste the copied characters somewhere for later use in the steps below. This copied string is your device connection string.

Add connection string to simulator

Start Device Update Agent on your new Software Devices.

  1. Start Ubuntu.
  2. Run the Device Update Agent and specify the device connection string from the previous section wrapped with apostrophes:

Replace <device connection string> with your connection string

sudo ./AducIotAgentSim-microsoft-swupdate "<device connection string>"

or

./AducIotAgentSim-microsoft-apt -c '<device connection string>'
  1. Scroll up and look for the string indicating that the device is in "Idle" state. An "Idle" state signifies that the device is ready for service commands:
Agent running. [main]

Add a tag to your device

  1. Log into Azure portal and navigate to the IoT Hub.

  2. From 'IoT Devices' or 'IoT Edge' on the left navigation pane find your IoT device and navigate to the Device Twin or Module Twin.

  3. In the Module Twin of the Device Update agent module, delete any existing Device Update tag value by setting them to null. If you are using Device identity with Device Update agent make these changes on the Device Twin.

  4. Add a new Device Update tag value as shown below.

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

Import update

  1. Download the sample import manifest and sample image update. Note: these are re-used update files from the Raspberry Pi tutorial, because the update in this tutorial will be simulated and therefore the specific file content doesn't matter.

  2. Log in to the Azure portal and navigate to your IoT Hub with Device Update. Then, select the Device Updates option under Automatic Device Management from the left-hand navigation bar.

  3. Select the Updates tab.

  4. Select "+ Import New Update".

  5. Select the folder icon or text box under "Select an Import Manifest File". You will see a file picker dialog. Select the sample import manifest you downloaded in step 1 above. Next, select the folder icon or text box under "Select one or more update files". You will see a file picker dialog. Select the sample image update that you downloaded in step 1 above.

    Screenshot showing update file selection.

  6. Select the folder icon or text box under "Select a storage container". Then select the appropriate storage account.

  7. If you’ve already created a container, you can reuse it. (Otherwise, select "+ Container" to create a new storage container for updates.). Select the container you wish to use and click "Select".

Screenshot showing container selection.

  1. Select "Submit" to start the import process.

  2. The import process begins, and the screen changes to the "Import History" section. Select "Refresh" to view progress until the import process completes. Depending on the size of the update, this may complete in a few minutes but could take longer.

    Screenshot showing update import sequence.

  3. When the Status column indicates the import has succeeded, select the "Ready to Deploy" header. You should see your imported update in the list now.

Learn more about importing updates.

Create update group

  1. Go to the IoT Hub you previously connected to your Device Update instance.

  2. Select the Device Updates option under Automatic Device Management from the left-hand navigation bar.

  3. Select the Groups tab at the top of the page.

  4. Select the Add button to create a new group.

  5. Select the IoT Hub tag you created in the previous step from the list. Select Create update group.

    Screenshot showing tag selection.

Learn more about adding tags and creating update groups

Deploy update

  1. Once the group is created, you should see a new update available for your device group, with a link to the update under Pending Updates. You may need to Refresh once.

  2. Click on the available update.

  3. Confirm the correct group is selected as the target group. Schedule your deployment, then select Deploy update.

    Select update

  4. View the compliance chart. You should see the update is now in progress.

    Update in progress

  5. After your device is successfully updated, you should see your compliance chart and deployment details update to reflect the same.

    Update succeeded

Monitor an update deployment

  1. Select the Deployments tab at the top of the page.

    Deployments tab

  2. Select the deployment you created to view the deployment details.

    Deployment details

  3. Select Refresh to view the latest status details. Continue this process until the status changes to Succeeded.

You have now completed a successful end-to-end image update using Device Update for IoT Hub using the Ubuntu (18.04 x64) Simulator Reference Agent.

Clean up resources

When no longer needed, clean up your device update account, instance, IoT Hub and IoT device.

Next steps