Quickstart: Communicate to a device application in C via IoT Hub device streams (preview)
Azure IoT Hub currently supports device streams as a preview feature.
IoT Hub device streams allow service and device applications to communicate in a secure and firewall-friendly manner. During public preview, the C SDK supports device streams on the device side only. As a result, this quickstart covers instructions to run only the device-side application. To run an accompanying service-side application, see:
- Communicate to device apps in C# via IoT Hub device streams
- Communicate to device apps in Node.js via IoT Hub device streams
The device-side C application in this quickstart has the following functionality:
- Establish a device stream to an IoT device.
- Receive data that's sent from the service-side application and echo it back.
The code demonstrates the initiation process of a device stream, as well as how to use it to send and receive data.
Open Azure Cloud Shell
Azure Cloud Shell is an interactive shell environment hosted in Azure and used through your browser. Azure Cloud Shell allows you to
PowerShell shells to run a variety of tools to work with Azure services. Azure Cloud Shell comes pre-installed with the commands
to allow you to run the content of this article without having to install anything on your local environment.
To run any code contained in this article on Azure Cloud Shell, open a Cloud Shell session, use the Copy button on a code block to copy the code, and paste it into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. Pasted text is not automatically executed, so press Enter to run code.
You can launch Azure Cloud Shell with:
|Select Try It in the upper-right corner of a code block. This doesn't automatically copy text to Cloud Shell.|
|Open Azure Cloud Shell in your browser.|
|Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal.|
If you don’t have an Azure subscription, create a free account before you begin.
The preview of device streams is currently supported only for IoT hubs that are created in the following regions:
- Central US
- Central US EUAP
Install the latest version of Git.
Run the following command to add the Azure IoT Extension for Azure CLI to your Cloud Shell instance. The IOT Extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS)-specific commands to the Azure CLI.
az extension add --name azure-cli-iot-ext
Prepare the development environment
For this quickstart, you use the Azure IoT device SDK for C. You prepare a development environment used to clone and build the Azure IoT C SDK from GitHub. The SDK on GitHub includes the sample code that's used in this quickstart.
Download the CMake build system.
Before you start the CMake installation, it's important that the Visual Studio prerequisites (Visual Studio and the Desktop development with C++ workload) are installed on your machine. After the prerequisites are in place and you've verified the download, you can install the CMake build system.
Open a command prompt or Git Bash shell. Execute the following command to clone the Azure IoT C SDK GitHub repository:
git clone https://github.com/Azure/azure-iot-sdk-c.git --recursive -b public-preview
This operation should take a few minutes.
Create a cmake subdirectory in the root directory of the Git repository, as shown in the following command, and then go to that folder.
cd azure-iot-sdk-c mkdir cmake cd cmake
Run the following commands from the cmake directory to build a version of the SDK that's specific to your development client platform.
cmake .. make -j
In Windows, run the following commands in Developer Command Prompt for Visual Studio 2015 or 2017. A Visual Studio solution for the simulated device will be generated in the cmake directory.
rem For VS2015 cmake .. -G "Visual Studio 14 2015" rem Or for VS2017 cmake .. -G "Visual Studio 15 2017" rem Then build the project cmake --build . -- /m /p:Configuration=Release
Create an IoT hub
This section describes how to create an IoT hub by using the Azure portal.
Sign in to the Azure portal.
Select Create a resource, and then select Internet of Things.
In the list at the right, select Iot Hub. The first page for creating an IoT hub opens.
Fill in the fields:
a. In the Subscription drop-down list, select the subscription to use for your IoT hub.
b. For Resource Group, do either of the following:
To create a new resource group, select Create new and enter the name you want to use.
To use an existing resource group, select Use existing and then, in the drop-down list, select the resource group.
For more information, see Manage Azure Resource Manager resource groups.
c. In the Region drop-down list, select the region in which you want your hub to be located. Select a region that supports the IoT Hub device streams preview, either Central US or Central US EUAP.
d. In the IoT Hub Name box, enter the name for your IoT hub. The name must be globally unique. If the name you enter is available, a green check mark appears.
Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.
To continue creating your IoT hub, select Next: Size and scale.
In this pane, you can accept the default settings and select Review + create at the bottom. Consider the following options:
In the Pricing and scale tier drop-down list, select one of the standard tiers (S1, S2, or S3) or F1: Free tier. This choice can also be guided by the size of your fleet and the non-streaming workloads that you expect in your hub (for example, telemetry messages). For example, the free tier is intended for testing and evaluation. It allows 500 devices to be connected to the IoT hub and up to 8,000 messages per day. Each Azure subscription can create one IoT hub in the free tier.
For Number of IoT Hub units: This choice depends on non-streaming workload you expect in your hub. You can select 1 for now.
For more information about tier options, see Choose the right IoT hub tier.
To review your choices, select the Review + create tab. The pane that opens is similar to the following:
To create your new IoT hub, select Create. The process takes a few minutes.
Register a device
You must register a device with your IoT hub before it can connect. In this section, you use Azure Cloud Shell with the IoT Extension to register a simulated device.
To create the device identity, run the following command in Cloud Shell:
- Replace the YourIoTHubName placeholder with the name you choose for your IoT hub.
- Use MyDevice, as shown. It's the name given for the registered device. If you choose a different name for your device, use that name throughout this article, and update the device name in the sample applications before you run them.
az iot hub device-identity create --hub-name YourIoTHubName --device-id MyDevice
To get the device connection string for the device that you just registered, run the following commands in Cloud Shell:
Replace the YourIoTHubName placeholder with the name you choose for your IoT hub.
az iot hub device-identity show-connection-string --hub-name YourIoTHubName --device-id MyDevice --output table
Note the device connection string for later use in this quickstart. It looks like the following example:
Communicate between the device and the service via device streams
In this section, you run both the device-side application and the service-side application and communicate between the two.
Run the device-side application
To run the device-side application, do the following:
Provide your device credentials by editing the iothub_client_c2d_streaming_sample.c source file in the iothub_client/samples/iothub_client_c2d_streaming_sample folder and then providing your device connection string.
/* Paste in your iothub connection string */ static const char* connectionString = "[device connection string]";
Compile the code as follows:
# In Linux # Go to the sample's folder cmake/iothub_client/samples/iothub_client_c2d_streaming_sample make -j
rem In Windows rem Go to the cmake folder at the root of repo cmake --build . -- /m /p:Configuration=Release
Run the compiled program:
# In Linux # Go to the sample's folder cmake/iothub_client/samples/iothub_client_c2d_streaming_sample ./iothub_client_c2d_streaming_sample
rem In Windows rem Go to the sample's release folder cmake\iothub_client\samples\iothub_client_c2d_streaming_sample\Release iothub_client_c2d_streaming_sample.exe
Run the service-side application
As mentioned previously, the IoT Hub C SDK supports device streams on the device side only. To build and run the service-side application, follow the instructions in one of the following quickstarts:
- Communicate to a device app in C# via IoT Hub device streams
- Communicate to a device app in Node.js via IoT Hub device streams
Clean up resources
If you plan to continue to the next recommended article, you can keep and reuse the resources you've already created.
Otherwise, to avoid charges, you can delete the Azure resources that you created in this article.
Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you don't accidentally delete the wrong resource group or resources. If you created the IoT hub inside an existing resource group that contains resources that you want to keep, delete only the IoT hub resource itself, not the resource group.
To delete a resource group by name:
Sign in to the Azure portal, and then select Resource groups.
In the Filter by name box, enter the name of the resource group that contains your IoT hub.
In the result list, to the right of your resource group, select the ellipsis (...), and then select Delete resource group.
To confirm the deletion of the resource group, reenter the resource group name, and then select Delete. After a few moments, the resource group and all its contained resources are deleted.
In this quickstart, you've set up an IoT hub, registered a device, established a device stream between a C application on the device and another application on the service side, and used the stream to send data back and forth between the applications.
To learn more about device streams, see: