Device Update Agent Provisioning
The Device Update Module agent can run alongside other system processes and IoT Edge modules that connect to your IoT Hub as part of the same logical device. This section describes how to provision the Device Update agent as a module identity.
If you are using the Device Update agent versions, please migrate to the latest agent version 1.0.0 which is the GA version. See GA agent for changes and how to upgrade
You can check installed version of the Device Update agent and the Delivery Optimization agent in the Device Properties section of your IoT device twin. Learn more about device properties under ADU Core Interface.
In IoT Hub, under each device identity, you can create up to 50 module identities. Each module identity implicitly generates a module twin. On the device side, the IoT Hub device SDKs enable you to create modules where each one opens an independent connection to IoT Hub. Module identity and module twin provide the similar capabilities as device identity and device twin but at a finer granularity. Learn more about Module Identities in IoT Hub
If you are migrating from a device level agent to adding the agent as a Module identity on the device, remove the older agent that was communicating over the Device Twin. When you provision the Device Update agent as a Module Identity, all communications between the device and the Device Update service happen over the Module Twin so do remember to tag the Module Twin of the device when creating groups and all communications must happen over the module twin.
The following IoT device over the air update types are currently supported with Device Update:
Linux devices (IoT Edge and Non-IoT Edge devices):
Constrained devices:
- Eclipse ThreadX Device Update agent samples: Device Update for Azure IoT Hub tutorial for Azure-Real-Time-Operating-System
Disconnected devices:
If you're setting up the IoT device/IoT Edge device for package based updates, add packages.microsoft.com to your machine’s repositories by following these steps:
Log onto the machine or IoT device on which you intend to install the Device Update agent.
Open a Terminal window.
Install the repository configuration that matches your device’s operating system.
curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
Copy the generated list to the sources.list.d directory.
sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
Install the Microsoft GPG public key.
curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
This section describes how to provision the Device Update agent as a module identity on
- IoT Edge enabled devices, or
- Non-Edge IoT devices, or
- Other IoT devices.
To check if you have IoT Edge enabled on your device, please refer to the IoT Edge installation instructions.
Follow all or any of the below sections to add the Device update agent based on the type of IoT device you are managing.
Follow these instructions to provision the Device Update agent on IoT Edge enabled devices.
Follow the instructions to Manually provision a single Linux IoT Edge device.
Install the Device Update image update agent.
We provide sample images in the Assets here repository. The swUpdate file is the base image that you can flash onto a Raspberry Pi B3+ board. The .gz file is the update you would import through Device Update for IoT Hub. For an example, see How to flash the image to your IoT Hub device.
Install the Device Update package update agent.
For latest agent versions from packages.microsoft.com: Update package lists on your device and install the Device Update agent package and its dependencies using:
sudo apt-get update
sudo apt-get install deviceupdate-agent
For any 'rc' i.e. release candidate agent versions from Artifacts : Download the .deb file to the machine you want to install the Device Update agent on, then:
sudo apt-get install -y ./"<PATH TO FILE>"/"<.DEB FILE NAME>"
If you are setting up a MCC for a disconnected device scenario, then install the Delivery Optimization APT plugin:
sudo apt-get install deliveryoptimization-plugin-apt
After you've installed the device update agent, you will need to edit the configuration file for Device Update by running the command below.
sudo nano /etc/adu/du-config.json
Change the connectionType to "AIS" for agents who will be using the IoT Identity Service for provisioning. The ConnectionData field must be an empty string. Please note that all values with the 'Place value here' tag must be set. See Configuring a DU agent.
You are now ready to start the Device Update agent on your IoT device.
Follow these instructions to provision the Device Update agent on your IoT Linux devices.
Install the IoT Identity Service and add the latest version to your IoT device by following instructions in Installing the Azure IoT Identity Service.
Configure the IoT Identity Service by following the instructions in Configuring the Azure IoT Identity Service.
Finally install the Device Update agent. We provide sample images in Assets here, the swUpdate file is the base image that you can flash onto a Raspberry Pi B3+ board, and the .gz file is the update you would import through Device Update for IoT Hub. See example of how to flash the image to your IoT Hub device.
After you've installed the device update agent, you will need to edit the configuration file for Device Update by running the command below.
sudo nano /etc/adu/du-config.json
Change the connectionType to "AIS" for agents who will be using the IoT Identity Service for provisioning. The ConnectionData field must be an empty string. Please note that all values with the 'Place value here' tag must be set. See Configuring a DU agent.
You are now ready to start the Device Update agent on your IoT device.
The Device Update agent can also be configured without the IoT Identity service for testing or on constrained devices. Follow the below steps to provision the Device Update agent using a connection string (from the Module or Device).
We provide sample images in the Assets here repository. The swUpdate file is the base image that you can flash onto a Raspberry Pi B3+ board. The .gz file is the update you would import through Device Update for IoT Hub. For an example, see How to flash the image to your IoT Hub device.
Log onto the machine or IoT Edge device/IoT device.
Open a terminal window.
Add the connection string to the Device Update configuration file:
Enter the below in the terminal window:
- For Ubuntu agent use: sudo nano /etc/adu/du-config.json
- For Yocto reference image use: sudo nano /adu/du-config.json
Copy the primary connection string
- If Device Update agent is configured as a module copy the module's primary connection string.
- Otherwise copy the device's primary connection string.
Enter the copied primary connection string to the 'connectionData' field's value in the du-config.json file. Please note that all values with the 'Place value here' tag must be set. See Configuring a DU agent
Now you are now ready to start the Device Update agent on your IoT device.
This section describes how to start and verify the Device Update agent as a module identity running successfully on your IoT device.
Log in to the machine or device that has the Device Update agent installed.
Open a Terminal window, and enter the command below.
sudo systemctl restart deviceupdate-agent
You can check the status of the agent using the command below. If you see any issues, refer to this troubleshooting guide.
sudo systemctl status deviceupdate-agent
You should see status OK.
On the IoT Hub portal, go to IoT device or IoT Edge devices to find the device that you configured with Device Update agent. There you will see the Device Update agent running as a module. For example:
You can also build and modify your own customer Device Update agent. Follow the instructions to build the Device Update Agent from source.
Once the agent is successfully building, it's time to run the agent. Now, make the changes needed to incorporate the agent into your image. Look at how to modify the Device Update Agent for guidance.
If you run into issues, review the Device Update for IoT Hub Troubleshooting Guide to help unblock any possible issues and collect necessary information to provide to Microsoft.
You can 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.
Package Update: Getting Started using Ubuntu Server 18.04 x64 Package agent
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