Quickstart: Send telemetry from a device to an IoT hub and monitor it with the Azure CLI

  • Article

IoT Hub is an Azure service designed to collect large volumes of telemetry data from IoT devices for storage or processing in the cloud. In this codeless quickstart, you use the Azure CLI to create an IoT hub and a simulated device. You send device telemetry to the hub, and also send messages, call methods, and update properties on the device. Additionally, you use the Azure portal to visualize device metrics. This article provides a basic workflow for developers using the CLI to interact with an IoT Hub application.

Prerequisites

  • If you don't have an Azure subscription, create one for trial before you begin.
  • Azure CLI. You can run all commands in this quickstart using an interactive CLI shell that runs in your browser or in an app such as Windows Terminal. If you prefer to use the CLI locally, this quickstart requires Azure CLI version 2.36 or later. Run az --version to find the version. To install or upgrade, see Install Azure CLI.

Sign in to the Azure portal

Sign in to the Azure portal.

Prepare two CLI sessions

Next, you prepare two Azure CLI sessions. If using a local CLI client, you'll run separate CLI instances. Use the separate CLI sessions for the following tasks:

  • The first session simulates an IoT device that communicates with your IoT hub.
  • The second session either monitors the device in the first session, or sends messages, commands, and property updates.

To run a command, select Copy to copy a block of code in this quickstart, paste it into your shell session, and run it.

Azure CLI requires you to be logged into your Azure account. All communication between your Azure CLI shell session and your IoT hub is authenticated and encrypted. As a result, this quickstart doesn't need extra authentication that you'd use with a real device, such as a connection string.

  • In the first CLI session, run the az extension add command. The command adds the Azure IoT Extension for Azure CLI to your CLI shell. The IOT Extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS) specific commands to Azure CLI.

    az extension add --name azure-iot

    After you install the Azure IOT extension, you don't need to install it again in any CLI session.

    Note

    This article uses the newest version of the Azure IoT extension, called azure-iot. The legacy version is called azure-cli-iot-ext.You should only have one version installed at a time. You can use the command az extension list to validate the currently installed extensions.

    Use az extension remove --name azure-cli-iot-ext to remove the legacy version of the extension.

    Use az extension add --name azure-iot to add the new version of the extension.

    To see what extensions you have installed, use az extension list.

  • Open the second CLI session. If you're using the CLI locally, open a second CLI instance.

Create an IoT hub

In this section, you use the Azure CLI to create a resource group and an IoT hub. An Azure resource group is a logical container into which Azure resources are deployed and managed. An IoT hub acts as a central message hub for bi-directional communication between your IoT application and the devices.

  1. In the first CLI session, run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the chinanorth location.

    az group create --name MyResourceGroup --location chinaeast

  2. In the first CLI session, run the Az PowerShell module iot hub create command to create an IoT hub. It takes a few minutes to create an IoT hub.

    YourIotHubName. Replace this placeholder and the surrounding braces in the following command, using the name you chose for your IoT hub. An IoT hub name must be globally unique in Azure. Use your IoT hub name in the rest of this quickstart wherever you see the placeholder.

    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}

Create and monitor a device

In this section, you create a simulated device in the first CLI session. The simulated device sends device telemetry to your IoT hub. In the second CLI session, you monitor events and telemetry.

To create and start a simulated device:

  1. In the first CLI session, run the az iot hub device-identity create command. This command creates the simulated device identity.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    simDevice. You can use this name directly for the simulated device in the rest of this quickstart. Optionally, use a different name.

    az iot hub device-identity create -d simDevice -n {YourIoTHubName}

  2. In the first CLI session, run the az iot device simulate command. This command starts the simulated device. The device sends telemetry to your IoT hub and receives messages from it.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot device simulate -d simDevice -n {YourIoTHubName}

To monitor a device:

  1. In the second CLI session, run the az iot hub monitor-events command. This command continuously monitors the simulated device. The output shows telemetry such as events and property state changes that the simulated device sends to the IoT hub.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot hub monitor-events --output table -p all -n {YourIoTHubName}

    Screenshot of monitoring events on a simulated device.

  2. After you monitor the simulated device in the second CLI session, press Ctrl+C to stop monitoring. Keep the second CLI session open to use in later steps.

Use the CLI to send a message

In this section, you send a message to the simulated device.

  1. In the first CLI session, confirm that the simulated device is still running. If the device stopped, run the following command to restart it:

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot device simulate -d simDevice -n {YourIoTHubName}

  2. In the second CLI session, run the az iot device c2d-message send command. This command sends a cloud-to-device message from your IoT hub to the simulated device. The message includes a string and two key-value pairs.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot device c2d-message send -d simDevice --data "Hello World" --props "key0=value0;key1=value1" -n {YourIoTHubName}

    Optionally, you can send cloud-to-device messages by using the Azure portal. To send messages through the Azure portal, browse to the overview page for your IoT Hub, select IoT Devices, select the simulated device, and select Message to Device.

  3. In the first CLI session, confirm that the simulated device received the message.

    Screenshot of a simulated device receiving a message.

Use the CLI to call a device method

In this section, you call a direct method on the simulated device.

  1. As you did before, confirm that the simulated device in the first CLI session is running. If not, restart it.

  2. In the second CLI session, run the az iot hub invoke-device-method command. In this example, there's no preexisting method for the device. The command calls an example method name on the simulated device and returns a payload.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot hub invoke-device-method --mn MySampleMethod -d simDevice -n {YourIoTHubName}

  3. In the first CLI session, confirm the output shows the method call.

    Screenshot of a simulated device displaying output after a method was invoked.

Use the CLI to update device properties

In this section, you update the state of the simulated device by setting property values.

  1. As you did before, confirm that the simulated device in the first CLI session is running. If not, restart it.

  2. In the second CLI session, run the az iot hub device-twin update command. This command updates the properties to the desired state on the IoT hub device twin that corresponds to your simulated device. In this case, the command sets example temperature condition properties.

    Important

    If you're using PowerShell in the CLI shell, use the PowerShell version of the command in the following code. PowerShell requires you to escape the characters in the JSON payload.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot hub device-twin update -d simDevice --desired '{"conditions":{"temperature":{"warning":98, "critical":107}}}' -n {YourIoTHubName}

    az iot hub device-twin update -d simDevice --desired '{\"conditions\":{\"temperature\":{\"warning\":98, \"critical\":107}}}' -n {YourIoTHubName}

  3. In the first CLI session, confirm that the simulated device outputs the property update.

    Screenshot that shows how to update properties on a device.

  4. In the second CLI session, run the az iot hub device-twin show command. This command reports changes to the device properties.

    YourIotHubName. Replace this placeholder in the following code with the name you chose for your IoT hub.

    az iot hub device-twin show -d simDevice --query properties.reported -n {YourIoTHubName}

    Screenshot that shows the updated properties on a device twin.

View messaging metrics in the portal

The Azure portal enables you to manage all aspects of your IoT hub and devices. In a typical IoT Hub application that ingests telemetry from devices, you might want to monitor devices or view metrics on device telemetry.

To visualize messaging metrics in the Azure portal:

  1. In the left navigation menu on the portal, select All Resources. This tab lists all resources in your subscription, including the IoT hub you created.

  2. Select the link on the IoT hub you created. The portal displays the overview page for the hub.

  3. Select Metrics in the left pane of your IoT Hub.

    IoT Hub messaging metrics

  4. In the Scope field, enter your IoT hub name.

  5. In the Metric Namespace field, select Iot Hub Standard Metrics.

  6. In the Metric field, select Total number of messages used.

  7. Hover your mouse pointer over the area of the timeline in which your device sent messages. The total number of messages at a point in time appears in the lower left corner of the timeline.

    View Azure IoT Hub metrics

  8. Optionally, use the Metric dropdown to display other metrics on your simulated device. For example, C2d message deliveries completed or Total devices (preview).

Clean up resources

If you no longer need the Azure resources created in this quickstart, you can use the Azure CLI to delete them.

If you continue to the next recommended article, you can keep the resources you already created and reuse them.

Important

Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you do not accidentally delete the wrong resource group or resources.

To delete a resource group by name:

  1. Run the az group delete command. This command removes the resource group, the IoT hub, and the device registration you created.

    az group delete --name MyResourceGroup

  2. Run the az group list command to confirm the resource group is deleted.

    az group list

Next steps

In this quickstart, you used the Azure CLI to create an IoT hub, create a simulated device, send and monitor telemetry, call a method, set desired properties, and clean up resources. You used the Azure portal to visualize messaging metrics on your device.

If you're a device developer, the suggested next step is to see the telemetry quickstart that uses the Azure IoT Device SDK for C. Optionally, see one of the available Azure IoT Hub telemetry quickstart articles in your preferred language or SDK.

To learn how to control your simulated device from a back-end application, continue to the next quickstart.

Quickstart: Control a device connected to an IoT hub