Tutorial: Device Update for Azure IoT Hub using the Raspberry Pi 3 B+ reference image

Article
03/10/2023

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 on a Raspberry Pi 3 B+ board.

In this tutorial, you'll learn how to:

Download an image.
Add a tag to your IoT device.
Import an update.
Deploy an image update.
Monitor the update deployment.

Note

Image updates in this tutorial were validated on the Raspberry Pi B3 board.

Prerequisites

If you haven't already done so, create a Device Update account and instance and configure an IoT hub. This tutorial needs the device to be connected via ethernet connection.

Download files in Assets on the Device Update GitHub releases page. The Tutorial_RaspberryPi.zip has all the required files for the tutorial.

Create a device in IoT Hub and get a connection string

Now, add the device to IoT Hub. From within IoT Hub, a connection string is generated for the device.

From the Azure portal, navigate to your IoT hub.
On the left pane, select Devices. Then select New.
Under Device ID, enter a name for the device. Ensure that the Autogenerate keys checkbox is selected.
Select Save. On the Devices page, the device you created should be in the list.
Get the device connection string by navigating to 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.

Note

This tutorial uses a device connection string to authenticate and connect with the IoT Hub for ease of set-up. For production scenarios, we recommend using module identity and leveraging AIS(IoT Identity Service) to provision devices. Learn more

Set up Raspberry Pi

We provide base image and update files in Assets on the Device Update GitHub releases page. The Tutorial_RaspberryPi.zip has all the required files for the tutorial. The .wic file is the base image that you can flash on to a Raspberry Pi 3 B+ board. The swUpdate(.swu) file, custom swupdate script and manifest are the update files you would import through Device Update for IoT Hub.

This base image uses a Yocto build(based on 3.4.4 release) with:

SWUpdate which enables the dual partition update with DU
Device Update agent

To learn more about the Yocto layers used, refer to Device Update Yocto GitHub..

You can use your favorite OS flashing tool to install the Device Update base image (adu-base-image) on the SD card that will be used in the Raspberry Pi 3 B+ device. Below are the instructions for using bmaptool to flash to the SD card.

Use bmaptool to flash the SD card

Install the bmaptool utility, if you haven't done so already.
```
sudo apt-get install bmap-tools
```
Locate the path for the SD card in /dev. The path should look something like /dev/sd* or /dev/mmcblk*. You can use the dmesg utility to help locate the correct path.
Unmount all mounted partitions before flashing.
```
sudo umount /dev/<device>
```
Make sure you have write permissions to the device.
```
sudo chmod a+rw /dev/<device>
```
Optional: For faster flashing, download the bimap file and the image file and put them in the same directory.

Flash the SD card.

sudo bmaptool copy <path to image> /dev/<device>

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.

Configure the Device Update agent on Raspberry Pi

Make sure that Raspberry Pi 3 is connected to the network.
SSH into the Raspberry Pi 3 by using the following command in the PowerShell window:
```
  ssh raspberrypi3 -l root
```
The DU configuration files (du-config.json and du-diagnostics-config.json) must be on the device so that Device Update for IoT Hub configures properly.
1. To create or open the du-config.json file for editing by using:
```
  nano /adu/du-config.json
```
1. After you run the command, you should see an open editor with the file. If you've never created the file, it will be empty. Now copy the below du-config.json contents, and substitute the configurations required for your device. Then replace the example connection string with the one for the device you created in the preceding steps.
  
  du-config.json
```
{
   "schemaVersion": "1.0",
   "aduShellTrustedUsers": [
      "adu",
      "do"
   ],
   "manufacturer": "contoso",
   "model": "virtual-vacuum-v2",
   "agents": [
      {
      "name": "main",
      "runas": "adu",
      "connectionSource": {
         "connectionType": "string",
         "connectionData": "HostName=<hub_name>.azure-devices.net;DeviceId=<device_id>;SharedAccessKey=<device_key>" 
      },
      "manufacturer": "contoso",
      "model": "virtual-vacuum-v2"
      }
   ]
}  
```
1. After you finish your changes, select Ctrl+X to exit the editor. Then enter y to save the changes.
Now you need to create the du-diagnostics-config.json file by using similar commands.
1. Start by creating or opening the du-diagnostics-config.json file for editing by using:
```
  nano /adu/du-diagnostics-config.json
```
1. Copy the du-diagnostics-config.json contents provided below, and substitute any configurations that differ from the default build. The example du-diagnostics-config.json file represents the default log locations for Device Update for IoT Hub. You only need to change these default values if your implementation differs.
du-diagnostics-config.json
```
{
   "logComponents":[
      {
         "componentName":"adu",
         "logPath":"/adu/logs/"
      },
      {
         "componentName":"do",
         "logPath":"/var/log/deliveryoptimization-agent/"
      }
   ],
   "maxKilobytesToUploadPerLogPath":50
}
```
1. After you finish your changes, select Ctrl+X to exit the editor. Then enter y to save the changes.
Use the following command to show the files located in the /adu/ directory. You should see both of your configuration files.du-diagnostics-config.json files for editing by using:
```
  ls -la /adu/
```
Restart the Device Update system daemon to make sure that the configurations were applied. Use the following command within the terminal logged in to the raspberrypi:
```
  systemctl start deviceupdate-agent
```
Check that the agent is live by using the following command:
```
  systemctl status deviceupdate-agent
```
You should see the status appear as alive and green.

Connect the device in Device Update for IoT Hub

On the left pane, select Devices.
Select the link with your device name.
At the top of the page, select Device Twin.
Under the reported section of the Device Twin properties, look for the Linux kernel version.

For a new device, which hasn't received an update from Device Update, the DeviceManagement:DeviceInformation:1.swVersion value represents the firmware version running on the device. After an update has been applied to a device, Device Update uses the AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId property value to represent the firmware version running on the device.
The base and update image files have a version number in the file name.
```
 adu-<image type>-image-<machine>-<version number>.<extension>
```
Use that version number in the later "Import the update" section.

Add a Device Update group tag to your device

In the Azure portal, navigate to your IoT hub.
On the left pane, under Devices, 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 the Device Update agent, make these changes on the device twin.
Add a new Device Update tag value, as shown:
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```
This screenshot shows the section where the tag needs to be added in the twin.

Import the update

Download the sample tutorial manifest and sample update (.swu file) and the sample A/B script from Tutorial_RaspberryPi.zip under Release Assets for the latest agent.
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. For the tutorial, import the sample tutorial manifest and sample update (.swu file) and the sample A/B script downloaded earlier.
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.

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 with a link to the update under Best update. You might need to refresh once.

For more information about compliance, see Device Update compliance.
Select the target group by selecting the group name. You're directed to the group details under Group basics.
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.
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.
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.