Edit

Device Update Agent Provisioning

  • Article

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.

Changes to Device Update agent at GA release

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.

Module identity vs device identity

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.

Support for Device Update

The following IoT device over the air update types are currently supported with Device Update:

Prerequisites

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:

  1. Log onto the machine or IoT device on which you intend to install the Device Update agent.

  2. Open a Terminal window.

  3. 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

  4. Copy the generated list to the sources.list.d directory.

    sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/

  5. 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/

How to provision the Device Update agent as a Module Identity

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.

On IoT Edge enabled devices

Follow these instructions to provision the Device Update agent on IoT Edge enabled devices.

  1. Follow the instructions to Manually provision a single Linux IoT Edge device.

  2. 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.

  3. 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

  4. 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.

  5. You are now ready to start the Device Update agent on your IoT device.

On Iot Linux devices without IoT Edge installed

Follow these instructions to provision the Device Update agent on your IoT Linux devices.

  1. Install the IoT Identity Service and add the latest version to your IoT device by following instructions in Installing the Azure IoT Identity Service.

  2. Configure the IoT Identity Service by following the instructions in Configuring the Azure IoT Identity Service.

  3. 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.

  4. 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.

  5. You are now ready to start the Device Update agent on your IoT device.

Other IoT devices

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).

  1. 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.

  2. Log onto the machine or IoT Edge device/IoT device.

  3. Open a terminal window.

  4. Add the connection string to the Device Update configuration file:

    1. Enter the below in the terminal window:

    2. 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.

    3. 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

  5. Now you are now ready to start the Device Update agent on your IoT device.

How to start the Device Update Agent

This section describes how to start and verify the Device Update agent as a module identity running successfully on your IoT device.

  1. Log in to the machine or device that has the Device Update agent installed.

  2. Open a Terminal window, and enter the command below.

    sudo systemctl restart deviceupdate-agent

  3. 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.

  4. 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:

    Diagram of Device Update module name.

How to build and run Device Update Agent

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.

Troubleshooting guide

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.

Next steps

You can use the following tutorials for a simple demonstration of Device Update for IoT Hub: