Edit

Device Update for Azure IoT Hub using Eclipse ThreadX

  • Article

This article shows you how to create the Device Update for Azure IoT Hub agent in Eclipse ThreadX NetX Duo. It also provides simple APIs for developers to integrate the Device Update capability in their application. Explore samples of key semiconductors evaluation boards that include the get-started guides to learn how to configure, build, and deploy over-the-air updates to the devices.

If you don't have an Azure subscription, create a free account before you begin.

Prerequisites

  • Access to an IoT Hub instance. We recommend that you use an S1 (Standard) tier or higher.
  • A Device Update instance and account linked to your IoT hub. Follow the guide to create and link a device update account if you haven't done so previously.

Get started

Each board-specific sample Azure real-time operating system (RTOS) project contains code and documentation on how to use Device Update for IoT Hub on it. You will:

  1. Download the board-specific sample files from Eclipse ThreadX and Device Update samples.
  2. Find the docs folder from the downloaded sample.
  3. From the docs, follow the steps for how to prepare Azure resources and an account and register IoT devices to it.
  4. Follow the docs to build a new firmware image and import manifest for your board.
  5. Publish the firmware image and manifest to Device Update for IoT Hub.
  6. Download and run the project on your device.

Learn more about Eclipse ThreadX.

Tag your device

  1. Keep the device application running from the previous step.

  2. Sign in to the Azure portal and go to the IoT hub.

  3. On the left pane, select Devices. Find your IoT device and go to the device twin.

  4. In the device twin, delete any existing Device Update tag values by setting them to null.

  5. Add a new Device Update tag value to the root JSON object, as shown:

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

View device groups

Device Update uses groups to organize devices. Device Update automatically sorts devices into groups based on their assigned tags and compatibility properties. Each device belongs to only one group, but groups can have multiple subgroups to sort different device classes.

  1. Go to the Groups and Deployments tab at the top of the page.

    Screenshot that shows ungrouped devices.

  2. View the list of groups and the update compliance chart. The update compliance chart shows the count of devices in various states of compliance: On latest update, New updates available, and Updates in progress. Learn about update compliance.

    Screenshot that shows the update compliance view.

  3. You should see a device group that contains the simulated device you set up in this tutorial along with any available updates for the devices in the new group. If there are devices that don't meet the device class requirements of the group, they'll show up in a corresponding invalid group. To deploy the best available update to the new user-defined group from this view, select Deploy next to the group.

For more information about tags and groups, see Manage device groups.

Deploy new firmware

  1. After the group is created, you should see a new update available for your device group with a link to the update under Best update. You might need to refresh once. Learn more about update compliance.

  2. Select the target group by selecting the group name. You're directed to the group details under Group basics.

    Screenshot that shows Group details.

  3. To start the deployment, go to the Current deployment tab. Select the deploy link next to the desired update from the Available updates section. The best available update for a given group is denoted with a Best highlight.

    Screenshot that shows selecting an update.

  4. Schedule your deployment to start immediately or in the future. Then select Create.

    Tip

    By default, the Start date and time is 24 hours from your current time. Be sure to select a different date and time if you want the deployment to begin earlier.

    Screenshot that shows the Create deployment screen.

  5. Under Deployment details, Status turns to Active. The deployed update is marked with (deploying).

    Screenshot that shows deployment as Active.

  6. View the compliance chart to see that the update is now in progress.

  7. After your device is successfully updated, you see that your compliance chart and deployment details updated to reflect the same.

    Screenshot that shows the update succeeded.

Monitor the update deployment

  1. Select the Deployment history tab at the top of the page.

    Screenshot that shows the deployment history.

  2. Select Details next to the deployment you created.

    Screenshot that shows deployment details.

  3. Select Refresh to view the latest status details.

You've now completed a successful end-to-end image update by using Device Update for IoT Hub on an Eclipse ThreadX embedded device.

Next steps

To learn more about Eclipse ThreadX and how it works with IoT Hub, see Eclipse ThreadX.