Tutorial: Device Update for Azure IoT Hub using the Ubuntu (18.04 x64) simulator reference agent
Device Update for Azure IoT Hub supports image-based, package-based, and script-based updates.
Image updates provide a higher level of confidence in the end state of the device. It's typically easier to replicate the results of an image update between a preproduction environment and a production environment because it doesn't pose the same challenges as packages and their dependencies. Because of their atomic nature, you 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 by using Device Update for IoT Hub.
In this tutorial, you'll learn how to:
- Download and install an image.
- Add a tag to your IoT device.
- Import an update.
- Deploy an image update.
- Monitor the update deployment.
Prerequisites
Create a Device Update account and instance configured with an IoT hub.
Have an Ubuntu 18.04 device. This device can be either physical or a virtual machine.
Download the zip file named
Tutorial_Simulator.zipfrom Release Assets in the latest release, and unzip it.If your test device is different than your development machine, download the zip file onto both.
You can use
wgetto download the zip file. Replace<release_version>with the latest release, for example0.8.2.wget https://github.com/Azure/iot-hub-device-update/releases/download/<release_version>/Tutorial_Simulator.zip
Add a device to Azure IoT Hub
After the Device Update agent is running on an IoT device, you must add the device to IoT Hub. From within IoT Hub, a connection string is generated for a particular device.
From the Azure portal, navigate to your IoT hub.
Create a new device.
On the left pane, go to Devices. Then select New.
Under Device ID, enter a name for the device. Ensure that the Autogenerate keys checkbox is selected.
Select Save.
Now, you're returned to the Devices page and the device you created should be in the list. Select that device.
In the device view, select the Copy icon next to Primary Connection String.
Paste the copied characters somewhere for later use in the following steps:
This copied string is your device connection string.
Add a tag to your device
From the Azure portal, navigate to your IoT hub.
From Devices on the left pane, find your IoT device and go to the device twin or module twin.
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 the device identity with a Device Update agent, make these changes on the device twin.
Add a new Device Update tag value, as shown:
"tags": { "ADUGroup": "<CustomTagValue>" }
Install a Device Update agent to test it as a simulator
Follow the instructions to install the Azure IoT Edge runtime on your test device.
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.
Install the Device Update agent .deb packages.
sudo apt-get install deviceupdate-agentEnter 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:
sudo nano /etc/adu/du-config.jsonSet up the agent to run as a simulator. Run the following command on the IoT device so that the Device Update agent invokes the simulator handler to process a package update with APT (
microsoft/apt:1).sudo /usr/bin/AducIotAgent --register-content-handler /var/lib/adu/extensions/sources/libmicrosoft_simulator_1.so --update-type 'microsoft/apt:1'To register and invoke the simulator handler, use the following format, filling in the placeholders:
sudo /usr/bin/AducIotAgent --register--content-handler <full path to the handler file> --update-type <update type name>Make a copy of the file
sample-du-simulator-data.json, which is from theTutorial_Simulator.zipfile that you downloaded in the prerequisites, in thetmpfolder.cp sample-du-simulator-data.json /tmp/du-simulator-data.jsonChange permissions for the new file.
sudo chown adu:adu /tmp/du-simulator-data.json sudo chmod 664 /tmp/du-simulator-data.jsonIf /tmp doesn't exist, then:
sudo mkdir/tmp sudo chown root:root/tmp sudo chmod 1777/tmpRestart the Device Update agent.
sudo systemctl restart adu-agent
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 don't agree with the license terms, don't use the Device Update for IoT Hub agent.
Note
After your testing with the simulator, run the following command to invoke the APT handler and deploy over-the-air package updates:
sudo /usr/bin/AducIotAgent --register-content-handler /var/lib/adu/extensions/sources/libmicrosoft_apt_1.so --update-type 'microsoft/a pt:1'
Import the update
In this section, you use the files TutorialImportManifest_Sim.importmanifest.json and adu-update-image-raspberrypi3.swu from the downloaded Tutorial_Simulator.zip in the prerequisites. The update file is reused from the Raspberry Pi tutorial. Because the update in this tutorial is simulated, the specific file content doesn't matter.
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.
Select the Updates tab.
Select + Import New Update.
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 will be 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.
In your container, select Upload and go to the files you downloaded in step 1. After you've selected 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.
On the Import update page, review the files to be imported. Then select Import update to start the import process.
The import process begins, and the screen switches to the Import History section. When the Status column indicates the import has succeeded, select the Available updates header. You should see your imported update in the list now.
For more information about the import process, see Import an update to Device Update for IoT Hub.
View device groups
Device Update uses groups to organize devices. Device Update automatically sorts 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.
Go to the Groups and Deployments tab at the top of the page.
View the list of groups 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. Learn about update compliance.
You should see a device group that contains the simulated device you set up in this tutorial along with 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'll 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.
For more information about tags and groups, see Manage device groups.
Deploy the update
After the group is created, you should see a new update available for your device group. A link to the update should be under Best update. You might need to refresh the page.
Select the target group by selecting the group name. You're directed to Group details under Group basics.
To start 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.
Schedule your deployment to start immediately or in the future. Then select Create.
Under Deployment details, Status turns to Active. The deployed update is marked with (deploying).
View the compliance chart to see that the update is now in progress.
After your device is successfully updated, you see that your compliance chart and deployment details are updated to reflect the same.
Monitor the update deployment
Select the Deployment history tab at the top of the page.
Select Details next to the deployment you created.
Select Refresh to view the latest status details.
You've now completed a successful end-to-end image update by 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
Feedback
Submit and view feedback for