Edit

Share via

Tutorial: Azure Device Update for IoT Hub using a simulator agent

  • Article

Azure Device Update for IoT Hub supports image-based, package-based, and script-based updates. This tutorial demonstrates an end-to-end image-based Device Update update that uses an Ubuntu simulator agent.

Image updates provide a high level of confidence in the end state of the device, and don't pose the same package and dependency management challenges as package or script based updates. It's easier to replicate the results of an image update between a preproduction and production environment, or easily adopt an A/B failover model.

In this tutorial, you:

  • Assign an IoT device to a Device Update group by using tags.
  • Download and install an image update.
  • Import the image update.
  • Deploy the image update.
  • View the update deployment history.

Prerequisites

Register and configure a device and module

Add a device to the device registry in your IoT hub. Every device that connects to IoT Hub must be registered.

  1. In the Azure portal, open the IoT hub page associated with your Device Update instance.
  2. In the navigation pane, select Device management > Devices.
  3. On the Devices page, select Add Device.
  4. Under Device ID, enter a name for the device. Ensure that Autogenerate keys checkbox is selected.
  5. Select Save. The device appears in the list on the Devices page.

Create a module identity

After you register the device, create a module identity. Modules are independent identities for IoT device components, which allow for finer granularity when the device runs multiple processes.

For this tutorial, you create a module identity for the Device Update agent that runs on the device. For more information, see Understand and use module twins in IoT Hub.

  1. On the Devices page, select the device you registered.
  2. On the device page, select Add Module Identity.
  3. On the Add Module Identity page, under Module Identity Name, enter a name for the module such as DeviceUpdateAgent.
  4. Select Save. The new module identity appears on the device page under Module Identities.
  5. Select the module name, and on the Module Identity Details page, select the Copy icon next to Connection string (primary key). Save this module connection string to use when you configure the Device Update agent.

Add a group tag to your module twin

Device Update automatically organizes devices into groups based on their assigned tags and compatibility properties. Each device belongs to only one group, but groups can have multiple subgroups to sort different device classes.

You can assign a tag to any device that Device Update manages to assign the device to a Device Update group. The tag can be in the device twin or in the module twin as in this tutorial. Each device can be assigned to only one Device Update group.

  1. On the Module Identity Details page, select Module Identity Twin.

  2. On the Module Identity Twin page, add a new DeviceUpdateGroup tag to the JSON code at the same level as modelId and version, as follows:

    "tags": {
    "DeviceUpdateGroup": "DU-simulator-tutorial"
},

  3. Select Save. The portal reformats the module twin to incorporate the tag into the JSON structure.

Install and configure the Device Update agent

The Device Update agent runs on every device that Device Update manages. In this tutorial, you install the Device Update agent on the Ubuntu 18.04 device and configure it to run as a simulator, demonstrating how you can apply an update to a device without changing the device configuration.

Note

You can also use the Azure IoT Identity Service to provision the device. To do that, install the Azure IoT Identity Service before installing the Device Update agent. Then configure the Device Update agent with "connectionType": "AIS" and leave connectionData as a blank string in the configuration file.

  1. Add the Microsoft package repository, and then add the Microsoft package signing key to your list of trusted keys.

    wget https://packages.microsoft.com/config/ubuntu/18.04/multiarch/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

  2. Install the Device Update agent .deb packages.

    sudo apt-get update
sudo apt-get install deviceupdate-agent

  3. Open the du-config.json agent configuration file.

    sudo nano /etc/adu/du-config.json

  4. Update du-config.json with the following example values. Replace the <connection string> placeholder with the connection string you copied from the module identity. For more information about the parameters, see Device Update configuration file.

    • manufacturer: "contoso"
    • model: "video"
    • agents.name: "aduagent"
    • agents.connectionData: <connection string>
    • agents.manufacturer: "contoso"
    • agents.model: "video"

    The edited du-config.json file should look like this:

    {
   "schemaVersion": "1.0",
   "aduShellTrustedUsers": [
      "adu",
      "do"
   ],
   "manufacturer": "contoso",
   "model": "video",
   "agents": [
      {
      "name": "aduagent",
      "runas": "adu",
      "connectionSource": {
         "connectionType": "string",
         "connectionData": <connection string>
      },
      "manufacturer": "contoso",
      "model": "video"
      }
   ]
}

  5. Press Ctrl+X to exit the editor, and enter y to save your changes.

  6. To set up the agent to run as a simulator, run the following command on the IoT device. The Device Update agent invokes the simulator handler to process updates that use the Microsoft SWUpdate extension.

      sudo /usr/bin/AducIotAgent --extension-type updateContentHandler --extension-id 'microsoft/swupdate:1' --register-extension /var/lib/adu/extensions/sources/libmicrosoft_simulator_1.so

