Azure IoT SDK for C

Quickstart: Sending Telemetry from an IoT Device

This guide will walk you through the essential steps to get started with the Azure IoT SDK for C. You'll learn how to set up your development environment and send telemetry data from a simulated IoT device to Azure IoT Hub.

Prerequisites

• An Azure subscription. If you don't have one, create a free account.
• An Azure IoT Hub instance. You can create one through the Azure portal.
• A C development environment:
• A C compiler (e.g., GCC, Clang, MSVC).
• CMake build system.
• Git for version control.
• (Optional) A physical IoT device (e.g., Raspberry Pi, Arduino) for real-world testing.

Step 1: Set up Azure IoT Hub

First, ensure you have an IoT Hub instance created. Navigate to the Azure portal and create a new IoT Hub resource if you don't have one already.

Get the Connection String

Once your IoT Hub is created, you'll need to get the iothubowner connection string. This string allows your device to authenticate with IoT Hub.

1. In your IoT Hub's overview page in the Azure portal, click on Shared access policies.
2. Select the iothubowner policy.
3. Copy the Connection string--primary.

Step 2: Clone the Azure IoT SDK for C

Use Git to clone the Azure IoT SDK repository to your local machine.

git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c

Step 3: Build the SDK

The SDK uses CMake for its build system. Navigate into the cloned directory and build the SDK.

mkdir build
cd build
cmake ..
make

This will compile the core libraries of the SDK. You might need to install specific dependencies depending on your operating system. Refer to the SDK's README for detailed setup instructions.

Step 4: Create Your Device Application

Let's create a simple C application that connects to IoT Hub and sends telemetry.

Create a new file, e.g., device_telemetry.c, and add the following code:

#include <stdio.h>
#include <stdlib.h>
#include "azure/az_iot_hub_client.h"
#include "azure/core/az_json.h"
#include "azure/core/az_transport.h"
#include "azure/core/az_credentials.h"
#include "azure/core/az_result.h"

// Replace with your actual IoT Hub connection string
static const char* AZURE_IOT_HUB_CONNECTION_STRING = "HostName=YOUR_HUB_NAME.azure-devices.net;DeviceId=YOUR_DEVICE_ID;SharedAccessKey=YOUR_DEVICE_KEY";
static const char* DEVICE_ID = "YOUR_DEVICE_ID";
static const char* TELEMETRY_MESSAGE_FORMAT = "{\"temperature\": %.2f, \"humidity\": %.2f}";

int main()
{
    az_iot_hub_client client;
    az_span connection_string_span = az_span_create_from_str(AZURE_IOT_HUB_CLIENT_CONNECTION_STRING);
    az_iot_hub_client_options client_options = az_iot_hub_client_options_default();
    az_result result;

    // Initialize the IoT Hub client
    result = az_iot_hub_client_init(&client, connection_string_span, &client_options);
    if (az_failed(result)) {
        fprintf(stderr, "Failed to initialize IoT Hub client: %lu\n", result);
        return 1;
    }

    // Prepare the MQTT connection properties
    char mqtt_user_name[128];
    az_span mqtt_user_name_span = AZ_SPAN_FROM_ARRAY(mqtt_user_name);
    result = az_iot_hub_client_get_user_name(&client, mqtt_user_name_span, &mqtt_user_name_span);
    if (az_failed(result)) {
        fprintf(stderr, "Failed to get MQTT username: %lu\n", result);
        return 1;
    }

    char client_id[128];
    az_span client_id_span = AZ_SPAN_FROM_ARRAY(client_id);
    result = az_iot_hub_client_get_client_id(&client, client_id_span, &client_id_span);
    if (az_failed(result)) {
        fprintf(stderr, "Failed to get client ID: %lu\n", result);
        return 1;
    }

    printf("Connecting to Azure IoT Hub...\n");
    printf("MQTT Username: %.*s\n", AZ_SPAN_END(mqtt_user_name_span));
    printf("Client ID: %.*s\n", AZ_SPAN_END(client_id_span));

    // *** In a real application, you would establish an MQTT connection here ***
    // This typically involves a third-party MQTT client library like Paho MQTT.
    // For brevity, we'll simulate the send operation.

    // Simulate sending telemetry
    float temperature = 25.5f;
    float humidity = 60.2f;

    char telemetry_buffer[128];
    int telemetry_len = snprintf(telemetry_buffer, sizeof(telemetry_buffer), TELEMETRY_MESSAGE_FORMAT, temperature, humidity);
    if (telemetry_len < 0 || telemetry_len >= sizeof(telemetry_buffer)) {
        fprintf(stderr, "Failed to format telemetry message.\n");
        return 1;
    }

    az_span telemetry_span = az_span_create_from_str(telemetry_buffer);
    char mqtt_topic[128];
    az_span mqtt_topic_span = AZ_SPAN_FROM_ARRAY(mqtt_topic);
    result = az_iot_hub_client_telemetry_get_publish_topic(&client, mqtt_topic_span, &mqtt_topic_span);
    if (az_failed(result)) {
        fprintf(stderr, "Failed to get telemetry topic: %lu\n", result);
        return 1;
    }

    printf("Sending telemetry: %.*s\n", AZ_SPAN_END(telemetry_span));
    printf("To topic: %.*s\n", AZ_SPAN_END(mqtt_topic_span));

    // *** In a real application, you would publish this message using your MQTT client ***
    // Example: mqtt_client_publish(mqtt_client, az_span_to_char(mqtt_topic_span), az_span_to_char(telemetry_span), QOS_LEVEL);

    printf("Telemetry sent (simulated).\n");

    return 0;
}

Compile Your Application

You'll need to link your application against the built Azure IoT SDK libraries. Here's a basic example of how you might compile it (adjust paths as necessary):

# Assuming you are in the root 'azure-iot-sdk-c' directory
gcc device_telemetry.c -I./azure/ -L./build/azure-iot-sdk-c/ -laziotshared -laziotdevice -o device_telemetry
./device_telemetry

This example assumes a Linux-like environment. For other platforms or more complex build scenarios, it's highly recommended to use CMake to manage your project.

Next Steps

• Explore sending commands and device twin updates.
• Learn about secure device provisioning with the Azure IoT Device Provisioning Service.
• Integrate with other Azure services like Stream Analytics and Time Series Insights.

For more detailed examples and advanced features, please refer to the SDK samples directory.