Tutorial: Device Update for Azure IoT Hub using the package agent on Ubuntu Server 18.04 x64

Device Update for Azure IoT Hub supports image-based, package-based, and script-based updates.

Package-based updates are targeted updates that alter only a specific component or application on the device. They lead to lower consumption of bandwidth and help reduce the time to download and install the update. Package-based updates also typically allow for less downtime of devices when you apply an update and avoid the overhead of creating images. They use an APT manifest, which provides the Device Update agent with the information it needs to download and install the packages specified in the APT manifest file (and their dependencies) from a designated repository.

This tutorial walks you through updating Azure IoT Edge on Ubuntu Server 18.04 x64 by using the Device Update package agent. Although the tutorial demonstrates updating IoT Edge, by using similar steps you could update other packages, such as the container engine it uses.

The tools and concepts in this tutorial still apply even if you plan to use a different OS platform configuration. Finish this introduction to an end-to-end update process. Then choose your preferred form of updating an OS platform to dive into the details.

In this tutorial, you'll learn how to:

Prerequisites

• If you haven't already done so, create a Device Update account and instance. Configure an IoT hub.

• You need the connection string for an IoT Edge device.

• If you used the Simulator agent tutorial for prior testing, run the following command to invoke the APT handler and deploy over-the-air package updates in this tutorial:

  # sudo /usr/bin/AducIotAgent --register-content-handler /var/lib/adu/extensions/sources/libmicrosoft_apt_1.so --update-type 'microsoft/a pt:1'
  

Prepare a device

Prepare a device automatically or manually.

Use the automated Deploy to Azure button

For convenience, this tutorial uses a cloud-init-based Azure Resource Manager template to help you quickly set up an Ubuntu 18.04 LTS virtual machine. It installs both the Azure IoT Edge runtime and the Device Update package agent. Then it automatically configures the device with provisioning information by using the device connection string for an IoT Edge device (prerequisite) that you supply. The Resource Manager template also avoids the need to start an SSH session to complete setup.

1. To begin, select the button:

   .

2. Fill in the available text boxes:

   

   • Subscription: The active Azure subscription to deploy the virtual machine into.
   • Resource group: An existing or newly created resource group to contain the virtual machine and its associated resources.
   • Region: The geographic region to deploy the virtual machine into. This value defaults to the location of the selected resource group.
   • DNS Label Prefix: A required value of your choosing that's used to prefix the hostname of the virtual machine.
   • Admin Username: A username, which is provided root privileges on deployment.
   • Device Connection String: A device connection string for a device that was created within your intended IoT hub.
   • VM Size: The size of the virtual machine to be deployed.
   • Ubuntu OS Version: The version of the Ubuntu OS to be installed on the base virtual machine. Leave the default value unchanged because it will be set to Ubuntu 18.04-LTS already.
   • Authentication Type: Choose sshPublicKey or password based on your preference.
   • Admin Password or Key: The value of the SSH Public Key or the value of the password based on the choice of authentication type.

   After all the boxes are filled in, select the checkbox at the bottom of the page to accept the terms. Select Purchase to begin the deployment.

3. Verify that the deployment has completed successfully. Allow a few minutes after deployment completes for the post-installation and configuration to finish installing IoT Edge and the device package update agent.

   A virtual machine resource should have been deployed into the selected resource group. Note the machine name, which is in the format vm-0000000000000. Also note the associated DNS name, which is in the format <dnsLabelPrefix>.<location>.cloudapp.azure.com.

   You can obtain the DNS name from the Overview section of the newly deployed virtual machine in the Azure portal.

   

   Tip

   To SSH into this VM after setup, use the associated DNS name with the following command: ssh <adminUsername>@<DNS_Name>.

4. Open the configuration details (See how to set up configuration file here with the command below. Set your connectionType as 'AIS' and connectionData as empty string.

/etc/adu/du-config.json

5. Restart the Device Update agent by running the following command:

 sudo systemctl restart adu-agent

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

• Device update for IoT Hub license
• Delivery optimization client license

Read the license terms before you use a package. Your installation and use of a package constitutes your acceptance of these terms. If you don't agree with the license terms, don't use that package.

Manually prepare a device

Similar to the steps automated by the cloud-init script, the following manual steps are used to install and configure a device. Use these steps to prepare a physical device.

1. Follow the instructions to install the Azure IoT Edge runtime.

   Note

   The Device Update agent doesn't depend on IoT Edge. But it does rely on the IoT Identity Service daemon that's installed with IoT Edge (1.2.0 and higher) to obtain an identity and connect to IoT Hub.

   Although not covered in this tutorial, the IoT Identity Service daemon can be installed standalone on Linux-based IoT devices. The sequence of installation matters. The Device Update package agent must be installed after the IoT Identity Service. Otherwise, the package agent won't be registered as an authorized component to establish a connection to IoT Hub.

2. Install the Device Update agent .deb packages:

   sudo apt-get install deviceupdate-agent deliveryoptimization-plugin-apt 
   

3. Enter your IoT device's module (or device, depending on how you provisioned the device with Device Update) primary connection string in the configuration file by running the following command:

   /etc/adu/du-config.json
   

4. Restart the Device Update agent by running the following command:

    sudo systemctl restart adu-agent
   

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

• Device update for IoT Hub license
• Delivery optimization client license

Read the license terms before you use a package. Your installation and use of a package constitutes your acceptance of these terms. If you don't agree with the license terms, don't use that package.

Add a tag to your device

1. Sign in to the Azure portal and go to the IoT hub.

2. On the left pane, under Devices, find your IoT Edge device and go to the device twin or module twin.

3. In the module twin of the Device Update agent module, delete any existing Device Update tag values by setting them to null. If you're using Device identity with Device Update agent, make these changes on the device twin.

4. Add a new Device Update tag value, as shown:

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

Import the update

1. Go to Device Update releases in GitHub and select the Assets dropdown list. Download Tutorial_IoTEdge_PackageUpdate.zip by selecting it. Extract the contents of the folder to discover a sample APT manifest (sample-1.0.2-aziot-edge-apt-manifest.json) and its corresponding import manifest (sample-1.0.2-aziot-edge-importManifest.json).

2. Sign in to the Azure portal and go to your IoT hub with Device Update. On the left pane, under Automatic Device Management, select Updates.

3. Select the Updates tab.

4. Select + Import New Update.

5. Select + Select from storage container. Select an existing account or create a new account by using + Storage account. Then select an existing container or create a new container by using + Container. This container is used to stage your update files for importing.

   Note

   We recommend that you use a new container each time you import an update to avoid accidentally importing files from previous updates. If you don't use a new container, be sure to delete any files from the existing container before you finish this step.

   

6. In your container, select Upload and go to the files you downloaded in step 1. After you select all your update files, select Upload. Then select the Select button to return to the Import update page.

   

   This screenshot shows the import step. File names might not match the ones used in the example.

7. On the Import update page, review the files to be imported. Then select Import update to start the import process.

   

8. The import process begins, and the screen switches to the Import History section. When the Status column indicates that the import succeeded, select the Available updates header. You should see your imported update in the list now.

   

Learn more about how to import updates.

Create an update group

1. Go to the Groups and Deployments tab at the top of the page.

   

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

   

3. Select an IoT Hub tag and Device Class from the list. Then select Create group.

   

4. After the group is created, you see that the update compliance chart and groups list are updated. The update compliance chart shows the count of devices in various states of compliance: On latest update, New updates available, and Updates in progress. Learn about update compliance.

   

5. You should see your newly created group and any available updates for the devices in the new group. If there are devices that don't meet the device class requirements of the group, they show up in a corresponding invalid group. To deploy the best available update to the new user-defined group from this view, select Deploy next to the group.

Learn more about how to add tags and create update groups.

Deploy the update

1. After the group is created, you should see a new update available for your device group with a link to the update under Best update. You might need to refresh once. Learn more about update compliance.

2. Select the target group by selecting the group name. You're directed to the group details under Group basics.

   

3. To initiate the deployment, go to the Current deployment tab. Select the deploy link next to the desired update from the Available updates section. The best available update for a given group is denoted with a Best highlight.

   

4. Schedule your deployment to start immediately or in the future. Then select Create.

   Tip

   By default, the Start date and time is 24 hours from your current time. Be sure to select a different date and time if you want the deployment to begin earlier.

   

5. Under Deployment details, Status turns to Active. The deployed update is marked with (deploying).

   

6. View the compliance chart to see that the update is now in progress.

7. After your device is successfully updated, you see that your compliance chart and deployment details updated to reflect the same.

   

Monitor the update deployment

1. Select the Deployment history tab at the top of the page.

   

2. Select the details link next to the deployment you created.

   

3. Select Refresh to view the latest status details.

You've now completed a successful end-to-end package update by using Device Update for IoT Hub on an Ubuntu Server 18.04 x64 device.

Clean up resources

When no longer needed, clean up your device update account, instance, and IoT hub. Also clean up the IoT Edge device if you created the VM via the Deploy to Azure button. To clean up resources, go to each individual resource and select Delete. Clean up a device update instance before you clean up the device update account.

Next steps

Use the following tutorials for a simple demonstration of Device Update for IoT Hub:

• Image Update: Getting started with Raspberry Pi 3 B+ reference Yocto image extensible via open source to build your own images for other architecture as needed.
• Proxy Update: Getting started using Device Update binary agent for downstream devices.
• Getting started using Ubuntu (18.04 x64) simulator reference agent.
• Device Update for Azure IoT Hub tutorial for Azure real-time operating system.