Edit

Share via

Quickstart: Control a device connected to an IoT hub

  • Article

In this quickstart, you use a direct method to control a simulated device connected to your IoT hub. IoT Hub is an Azure service that lets you manage your IoT devices from the cloud and ingest high volumes of device telemetry to the cloud for storage or processing. You can use direct methods to remotely change the behavior of devices connected to your IoT hub.

The quickstart uses two pre-written .NET applications:

  • A simulated device application that responds to direct methods called from a service application. To receive the direct method calls, this application connects to a device-specific endpoint on your IoT hub.

  • A service application that calls the direct methods on the simulated device. To call a direct method on a device, this application connects to service-side endpoint on your IoT hub.

Prerequisites

  • An Azure account with an active subscription. Create one for free.

  • The two sample applications you run in this quickstart are written using C#. You need the .NET SDK 6.0 or greater on your development machine.

    You can download the .NET Core SDK for multiple platforms from .NET.

    You can verify the current version of C# on your development machine using the following command:

    dotnet --version

  • Clone or download the Azure IoT C# SDK from GitHub.

  • Make sure that port 8883 is open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see Connecting to IoT Hub (MQTT).

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.

In this section, you use Azure CLI to create an IoT hub and a resource group. 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.

If you already have an IoT hub in your Azure subscription, you can skip this section.

To create an IoT hub and a resource group:

  1. Launch your CLI app. To run the CLI commands in the rest of this article, copy the command syntax, paste it into your CLI app, edit variable values, and press Enter.

    • If you're using Cloud Shell, select the Try It button on the CLI commands to launch Cloud Shell in a split browser window. Or you can open the Cloud Shell in a separate browser tab.
    • If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.

  2. Run az extension add to install or upgrade the azure-iot extension to the current version.

    az extension add --upgrade --name azure-iot

  3. In your CLI app, run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the eastus location.

    Note

    Optionally, you can set a different location. To see available locations, run az account list-locations. This quickstart uses eastus as shown in the example command.

    az group create --name MyResourceGroup --location eastus

  4. Run the az iot hub create command to create an IoT hub. It might take 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 {your_iot_hub_name}

Retrieve the service connection string

You also need your IoT hub's service connection string to enable the service application to connect to the hub and retrieve the messages. The service connection string is for your IoT hub as a whole, and is different from the device connection string you retrieved in the previous section.

The following command retrieves the service connection string for your IoT hub:

az iot hub connection-string show --policy-name service --hub-name {YourIoTHubName} --output table

Make a note of the service connection string, which looks like:

HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}

You use this value later in the quickstart.

Simulate a device

The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.

  1. In a local terminal window, navigate to the root folder of the sample C# project. Then navigate to the iothub\device\samples\getting started\SimulatedDeviceWithCommand folder.

  2. Run the following command to install the required packages for simulated device application:

    dotnet restore

  3. Run the following command to build and run the simulated device application.

    {DeviceConnectionString}: Replace this placeholder with the device connection string you noted previously.

    dotnet run -- -c "{DeviceConnectionString}"

    The following screenshot shows the output as the simulated device application sends telemetry to your IoT hub:

    Run the simulated device

Call the direct method

The service application connects to a service-side endpoint on your IoT Hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub service application typically runs in the cloud.

  1. In another local terminal window, navigate to the root folder of the sample C# project. Then navigate to the iothub\service\samples\getting started\InvokeDeviceMethod folder.

  2. In the local terminal window, run the following commands to install the required libraries for the service application:

    dotnet build

  3. In the local terminal window, run the following commands to build and run the service application.

    {ServiceConnectionString}: Replace this placeholder with the IoT Hub service connection string you noted previously.

    {DeviceName}: Replace this placeholder with the name of the device you registered.

    dotnet run -- -c "{ServiceConnectionString}" -d {DeviceName}

    The following screenshot shows the output as the application makes a direct method call to the device and receives an acknowledgment:

    Run the service application

    After you run the service application, you see a message in the console window running the simulated device, and the rate at which it sends messages changes:

    Change in simulated client

This quickstart uses two Java applications:

  • A simulated device application that responds to direct methods called from a back-end application.
  • A service application that calls the direct method on the simulated device.

Prerequisites

  • An Azure account with an active subscription. Create one for free.

  • Java SE Development Kit 8. In Java long-term support for Azure and Azure Stack, under Long-term support, select Java 8.

    You can verify the current version of Java on your development machine using the following command:

    java -version

  • Apache Maven 3.

    You can verify the current version of Maven on your development machine using the following command:

    mvn --version

  • Clone or download the Azure IoT Java samples from GitHub.

  • Make sure that port 8883 open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see Connecting to IoT Hub (MQTT).

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.

Create an IoT hub

In this section, you use Azure CLI to create an IoT hub and a resource group. 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.

If you already have an IoT hub in your Azure subscription, you can skip this section.

To create an IoT hub and a resource group:

  1. Launch your CLI app. To run the CLI commands in the rest of this article, copy the command syntax, paste it into your CLI app, edit variable values, and press Enter.

    • If you're using Cloud Shell, select the Try It button on the CLI commands to launch Cloud Shell in a split browser window. Or you can open the Cloud Shell in a separate browser tab.
    • If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.

  2. Run az extension add to install or upgrade the azure-iot extension to the current version.

    az extension add --upgrade --name azure-iot

  3. In your CLI app, run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the eastus location.

    Note

    Optionally, you can set a different location. To see available locations, run az account list-locations. This quickstart uses eastus as shown in the example command.

    az group create --name MyResourceGroup --location eastus

  4. Run the az iot hub create command to create an IoT hub. It might take 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 {your_iot_hub_name}

Register a device

A device must be registered with your IoT hub before it can connect. In this section, you use Azure CLI to create a device identity.

If you already have a device registered in your IoT hub, you can skip this section.

To create a device identity:

  1. Run the az iot hub device-identity create command in your CLI shell. This command creates the device identity.

    your_iot_hub_name. Replace this placeholder below with the name you chose for your IoT hub.

    myDevice. You can use this name for the device ID throughout this article, or provide a different device name.

    az iot hub device-identity create --device-id myDevice --hub-name {your_iot_hub_name}

  2. Run the az iot hub device-identity connection-string show command.

    az iot hub device-identity connection-string show --device-id myDevice --hub-name {your_iot_hub_name}

    The connection string output is in the following format:

    HostName=<your IoT Hub name>.azure-devices.net;DeviceId=<your device id>;SharedAccessKey=<some value>

  3. Save the connection string in a secure location.

Note

Keep your CLI app open. You'll use it in later steps.

Retrieve the service connection string

You also need a service connection string to enable the back-end application to connect to your IoT hub and retrieve the messages. The following command retrieves the service connection string for your IoT hub:

YourIoTHubName: Replace this placeholder below with the name you chose for your IoT hub.

az iot hub connection-string show --policy-name service --hub-name {YourIoTHubName} --output table

Make a note of the service connection string, which looks like:

HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}

You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.

Simulate a device

The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.

  1. In a local terminal window, navigate to the root folder of the sample Java project. Then navigate to the iot-hub\Quickstarts\simulated-device-2 folder.

  2. Open the src/main/java/com/microsoft/docs/iothub/samples/SimulatedDevice.java file in a text editor of your choice.

    Replace the value of the connString variable with the device connection string you made a note of earlier. Then save your changes to SimulatedDevice.java.

  3. In the local terminal window, run the following commands to install the required libraries and build the simulated device application:

    mvn clean package

  4. In the local terminal window, run the following commands to run the simulated device application:

    java -jar target/simulated-device-2-1.0.0-with-deps.jar

    The following screenshot shows the output as the simulated device application sends telemetry to your IoT hub:

    Output from the telemetry sent by the device to your IoT hub

Call the direct method

The back-end application connects to a service-side endpoint on your IoT Hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub back-end application typically runs in the cloud.

  1. In another local terminal window, navigate to the root folder of the sample Java project. Then navigate to the iot-hub\Quickstarts\back-end-application folder.

  2. Open the src/main/java/com/microsoft/docs/iothub/samples/BackEndApplication.java file in a text editor of your choice.

    Replace the value of the iotHubConnectionString variable with the service connection string you made a note of earlier. Then save your changes to BackEndApplication.java.

  3. In the local terminal window, run the following commands to install the required libraries and build the back-end application:

    mvn clean package

  4. In the local terminal window, run the following commands to run the back-end application:

    java -jar target/back-end-application-1.0.0-with-deps.jar

    The following screenshot shows the output as the application makes a direct method call to the device and receives an acknowledgment:

    Output as the application makes a direct method call through your IoT hub

    After you run the back-end application, you see a message in the console window running the simulated device, and the rate at which it sends messages changes:

    Console message from device shows the rate at which it changes

This quickstart uses two Node.js applications:

  • A simulated device application that responds to direct methods called from a back-end application. To receive the direct method calls, this application connects to a device-specific endpoint on your IoT hub.
  • A back-end application that calls the direct methods on the simulated device. To call a direct method on a device, this application connects to a service-specific endpoint on your IoT hub.

Prerequisites

  • An Azure account with an active subscription. Create one for free.

  • Node.js 12+.

    You can verify the current version of Node.js on your development machine using the following command:

    node --version

  • Clone or download the Azure IoT Node.js samples from GitHub.

  • Make sure that port 8883 is open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see Connecting to IoT Hub (MQTT).

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.

Create an IoT hub

In this section, you use Azure CLI to create an IoT hub and a resource group. 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.

If you already have an IoT hub in your Azure subscription, you can skip this section.

To create an IoT hub and a resource group:

  1. Launch your CLI app. To run the CLI commands in the rest of this article, copy the command syntax, paste it into your CLI app, edit variable values, and press Enter.

    • If you're using Cloud Shell, select the Try It button on the CLI commands to launch Cloud Shell in a split browser window. Or you can open the Cloud Shell in a separate browser tab.
    • If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.

  2. Run az extension add to install or upgrade the azure-iot extension to the current version.

    az extension add --upgrade --name azure-iot

  3. In your CLI app, run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the eastus location.

    Note

    Optionally, you can set a different location. To see available locations, run az account list-locations. This quickstart uses eastus as shown in the example command.

    az group create --name MyResourceGroup --location eastus

  4. Run the az iot hub create command to create an IoT hub. It might take 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 {your_iot_hub_name}

Register a device

A device must be registered with your IoT hub before it can connect. In this section, you use Azure CLI to create a device identity.

If you already have a device registered in your IoT hub, you can skip this section.

To create a device identity:

  1. Run the az iot hub device-identity create command in your CLI shell. This command creates the device identity.

    your_iot_hub_name. Replace this placeholder below with the name you chose for your IoT hub.

    myDevice. You can use this name for the device ID throughout this article, or provide a different device name.

    az iot hub device-identity create --device-id myDevice --hub-name {your_iot_hub_name}

  2. Run the az iot hub device-identity connection-string show command.

    az iot hub device-identity connection-string show --device-id myDevice --hub-name {your_iot_hub_name}

    The connection string output is in the following format:

    HostName=<your IoT Hub name>.azure-devices.net;DeviceId=<your device id>;SharedAccessKey=<some value>

  3. Save the connection string in a secure location.

Note

Keep your CLI app open. You'll use it in later steps.

Retrieve the service connection string

You also need your IoT hub's service connection string to enable the back-end application to connect to your IoT hub and retrieve the messages. The following command retrieves the service connection string for your IoT hub:

YourIoTHubName: Replace this placeholder below with the name you chose for your IoT hub.

az iot hub connection-string show \
  --policy-name service --hub-name {YourIoTHubName} --output table

Make a note of the service connection string, which looks like:

HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}

You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.

Simulate a device

The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.

  1. In a local terminal window, navigate to the root folder of the sample Node.js project. Then navigate to the iot-hub\Quickstarts\simulated-device-2 folder.

  2. Open the SimulatedDevice.js file in a text editor of your choice.

    Replace the value of the connectionString variable with the device connection string you made a note of earlier. Then save your changes to SimulatedDevice.js.

  3. In the local terminal window, run the following commands to install the required libraries and run the simulated device application:

    npm install
node SimulatedDevice.js

    The following screenshot shows the output as the simulated device application sends telemetry to your IoT hub:

    Run the simulated device

Call the direct method

The back-end application connects to a service-side endpoint on your IoT hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub back-end application typically runs in the cloud.

  1. In another local terminal window, navigate to the root folder of the sample Node.js project. Then navigate to the iot-hub\Quickstarts\back-end-application folder.

  2. Open the BackEndApplication.js file in a text editor of your choice.

    Replace the value of the connectionString variable with the service connection string you made a note of earlier. Then save your changes to BackEndApplication.js.

  3. In the local terminal window, run the following commands to install the required libraries and run the back-end application:

    npm install
node BackEndApplication.js

    The following screenshot shows the output as the application makes a direct method call to the device and receives an acknowledgment:

    Output when the application makes direct method call to the device

    After you run the back-end application, you see a message in the console window running the simulated device, and the rate at which it sends messages changes:

    Output when there is a change in the simulated client

This quickstart uses two Python applications:

  • A simulated device application that responds to direct methods called from a back-end application.
  • A back-end application that calls the direct methods on the simulated device.

Prerequisites

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.

Create an IoT hub

In this section, you use Azure CLI to create an IoT hub and a resource group. 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.

If you already have an IoT hub in your Azure subscription, you can skip this section.

To create an IoT hub and a resource group:

  1. Launch your CLI app. To run the CLI commands in the rest of this article, copy the command syntax, paste it into your CLI app, edit variable values, and press Enter.

    • If you're using Cloud Shell, select the Try It button on the CLI commands to launch Cloud Shell in a split browser window. Or you can open the Cloud Shell in a separate browser tab.
    • If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.

  2. Run az extension add to install or upgrade the azure-iot extension to the current version.

    az extension add --upgrade --name azure-iot

  3. In your CLI app, run the az group create command to create a resource group. The following command creates a resource group named MyResourceGroup in the eastus location.

    Note

    Optionally, you can set a different location. To see available locations, run az account list-locations. This quickstart uses eastus as shown in the example command.

    az group create --name MyResourceGroup --location eastus

  4. Run the az iot hub create command to create an IoT hub. It might take 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 {your_iot_hub_name}

Register a device

A device must be registered with your IoT hub before it can connect. In this section, you use Azure CLI to create a device identity.

If you already have a device registered in your IoT hub, you can skip this section.

To create a device identity:

  1. Run the az iot hub device-identity create command in your CLI shell. This command creates the device identity.

    your_iot_hub_name. Replace this placeholder below with the name you chose for your IoT hub.

    myDevice. You can use this name for the device ID throughout this article, or provide a different device name.

    az iot hub device-identity create --device-id myDevice --hub-name {your_iot_hub_name}

  2. Run the az iot hub device-identity connection-string show command.

    az iot hub device-identity connection-string show --device-id myDevice --hub-name {your_iot_hub_name}

    The connection string output is in the following format:

    HostName=<your IoT Hub name>.azure-devices.net;DeviceId=<your device id>;SharedAccessKey=<some value>

  3. Save the connection string in a secure location.

Note

Keep your CLI app open. You'll use it in later steps.

Retrieve the service connection string

You also need a service connection string to enable the back-end application to connect to your IoT hub and retrieve the messages. The following command retrieves the service connection string for your IoT hub:

YourIoTHubName: Replace this placeholder below with the name you choose for your IoT hub.

az iot hub connection-string show \
  --policy-name service \
  --hub-name {YourIoTHubName} \
  --output table

Make a note of the service connection string, which looks like:

HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}

You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.

Simulate a device

The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.

  1. In a local terminal window, navigate to the root folder of the sample Python project. Then navigate to the iot-hub\Quickstarts\simulated-device-2 folder.

  2. Open the SimulatedDeviceSync.py file in a text editor of your choice.

    Replace the value of the CONNECTION_STRING variable with the device connection string you made a note of earlier. Then save your changes to SimulatedDeviceSync.py.

  3. In the local terminal window, run the following commands to install the required libraries for the simulated device application:

    pip install azure-iot-device

  4. In the local terminal window, run the following commands to run the simulated device application:

    python SimulatedDeviceSync.py

    The following screenshot shows the output as the simulated device application sends telemetry to your IoT hub:

    Run the simulated device

Call the direct method

The back-end application connects to a service-side endpoint on your IoT Hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub back-end application typically runs in the cloud.

  1. In another local terminal window, navigate to the root folder of the sample Python project. Then navigate to the iot-hub\Quickstarts\back-end-application folder.

  2. Open the BackEndApplication.py file in a text editor of your choice.

    Replace the value of the CONNECTION_STRING variable with the service connection string you made a note of earlier. Then save your changes to BackEndApplication.py.

  3. In the local terminal window, run the following commands to install the required libraries for the simulated device application:

    pip install azure-iot-hub

  4. In the local terminal window, run the following commands to run the back-end application:

    python BackEndApplication.py

    The following screenshot shows the output as the application makes a direct method call to the device and receives an acknowledgment:

    Run the back-end application

    After you run the back-end application, you see a message in the console window running the simulated device, and the rate at which it sends messages changes:

    Change in simulated client

Clean up resources

If you will be continuing to the next recommended article, you can keep the resources you've already created and reuse them.

Otherwise, you can delete the Azure resources created in this article to avoid charges.

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. If you created the IoT Hub inside an existing resource group that contains resources you want to keep, only delete the IoT Hub resource itself instead of deleting the resource group.

To delete a resource group by name:

  1. Sign in to the Azure portal and select Resource groups.

  2. In the Filter by name textbox, type the name of the resource group containing your IoT Hub.

  3. To the right of your resource group in the result list, select ... then Delete resource group.

    Delete

  4. You will be asked to confirm the deletion of the resource group. Type the name of your resource group again to confirm, and then select Delete. After a few moments, the resource group and all of its contained resources are deleted.

Next steps

In this quickstart, you called a direct method on a device from a service application, and responded to the direct method call in a simulated device application.

To learn how to route device-to-cloud messages to different destinations in the cloud, continue to the next tutorial.

Tutorial: Route telemetry to different endpoints for processing