Getting Started with the Azure IoT SDK for C

Welcome to the Azure IoT SDK for C! This guide will walk you through the essential steps to get your C-based device connected to Azure IoT Hub.

Prerequisites: Before you begin, ensure you have the following:
  • An Azure Subscription.
  • An IoT Hub instance created in Azure.
  • A C development environment set up on your target platform.
  • CMake build system installed.

Step 1: Install the Azure IoT SDK for C

The SDK is typically installed using CMake. You'll need to clone the repository and build it.

# Clone the Azure IoT SDK repository
git clone https://github.com/Azure/azure-iot-sdk-c.git

# Navigate into the cloned directory
cd azure-iot-sdk-c

# Create a build directory
mkdir build
cd build

# Configure the build with CMake
# For IoT Hub only:
cmake .. -Duse_amqp=ON -Duse_mqtt=ON -Duse_http=ON -Dskip_samples=OFF

# For IoT Hub and Device Provisioning Service:
# cmake .. -Duse_amqp=ON -Duse_mqtt=ON -Duse_http=ON -Duse_prov_client=ON -Dskip_samples=OFF

# Build the SDK
make
Tip: You can adjust CMake options based on your needs. For instance, set -Dskip_samples=ON if you don't need the example applications.

Step 2: Create a Device Identity in IoT Hub

You need a unique identity for your device within your Azure IoT Hub. This typically involves generating a connection string.

You can create a device identity using the Azure CLI:

az iot hub device-identity create --device-id MyCSharpDevice --hub-name YourIoTHubName

Then, retrieve the connection string:

az iot hub device-identity show-connection-string --device-id MyCSharpDevice --hub-name YourIoTHubName --output table

Important: Keep this connection string secure. It contains credentials for your device.

Step 3: Write Your First C Application

Now, let's create a simple application to send telemetry data to IoT Hub.

A common starting point is the iothub_client_sample_mqtt found within the SDK's samples directory. You can modify this sample or create your own by leveraging the SDK's APIs.

Here's a simplified conceptual example of connecting and sending a message:

#include "azure_iot_hub_client.h"
#include "azure_iot_hub_client_ll.h"
#include "iothub_message.h"
#include "azure_MQTT_api.h"
#include "azure_utc_time.h"

// ... (other includes and setup)

int main()
{
    // Initialize the IoT Hub client
    IOTHUB_CLIENT_LL_HANDLE iotHubClientHandle = IoTHubClient_LL_CreateFromConnectionString("YOUR_DEVICE_CONNECTION_STRING", MQTT_Protocol);

    if (iotHubClientHandle == NULL)
    {
        // Handle error
        return -1;
    }

    // Create a message
    IOTHUB_MESSAGE_HANDLE messageHandle = IoTHubMessage_CreateFromByteArray((const unsigned char*)"{\"message\": \"Hello from C!\"}", 23);

    if (messageHandle == NULL)
    {
        // Handle error
        IoTHubClient_LL_Destroy(iotHubClientHandle);
        return -1;
    }

    // Send the message
    if (IoTHubClient_LL_SendEventAsync(iotHubClientHandle, messageHandle, NULL, NULL) != IOTHUB_CLIENT_OK)
    {
        // Handle error
        IoTHubMessage_Destroy(messageHandle);
        IoTHubClient_LL_Destroy(iotHubClientHandle);
        return -1;
    }

    // Keep the client alive to allow messages to be sent
    // In a real application, you'd have a loop to handle events and keep connected
    IoTHubClient_LL_DoWork(iotHubClientHandle);
    // ... sleep or wait for work ...

    // Clean up
    IoTHubMessage_Destroy(messageHandle);
    IoTHubClient_LL_Destroy(iotHubClientHandle);

    return 0;
}
Note: Replace YOUR_DEVICE_CONNECTION_STRING with the actual connection string you obtained in Step 2.

Step 4: Build and Run Your Application

You'll need to configure your build system (e.g., CMake) to link against the built Azure IoT SDK libraries. The exact commands depend on your platform and build environment.

For example, using CMake:

# Assuming your application code is in 'src/my_app.c'
cd .. # Go back to root of your project
mkdir build-app
cd build-app

cmake ../azure-iot-sdk-c -DCMAKE_PREFIX_PATH=/path/to/azure-iot-sdk-c/build # Point to your SDK build directory
make my_app

# Run your application
./src/my_app

Next Steps