Quickstart: Connect a sample IoT Plug and Play Preview device application running on Windows to IoT Hub (C Windows)

This quickstart shows you how to build a sample IoT Plug and Play device application, connect it to your IoT hub, and use the Azure IoT explorer tool to view the information it sends to the hub. The sample application is written in C and is included in the Azure IoT Hub Device C SDK. A solution developer can use the Azure IoT explorer tool to understand the capabilities of an IoT Plug and Play device without the need to view any device code.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Prerequisites

To complete this quickstart, you need to install the following software on your local machine:

Install the Azure IoT explorer

Download and install the latest release of Azure IoT explorer from the tool's repository page, by selecting the .msi file under "Assets" for the most recent update.

Prepare an IoT hub

You also need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a free account before you begin. If you don't have an IoT hub, follow these instructions to create one.

Important

During public preview, IoT Plug and Play features are only available on IoT hubs created in the Central US, North Europe, and Japan East regions.

If you're using the Azure CLI locally, first sign in to your Azure subscription using az login. If you're running these commands in the Azure Cloud Shell, you're signed in automatically.

If you're using the Azure CLI locally, the az version should be 2.0.73 or later; the Azure Cloud Shell uses the latest version. Use the az --version command to check the version installed on your machine.

Run the following command to add the Microsoft Azure IoT Extension for Azure CLI to your instance:

az extension add --name azure-cli-iot-ext

Run the following command to create the device identity in your IoT hub. Replace the YourIoTHubName and YourDeviceID placeholders with your own IoT Hub name and a device ID of your choice.

az iot hub device-identity create --hub-name <YourIoTHubName> --device-id <YourDeviceID>

Run the following command to get the device connection string for the device you just registered (note for use later):

az iot hub device-identity show-connection-string --hub-name <YourIoTHubName> --device-id <YourDeviceID> --output table

Run the following command to get the IoT hub connection string for your hub (note for use later):

az iot hub show-connection-string --hub-name <YourIoTHubName> --output table

Prepare the development environment

In this quickstart, you prepare a development environment you can use to clone and build the Azure IoT Hub Device C SDK.

Open a command prompt in the directory of your choice. Execute the following command to clone the Azure IoT C SDKs and Libraries GitHub repository into this location:

git clone https://github.com/Azure/azure-iot-sdk-c --recursive -b public-preview

You should expect this operation to take several minutes to complete.

Build the code

You use the device SDK to build the included sample code. The application you build simulates a device that connects to an IoT hub. The application sends telemetry and properties and receives commands.

  1. Create a cmake subdirectory in the device SDK root folder, and navigate to that folder:

    cd <root folder>\azure-iot-sdk-c
    mkdir cmake
    cd cmake
    
  2. Run the following commands to build the device SDK and the generated code stub:

    cmake ..
    cmake --build . -- /m /p:Configuration=Release
    

    Note

    If cmake can't find your C++ compiler, you get build errors when you run the previous command. If that happens, try running this command at the Visual Studio command prompt.

Run the device sample

Run a sample application in the SDK to simulate an IoT Plug and Play device that sends telemetry to your IoT hub. To run the sample application, use these commands and pass the device connection string as a parameter.

cd digitaltwin_client\samples\digitaltwin_sample_device\Release
copy ..\EnvironmentalSensor.interface.json .
digitaltwin_sample_device.exe "<YourDeviceConnectionString>"

The device is now ready to receive commands and property updates, and has begun sending telemetry data to the hub. Keep the sample running as you complete the next steps.

Use the Azure IoT explorer to validate the code

  1. Open Azure IoT explorer. You see the App configurations page.

  2. Enter your IoT Hub connection string and select Connect.

  3. After you connect, you see the Devices overview page.

  1. To ensure the tool can read the interface model definitions from your device, select Settings. In the Settings menu, On the connected device may already appear in the Plug and Play configurations; if it does not, select + Add module definition source and then On the connected device to add it.

  2. Back on the Devices overview page, find the device identity you created previously. With the device application still running in the command prompt, check that the device's Connection state in Azure IoT explorer is reporting as Connected (if not, hit Refresh until it is). Select the device to view more details.

  3. Expand the interface with ID urn:YOUR_COMPANY_NAME_HERE:EnvironmentalSensor:1 to reveal the interface and IoT Plug and Play primitives—properties, commands, and telemetry.

  1. Select the Telemetry page and hit Start to view the telemetry data the device is sending.

  2. Select the Properties (non-writable) page to view the non-writable properties reported by the device.

  3. Select the Properties (writable) page to view the writable properties you can update.

  4. Expand property name, update with a new name and select Update writable property.

  5. To see the new name show up in the Reported Property column, select the Refresh button on top of the page.

  6. Select the Commands page to view all the commands the device supports.

  7. Expand the blink command and set a new blink time interval. Select Send command to call the command on the device.

  8. Go to the simulated device command prompt and read through the printed confirmation messages, to verify that the commands have executed as expected.

Clean up resources

If you plan to continue with additional IoT Plug and Play articles, you can keep and reuse the resources you used in this quickstart. Otherwise, you can delete the resources you created in this quickstart to avoid additional charges.

You can delete both the hub and registered device at once by deleting the entire resource group with the following command for Azure CLI. (Don't use this, however, if these resources are sharing a resource group with other resources you have for different purposes.)

az group delete --name <YourResourceGroupName>

To delete just the IoT hub, run the following command using Azure CLI:

az iot hub delete --name <YourIoTHubName>

To delete just the device identity you registered with your IoT hub, run the following command using Azure CLI:

az iot hub device-identity delete --hub-name <YourIoTHubName> --device-id <YourDeviceID>

You may also want to remove the cloned sample files from your development machine.

Next steps

In this quickstart, you've learned how to connect an IoT Plug and Play device to an IoT hub. To learn more about how to build a solution that interacts with your IoT Plug and Play devices, see: