Use the IoT extension for Azure CLI 2.0 for Azure IoT Hub device management

End-to-end diagram

Note

Before you start this tutorial, set up your device. In the article, you set up your Azure IoT device and IoT hub, and you deploy a sample application to run on your device. The application sends collected sensor data to your IoT hub.

The IoT extension for Azure CLI 2.0 is a new open source IoT extension that adds to the capabilities of Azure CLI 2.0. Azure CLI 2.0 includes commands for interacting with Azure resource manager and management endpoints. For example, you can use Azure CLI 2.0 to create an Azure VM or an IoT hub. A CLI extension enables an Azure service to augment the Azure CLI giving you access to additional service-specific capabilities. The IoT extension gives IoT developers command line access to all IoT Hub, IoT Edge, and IoT Hub Device Provisioning Service capabilities.

Note

The features described in this article are only available in the standard tier of IoT hub. For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

Management option Task
Direct methods Make a device act such as starting or stopping sending messages or rebooting the device.
Twin desired properties Put a device into certain states, such as setting an LED to green or setting the telemetry send interval to 30 minutes.
Twin reported properties Get the reported state of a device. For example, the device reports the LED is blinking now.
Twin tags Store device-specific metadata in the cloud. For example, the deployment location of a vending machine.
Device twin queries Query all device twins to retrieve those with arbitrary conditions, such as identifying the devices that are available for use.

For more detailed explanation on the differences and guidance on using these options, see Device-to-cloud communication guidance and Cloud-to-device communication guidance.

Device twins are JSON documents that store device state information (metadata, configurations, and conditions). IoT Hub persists a device twin for each device that connects to it. For more information about device twins, see Get started with device twins.

What you learn

You learn using the IoT extension for Azure CLI 2.0 with various management options on your development machine.

What you do

Run Azure CLI 2.0 and the IoT extension for Azure CLI 2.0 with various management options.

What you need

  • Tutorial Setup your device completed which covers the following requirements:

    • An active Azure subscription.
    • An Azure IoT hub under your subscription.
    • A client application that sends messages to your Azure IoT hub.
  • Make sure your device is running with the client application during this tutorial.

  • Python 2.7x or Python 3.x

  • Install Azure CLI 2.0. One simple way to install on Windows is to download and install the MSI. You can also follow the installation instructions on Microsoft Docs to setup Azure CLI 2.0 in your environment. At a minimum, your Azure CLI 2.0 version must be 2.0.24 or above. Use az –version to validate.

  • Install the IoT extension. The simplest way is to run az extension add --name azure-cli-iot-ext. The IoT extension readme describes several ways to install the extension.

Log in to your Azure account

Log in to your Azure account by running the following command:

az login

Direct methods

az iot hub invoke-device-method --device-id <your device id> --hub-name <your hub name> --method-name <the method name> --method-payload <the method payload>

Device twin desired properties

Set a desired property interval = 3000 by running the following command:

az iot hub device-twin update -n <your hub name> -d <your device id> --set properties.desired.interval = 3000

This property can be read from your device.

Device twin reported properties

Get the reported properties of the device by running the following command:

az iot hub device-twin update -n <your hub name> -d <your device id> --set properties.reported.interval = 3000

One of the properties is $metadata.$lastUpdated which shows the last time this device sends or receives a message.

Device twin tags

Display the tags and properties of the device by running the following command:

az iot hub device-twin show --hub-name <your hub name> --device-id <your device id>

Add a field role = temperature&humidity to the device by running the following command:

az iot hub device-twin update --hub-name <your hub name> --device-id <your device id> --set tags = '{"role":"temperature&humidity"}}'

Device twin queries

Query devices with a tag of role = 'temperature&humidity' by running the following command:

az iot hub query --hub-name <your hub name> --query-command "SELECT * FROM devices WHERE tags.role = 'temperature&humidity'"

Query all devices except those with a tag of role = 'temperature&humidity' by running the following command:

az iot hub query --hub-name <your hub name> --query-command "SELECT * FROM devices WHERE tags.role != 'temperature&humidity'"

Next steps

You’ve learned how to monitor device-to-cloud messages and send cloud-to-device messages between your IoT device and Azure IoT Hub.

To continue to get started with Azure IoT Hub and to explore other IoT scenarios, see the following: