How to view and update devices based on device twin properties

Use the Azure portal and Azure CLI to manage devices through device twins and module twins. This article focuses on device twins for simplicity, but all of the concepts and processes work in a similar way for module twins.

This article describes device twin management tasks available in the Azure portal or Azure CLI to manage device twins remotely. For information about developing device applications to handle device twin changes, see Get started with device twins.

In IoT Hub, a device twin is a JSON document that stores state information. Every device identity is automatically associated with a device twin when it's created. A backend app or user can update two elements of a device twin:

  • Desired properties: Desired properties are half of a linked set of state information. A backend app or user can update the desired properties on a twin to communicate a desired state change, while a device can update the reported properties to communicate its current state.
  • Tags: You can use device twin tags to organize and manage devices in your IoT solutions. You can set tags for any meaningful category, like device type, location, or function.

For more information, see Understand and use device twins in IoT Hub or Understand and use module twins in IoT Hub.

Note

The features described in this article are available only in the standard tier of IoT Hub. For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier and size for your solution.

Prerequisites

Prepare the following prerequisites before you begin.

  • An IoT hub in your Azure subscription. If you don't have a hub yet, follow the steps in Create an IoT hub.

  • A device registered in your IoT hub. If you don't have a device in your IoT hub, follow the steps in Register a device.

Understand tags for device organization

Device twin tags can be used as a powerful tool to help you organize your devices. When you have multiple kinds of devices within your IoT solutions, you can use tags to set types, locations, etc. For example:

{
  "deviceId": "mydevice1",
  "status": "enabled",
  "connectionState": "Connected",
  "cloudToDeviceMessageCount": 0,
  "authenticationType": "sas",
  "tags": {
    "deploymentLocation": {
      "building": "43",
      "floor": "1"
    },
    "deviceType":"HDCamera"
  },
  "properties": {
    ...
  }
}

View and update device twins

Once a device identity is created, a device twin is implicitly created in IoT Hub. You can use the Azure portal or Azure CLI to retrieve the device twin of a given device. You can also add, edit, or remove tags and desired properties.

  1. In the Azure portal, navigate to your IoT hub.

  2. In your IoT hub, select Devices from the Device management section of the navigation menu.

    The default Devices list shows up to 15 devices and doesn't provide the complete device inventory. To find a device that isn't displayed, enter its device ID in the search box. You can also apply a filter or run a query. For more information, see Query for device twins.

    Important

    The default list doesn't display device twin tag values. This limitation doesn't mean that the devices have no tags. View tags on the device details page, in Device twin, or in filtered or query results.

    The Type value in the default list can show an IoT Edge device as an IoT device because the capability information isn't available in this view. To find IoT Edge devices, select IoT Edge under Device management, or filter Devices to IoT Edge devices.

    Note

    Search and filter results are eventually consistent. Newly created devices and recent twin changes might not appear immediately. To check the current twin values for a known device, use a direct Get Twin request. For more information, see Twin query limitations.

  3. Select the device ID to open the device details page.

  4. The device details page displays any current tags for the selected device. Select edit next to the Tags parameter to add, update, or remove tags.

    Tip

    To add or update nested tags, select the Advanced tab and provide the JSON.

  5. Select Device twin to view and update the device twin JSON.

    Device twin tags are in the tags object. You can type directly in the text box to update tags or desired properties. To remove a tag or desired property, set the value of the item to null.

  6. Select Save to save your changes.

  7. Back on the device details page, select Refresh to update the page to reflect your changes.

If your device has any module identities associated with it, those modules are displayed on the device details page as well. Select a module name, then select Module identity twin to view and update the module twin JSON.

Query for device twins

IoT Hub exposes the device twins for your IoT hub as a document collection called devices. You can query devices based on their device twin values.

This section describes how to run twin queries in the Azure portal and Azure CLI. To learn how to write twin queries, see Queries for IoT Hub device and module twins.

Note

Device twin queries are eventually consistent. Newly created devices and recent twin changes might not appear immediately, and deleted devices might remain in results temporarily. A missing device or tag in query results doesn't by itself mean that it was deleted. To retrieve the current twin values for a known device, use a direct Get Twin request. For more information, see Twin query limitations.

  1. In the Azure portal, navigate to your IoT hub.

  2. Use a filter on Devices or run a query on Queries to find devices based on their device twin details:

    • Find devices using a filter:

      1. Select Devices under Device management.

      2. Select Add filter, and then select Device tag as the filter type from the drop-down menu.

      3. Enter the tag name and value you want, and then select Apply to get devices that match the criteria.

        Filtered results can display device twin tags. If Load more is available, select it to request additional filtered results. This is different from the default list, which displays up to 15 devices without device twin tag values.

    • Find devices using a query:

      1. Select Queries under Device management.

      2. Keep the prefilled SELECT * FROM devices query to get device twins, or enter a query to filter by a tag. For example, the following query returns device IDs and tags for devices whose devicetype tag is testIoTDevice:

        SELECT deviceId, tags
FROM devices
WHERE tags.devicetype = 'testIoTDevice'

        Replace the tag name and value with the ones your devices use.

      3. Select Run query and check the results.

Update device twins using jobs

The jobs capability can execute device twin updates against a set of devices at a scheduled time. For more information, see Schedule jobs on multiple devices.

Jobs aren't supported in the Azure portal. Instead, use the Azure CLI.

  • Last updated on