Device Update for Azure IoT Hub tutorial using the Raspberry Pi 3 B+ Reference Image

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

In this tutorial you will learn how to:

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

Note: Image updates in this tutorial have been validated on the Raspberry Pi B3 board.

Prerequisites

Download image

We provide sample images in "Assets" on the Device Update GitHub releases page. The .gz file is the base image that you can flash onto a Raspberry Pi B3+ board, and the swUpdate file is the update you would import through Device Update for IoT Hub.

Flash SD card with image

Using your favorite OS flashing tool, install the Device Update base image (adu-base-image) on the SD Card that will be used in the Raspberry Pi 3 B+ device.

Using bmaptool to flash SD card

  1. If you have not already, install the bmaptool utility.

    sudo apt-get install bmap-tools
    
  2. 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.

  3. You will need to unmount all mounted partitions before flashing.

    sudo umount /dev/<device>
    
  4. Make sure you have write permissions to the device.

    sudo chmod a+rw /dev/<device>
    
  5. Optional. For faster flashing, download the bimap file along with the image file and place them in the same directory.

  6. 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 do not agree with the license terms, do not use the Device update for IoT Hub agent.

Create device or module in IoT Hub and get connection string

Now, the device needs to be added to the Azure IoT Hub. From within Azure IoT Hub, a connection string will be generated for the device.

  1. From the Azure portal, launch the Azure 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 will be returned to the 'Devices' page and the device you created should be in the list.
  7. Get the device connection string:
    • Option 1 Using Device Update agent with a module identity: From the same 'Devices' page click on '+ Add Module Identity' on the top. Create a new Device Update module with the name 'IoTHubDeviceUpdate', choose other options as it applies to your use case and then click 'Save'. Click on the newly created 'Module' and in the module view, select the 'Copy' icon next to 'Primary Connection String'.
    • Option 2 Using Device Update agent with the device identity: 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.

Provision connection string on SD card

  1. Make sure that the Raspberry Pi3 is connected to the network.
  2. In PowerShell, use the below command to ssh into the device
    ssh raspberrypi3 -l root
    
  3. Enter login as 'root', and password should be left as empty.
  4. After you successfully ssh into the device, run the below commands

Replace <device connection string> with your connection string

	echo "connection_string=<device connection string>" > /adu/adu-conf.txt  
	echo "aduc_manufacturer=ADUTeam" >> /adu/adu-conf.txt
	echo "aduc_model=RefDevice" >> /adu/adu-conf.txt

Connect the device in Device Update IoT Hub

  1. On the left-hand side of the page, select 'IoT Devices'.

  2. Select the link with your device name.

  3. At the top of the page, select 'Device Twin' if directly connecting to Device Update using the IoT device identity. Otherwise select the module you created above and click on its ‘Module Twin’.

  4. 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 will represent the firmware version running on the device. Once an update has been applied to a device, Device Update will use AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId property value to represent the firmware version running on the device.

  5. The base and update image files have a version number in the filename.

    adu-<image type>-image-<machine>-<version number>.<extension>
    

Use that version number in the Import Update step below.

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.

  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 update file 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 Updates option under 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 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 on a Raspberry Pi 3 B+ device.

Clean up resources

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

Next steps