Simplify IoT Device Updates with Azure Device Update for IoT Hub

Sooner or later, while working with IoT devices, we come across the need to update the software installed on them. These devices might have intermittent connections, be spread around the world, and be hard to access.

In the last project I worked on, one of the challenges we faced was updating the OS and software packages on devices without accessing them through SSH. To solve this, we leveraged Azure Device Update for IoT Hub, enabling us to automate updates and remotely install Linux packages or execute scripts seamlessly—from Azure to the edge—without direct interaction with the devices.

In this post, I’ll show you how to set up a device to communicate and receive updates from Azure IoT Hub.

Pre-requisites

• Azure account
• Azure Iot Hub
• Have Azure Device Update for IoT Hub active for the target Iot Hub
• Storage account

Set-up the device

First of all, to start working with Azure Device Update, we need to install and configure it. For this tutorial, I’ll be using Ubuntu 22.04. So, let’s get started!

• Install device update package

wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install deviceupdate-agent

• Open the configuration details (See how to set up configuration file here with the command below). Set your information like manufacturer, model and connection string.

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

{
  "schemaVersion": "1.1",
  "aduShellTrustedUsers": [
    "adu",
    "do"
  ],
  "iotHubProtocol": "mqtt",
  "compatPropertyNames":"manufacturer,model,location,environment" <The property values must be in lower case only>,
  "manufacturer": <Place your device info manufacturer here>,
  "model": <Place your device info model here>,
  "agents": [
    {
      "name": <Place your agent name here>,
      "runas": "adu",
      "connectionSource": {
        "connectionType": "string", //or “AIS”
        "connectionData": <Place your Azure IoT device connection string here>
      },
      "manufacturer": <Place your device property manufacturer here>,
      "model": <Place your device property model here>,
      "additionalDeviceProperties": {
        "location": "usa",
        "environment": "development"
      }
    }
  ]
}

My test example:

{
  "schemaVersion": "1.1",
  "aduShellTrustedUsers": [
    "adu",
    "do"
  ],
  "iotHubProtocol": "mqtt",
  "manufacturer": "amazingdevice",
  "model": "xyz",
  "agents": [
    {
      "name": "main",
      "runas": "adu",
      "connectionSource": {
        "connectionType": "string",
        "connectionData": "your iot hub connection string"
      },
      "manufacturer": "amazingdevice",
      "model": "xyz"
    }
  ]
}

Finally restart the Device Update Agent:

sudo systemctl restart deviceupdate-agent

• Tag the device.

• On the left panel, under Devices, find your IoT device and go to the device twin or module twin (when Azure IoT Edge).

• In the device twin, 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 module twin of the Device Update agent module.

• Add a new Device Update tag value, as shown:
  

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

Prepare the update

After prepare our device to communicates with Device Update for IoT Hub, we can finally start work on that. We will install a package called cowsay , nothing special with cowsay, the purpose is only see this package installed and running in the end of the process.

Prepare apt update and import manifest files

We need to prepare two files to install cowsay from Azure IoT, the apt manifest file that has information such as name, version and etc. And manifest import file. The last one should be generate with Azure Cli. Example:

cowsay-apt-manifest.json

{
    "name": "Install cowsay",
    "version": "1.0.0", 
    "packages": [
        {
            "name": "cowsay",
            "version": "3.03+dfsg2-8"
        }
    ]
}

After create the apt manifest file, we can generate the manifest import file with the az command:

az iot du update init v5 --update-provider me --update-name aptcowsay --update-version 1.0.0 --compat manufacturer=amazingdevice model=xyz --step handler=microsoft/apt:1 --file path=C:/Projects/adu/apt/cowsay-apt-manifest.json

Resulting content:

cowsay-apt.importmanifest.json

{
    "compatibility": [
      {
        "manufacturer": "amazingdevice",
        "model": "xyz"
      }
    ],
    "createdDateTime": "2024-12-16T22:59:40Z",
    "files": [
      {
        "filename": "cowsay-apt-manifest.json",
        "hashes": {
          "sha256": "JNYocz3l4Ofwd94l14HT+2GvyHLtmWNMd+KbyYLcRBk="
        },
        "sizeInBytes": 179
      }
    ],
    "instructions": {
      "steps": [
        {
          "files": [
            "cowsay-apt-manifest.json"
          ],
          "handler": "microsoft/apt:1",
          "handlerProperties": {
            "installedCriteria": "1.0"
          },
          "type": "inline"
        }
      ]
    },
    "manifestVersion": "5.0",
    "updateId": {
      "name": "aptcowsay",
      "provider": "me",
      "version": "1.0.0"
    }
  }

Publish a new update

With the two required files created for preparing an update in the Azure portal, the next step is to upload them to an Azure Storage Account, configure the update, and publish it.

• Upload the two files on Azure Storage account;
• Go to Iot Hub, Device Management, Updates, Import a new update and select the manifest files from Storage Account;

• Select the tab Groups and Deployments, select the Group Name "adugrouptest" (it is the value of tag from ADUGroup that we defined before);

• A new update is available as you can see, click in Deploy, select Start Immediately and create;

• Next page you can monitoring the update

• When succeeded pass from 0 to 1, click on "View devices", and select your device:

If the process was completed successfully, you should see:

Result code: 700

Deployment step results > Result code: 700

Check the result on device

Now it’s time to verify if the "cowsay" package is indeed installed on our device. To do this, connect to the device and type: cowsay [some text].

Considerations

This was a simple example of what can be achieved with Azure Device Update for IoT Hub. In the scenario demonstrated, we showcased a package-based update, but it’s also possible to manage image-based and script-based updates, handle larger groups of devices, and explore many other features. For more details, refer to the official documentation..