Get the simulator files

  1. Download and extract the Tutorial_Simulator.zip archive from the GitHub Device Update Releases latest release Assets section onto your Ubuntu 18.04 machine.

    You can use wget to download the ZIP file. Replace <release_version> with the latest release, for example 1.0.0.

    wget https://github.com/Azure/iot-hub-device-update/releases/download/<release_version>/Tutorial_Simulator.zip

  2. Copy the sample-du-simulator-data.json file from the extracted Tutorial_Simulator folder to the tmp folder.

    cp sample-du-simulator-data.json /tmp/du-simulator-data.json

    Note

    If the tmp folder doesn't exist, create it as follows:

    sudo mkdir/tmp
sudo chown root:root/tmp
sudo chmod 1777/tmp

  3. Change the permissions for the /tmp/sample-du-simulator-data.json file.

    sudo chown adu:adu /tmp/du-simulator-data.json
sudo chmod 664 /tmp/du-simulator-data.json

  4. Restart the Device Update agent to apply your changes.

     sudo systemctl restart deviceupdate-agent

Import the update

Download and extract the Tutorial_Simulator.zip archive from the GitHub Device Update Releases latest release Assets section onto your development machine, if it's different from your Ubuntu 18.04 IoT device. This section uses the TutorialImportManifest_Sim.importmanifest.json and adu-update-image-raspberrypi3.swu files from the Tutorial_Simulator folder.

The update file is the same one as in the Raspberry Pi tutorial. Because the update in this tutorial is simulated, the specific file content doesn't matter.

  1. On your development machine, sign in to the Azure portal and go to the IoT hub configured with your Device Update instance.

  2. In the navigation pane, select Device Management > Updates.

  3. On the Updates page, select Import a new update.

  4. On the Import update page, select Select from storage container.

  5. Select an existing storage account, or create a new account by selecting Storage account.

  6. Select an existing container, or create a new container by selecting Container. This container is used to stage the update files for importing.

    Note

    To avoid accidentally importing files from previous updates, use a new container each time you import an update. If you don't use a new container, be sure to delete any files from the existing container.

  7. On the container page, select Upload. Browse to and select the TutorialImportManifest_Sim.importmanifest.json and adu-update-image-raspberrypi3.swu files, and then select Upload.

  8. Select the checkboxes by both files and then select Select to return to the Import update page.

    Screenshot that shows selecting uploaded files in the container.

  9. On the Import update page, review the files to be imported, and then select Import update.

    Screenshot that shows uploaded files to be imported as an update.

    The import process begins, and you can select View import history to view import history and status. On the Update history page, the Status field shows Succeeded when the import is complete. You can select Refresh to update the status.

The imported update now appears on the Updates page.

Screenshot that shows the new update listed as an available update.

For more information about the import process, see Import an update to Device Update for IoT Hub.

Select the device group

You can use the group tag you applied to your device to deploy the update to the device group. Select the Groups and Deployments tab at the top of the Updates page to view the list of groups and deployments and the update compliance chart.

The 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.

Under Group name, you see a list of all the device groups for devices connected to this IoT hub and their available updates, with links to deploy the updates under Status. Any devices that don't meet the device class requirements of a group appear in a corresponding invalid group. For more information about tags and groups, see Manage device groups.

You should see the device group that contains the simulated device you set up in this tutorial. Select the group name to view its details.

Screenshot that shows the update compliance view.

Deploy the update

  1. On the Group details page, you should see one new update available for this group. Select Deploy to start the deployment.

    Screenshot that shows starting a group update deployment.

  2. The update you imported is listed as the best available update for this group. Select Deploy.

  3. Schedule your deployment to start immediately, and then select Create.

  4. Navigate to the Current updates tab. Under Deployment details, Status turns to Active.

  5. After your device successfully updates, return to the Updates page. You should see that your compliance chart and deployment details updated to include the installed update.

View update deployment history

  1. Return to the group details page and select the Deployment history tab.

  2. Select View deployment details next to the deployment you created. Select Refresh to view the latest status details.

    Screenshot that shows Deployment details.

Clean up resources

If you're going to continue to the next tutorial, keep your Device Update and IoT Hub resources. When you no longer need the resources you created for this tutorial, you can delete them.

  1. In the Azure portal, navigate to the resource group that contains the resources.
  2. If you want to delete all the resources in the group, select Delete resource group.
  3. If you want to delete only some of the resources, use the check boxes to select the resources and then select Delete.

Related content