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.

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

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 Install and provision the Azure IoT Edge runtime.

  2. Install the Device Update image update agent.

    We provide sample images in the Artifacts 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.miscrosoft.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 deliveryoptimization-plugin-apt
      
    • For any 'rc' i.e. release candidate agent versions from Artifacts : Download the .dep file to the machine you want to install the Device Update agent on, then:

      sudo apt-get install -y ./"<PATH TO FILE>"/"<.DEP FILE NAME>"
      
  4. You are now ready to start the Device Update agent on your IoT Edge device.

On non-Edge IoT Linux devices

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.

    1. Log onto the machine or IoT device.
    2. Open a terminal window.
    3. Install the latest IoT Identity Service on your IoT device using this command:

    Note

    The IoT Identity service registers module identities with IoT Hub by using symmetric keys currently.

     sudo apt-get install aziot-identity-service
    
  2. Provisioning IoT Identity service to get the IoT device information.

    Create a custom copy of the configuration template so we can add the provisioning information. In a terminal, enter the following command:

    sudo cp /etc/aziot/config.toml.template /etc/aziot/config.toml 
    
  3. Next edit the configuration file to include the connection string of the device you wish to act as the provisioner for this device or machine. In a terminal, enter the below command.

    sudo nano /etc/aziot/config.toml
    
  4. You should see a message like the following example:

    Diagram of IoT Identity Service config file.

    1. In the same nano window, find the block with “Manual provisioning with connection string”.
    2. In the window, delete the “#” symbol ahead of 'provisioning'
    3. In the window, delete the “#” symbol ahead of 'source'
    4. In the window, delete the “#” symbol ahead of 'connection_string'
    5. In the window, delete the string within the quotes to the right of 'connection_string' and then add your connection string there
    6. Save your changes to the file with 'Ctrl+X' and then 'Y' and hit the 'enter' key to save your changes.
  5. Now apply and restart the IoT Identity service with the command below. You should now see a “Done!” printout that means you have successfully configured the IoT Identity Service.

    Note

    The IoT Identity service registers module identities with IoT Hub by using symmetric keys currently.

    sudo aziotctl config apply
    
  6. Finally install the Device Update agent. We provide sample images in Artifacts, 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.

  7. 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 Artifacts 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. You should see a window open with some text in it. Delete the entire string following 'connection_String=' the first-time you provision the Device Update agent on the IoT device. It is just place holder text.

    3. In the terminal, replace <your-connection-string> with the connection string of the device for your instance of Device Update agent. Select Enter and then Save. It should look this example:

      connection_string=<ADD CONNECTION STRING HERE>
      

    Important

    Do not add quotes around the connection string.

  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 into the machine or device that has the Device Update agent installed.

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

    sudo systemctl restart adu-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 adu-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 pre-built images and binaries for a simple demonstration of Device Update for IoT Hub: