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:
|Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell.|
|Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser.|
|Select the Cloud Shell button on the top-right menu bar in the Azure portal.|
To run the code in this article in Azure Cloud Shell:
Start Cloud Shell.
Select the Copy button on a code block to copy the code.
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.
Select Enter to run the code.
To complete this quickstart, you need to install the following software on your local machine:
- Visual Studio (Community, Professional, or Enterprise) - make sure that you include the NuGet package manager component and the Desktop Development with C++ workload when you install Visual Studio.
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.
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.
cmakesubdirectory in the device SDK root folder, and navigate to that folder:
cd <root folder>\azure-iot-sdk-c mkdir cmake cd cmake
Run the following commands to build the device SDK and the generated code stub:
cmake .. cmake --build . -- /m /p:Configuration=Release
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
Open Azure IoT explorer. You see the App configurations page.
Enter your IoT Hub connection string and select Connect.
After you connect, you see the Devices overview page.
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.
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.
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.
Select the Telemetry page and hit Start to view the telemetry data the device is sending.
Select the Properties (non-writable) page to view the non-writable properties reported by the device.
Select the Properties (writable) page to view the writable properties you can update.
Expand property name, update with a new name and select Update writable property.
To see the new name show up in the Reported Property column, select the Refresh button on top of the page.
Select the Commands page to view all the commands the device supports.
Expand the blink command and set a new blink time interval. Select Send command to call the command on the device.
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.
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: