Azure IoT Hub SDK for C

Welcome to the official documentation for the Azure IoT Hub SDK for C. This SDK provides the tools and libraries you need to connect your C-based devices to Azure IoT Hub, enabling secure and reliable communication for your IoT solutions.

Note: This documentation is continuously updated. Please ensure you are referring to the latest version for the most accurate information.

Getting Started

Begin your journey by setting up your development environment and understanding the core concepts of connecting to IoT Hub.

SDK Overview

The Azure IoT Hub SDK for C is designed for resource-constrained environments and offers a robust set of APIs for device management, telemetry, and command handling. It supports various transport protocols including:

Prerequisites

Before you can use the SDK, ensure you have the following:

Installation Guide

You can integrate the SDK into your C project using CMake or by compiling the source code directly. We recommend using CMake for its cross-platform compatibility and ease of dependency management.

  1. Clone the SDK repository from GitHub: 
    git clone https://github.com/Azure/azure-iot-sdk-c.git
  2. Navigate to the SDK directory: 
    cd azure-iot-sdk-c
  3. Build the SDK using CMake: 
    mkdir build
cd build
cmake ..
make

For detailed instructions specific to your platform, refer to the official GitHub repository README.

Quickstart: Send Telemetry

This section walks you through a basic example of sending telemetry data from your device to Azure IoT Hub.

1. Device Connection String

Obtain the device connection string from your Azure IoT Hub portal. It looks like this:

HostName=your-iot-hub.azure-devices.net;DeviceId=your-device-id;SharedAccessKey=YOUR_SHARED_ACCESS_KEY

2. Sample Code (Illustrative)

Here's a simplified example of how you might use the SDK to send a message:

// Include necessary SDK headers
#include "azure_iot_hub_client.h"
#include "azure_iot_message.h"
#include "azure_iot_pal_time.h"

int main() {
    // Initialize IoT Hub client (replace with your connection string)
    const char* connection_string = "HostName=your-iot-hub.azure-devices.net;DeviceId=your-device-id;SharedAccessKey=YOUR_SHARED_ACCESS_KEY";
    IotHubClient_Handle handle = IoTHubClient_CreateFromConnectionString(connection_string);

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

    // Prepare message payload
    const char* telemetry_data = "{\"temperature\": 25.5, \"humidity\": 60}";
    IOTHUB_MESSAGE_HANDLE message_handle = IoTHubMessage_CreateFromString(telemetry_data);

    if (message_handle == NULL) {
        // Handle error
        IoTHubClient_Destroy(handle);
        return -1;
    }

    // Set message properties (optional)
    IoTHubMessage_SetProperty(message_handle, "contentEncoding", "UTF-8");
    IoTHubMessage_SetProperty(message_handle, "contentType", "application/json");

    // Send the message
    IOTHUB_CLIENT_RESULT send_result = IoTHubClient_SendEventAsync(handle, message_handle, NULL, NULL);

    if (send_result != IOTHUB_CLIENT_OK) {
        // Handle error
        IoTHubMessage_Destroy(message_handle);
        IoTHubClient_Destroy(handle);
        return -1;
    }

    printf("Telemetry message sent successfully.\n");

    // Clean up
    IoTHubMessage_Destroy(message_handle);
    IoTHubClient_Destroy(handle);

    return 0;
}
Tip: For robust error handling and more advanced features like device twin management and direct method calls, explore the example applications provided in the SDK's samples/solutions/core/ directory.

API Reference

Detailed documentation for the various APIs, data structures, and functions available in the C SDK.

Core APIs

This section covers the fundamental building blocks for interacting with IoT Hub, including client creation, message handling, and event callbacks.

...

Transport Protocols

Information on configuring and using different transport protocols (MQTT, AMQP, HTTP) for your device connectivity.

...

Device Twin APIs

Learn how to manage your device's state and properties using the device twin features.

...

Direct Method APIs

Implement logic to receive and respond to direct method calls from your IoT Hub.

...

Troubleshooting

Common issues and their solutions when working with the Azure IoT Hub C SDK.

Important: Ensure your device's clock is synchronized to avoid authentication issues. Use an NTP client for reliable timekeeping.

Community & Support

Join the community, ask questions, and find help.