Azure IoT C SDKs and Libraries

The Azure IOT Hub Device SDK allows applications written in C99 or later or C++ to communicate easily with Azure IoT Hub, Azure IoT Central and toAzure IoT Device Provisioning. This repo includes the source code for the libraries, setup instructions, and samples demonstrating use scenarios.

For constained devices - where memory is measured in kilobytes and not megabytes - there are even lighter weight SDK options available. See Other Azure IoT SDKs for more.

Table of Contents

• Azure IoT C SDKs and Libraries
  • Table of Contents
  • Critical Upcoming Change Notice
  • Getting the SDK
  • Samples
  • SDK API Reference Documentation
  • Other Azure IoT SDKs
  • Developing Azure IoT Applications
  • Key Features
    • Device Client SDK
    • Provisioning Client SDK
  • OS Platforms and Hardware Compatibility
  • Porting the Azure IoT Device Client SDK for C to New Devices
  • Contribution, Feedback and Issues
  • Support
  • Read More
  • SDK Folder Structure
• Releases
  • New Features and Critical Bug Fixes
  • Long Term Support (LTS)
    • LTS Schedule
  • Release Example

Critical Upcoming Change Notice

All Azure IoT SDK users are advised to be aware of upcoming TLS certificate changes for Azure IoT Hub and Device Provisioning Servicethat will impact the SDK's ability to connect to these services. In October 2022, both services will migrate from the currentBaltimore CyberTrust CA Root to theDigiCert Global G2 CA root. There will be atransition period beforehand where your IoT devices must have both the Baltimore and Digicert public certificateswhich may be hardcoded in their application or flashed onto your WiFi module in order to prevent connectivity issues.

Devices with only the Baltimore public certificate will lose the ability to connect to Azure IoT Hub and Device Provisioning Service in October 2022.

To prepare for this change, make sure your device's TLS stack has both of these public root of trust certificates configured.

For a more in depth explanation as to why the IoT services are doing this, please seethis article.

Getting the SDK

The simplest way to get started with the Azure IoT SDKs on supported platforms is to use the following packages and libraries:

• mbed: Device SDK library on MBED
• Arduino: Device SDK library in the Arduino IDE
• Windows: Device SDK on Vcpkg
• iOS: Device SDK on CocoaPod

For other platforms - including Linux - you need to clone and build the SDK directly. You may also build it directly for the platforms above. Instructions can be found here.

Samples

There are many samples available for the SDK. More information can be found here.

SDK API Reference Documentation

The API reference documentation for the C SDKs can be found here.

Other Azure IoT SDKs

To find Azure IoT SDKs in other languages, please refer to the guidance here.

Note on constrained devices: The Embedded C SDK is an alternative for constrained devices which enables the BYO (bring your own) network approach: IoT developers have the freedom of choice to bring an MQTT client, TLS and Socket of their choice to create a device solution. Find more information about the Embedded C SDK here.

Developing Azure IoT Applications

To learn more about building Azure IoT Applications, you can visit the Azure IoT Dev Center.

Key Features

Device Client SDK

IoT Hub supports multiple protocols for the device to connect with : MQTT, AMQP, and HTTPS. MQTT and AMQP can optionally run over WebSockets. The Device Client SDK allows the protocol to be chosen at connection creation time.

If you're not sure which protocol to use, you should use MQTT or MQTT-WS. MQTT requires considerably fewer resources than AMQP and supports considerably more IoT Hub functionality than HTTPS. Neither AMQP nor HTTPS are guaranteed to have Device Client SDK implementations for new features going forward, such as Azure IoT Plug and Play.

✔️ feature available ✖️ feature planned but not supported ➖ no support planned

This SDK also contains options you can set and platform specific features. You can find detail list in this document.

Provisioning Client SDK

This repository contains provisioning client SDK for the Device Provisioning Service.

✔️ feature available ✖️ feature planned but not supported ➖ no support planned

OS Platforms and Hardware Compatibility

The IoT Hub device SDK for C can be used with a broad range of OS platforms and devices.

The minimum requirements are for the device platform to support the following:

• Support Azure IoT TLS over TCP/IP Requirements: https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-tls-support
• Support SHA-256 (optional): necessary to generate the secure token for authenticating the device with the service. Different authentication methods are available and not all require SHA-256.
• Have a Real Time Clock or implement code to connect to an NTP server: necessary for both establishing the TLS connection and generating the secure token for authentication.
• Having at least 64KB of RAM: the memory footprint of the SDK depends on the SDK and protocol used as well as the platform targeted. The smallest footprint is achieved targeting microcontrollers.

Platform support details can be found in this document.You can find an exhaustive list of the OS platforms the various SDKs have been tested against in the Azure Certified for IoT device catalog. Note that you might still be able to use the SDKs on OS and hardware platforms that are not listed on this page: all the SDKs are open sourced and designed to be portable. If you have suggestions, feedback or issues to report, refer to the Contribution and Support sections below.

Porting the Azure IoT Device Client SDK for C to New Devices

The C SDKs and Libraries:

• Are written in ANSI C (C99) and avoids compiler extensions to maximize code portability and broad platform compatibility.
• Expose a platform abstraction layer to isolate OS dependencies (threading and mutual exclusion mechanisms, communications protocol e.g. HTTP). Refer to our porting guide for more information about our abstraction layer.

In the repository you will find instructions and build tools to compile and run the device client SDK for C on Linux, Windows and microcontroller platforms (refer to the links above for more information on compiling the device client for C).

If you are considering porting the device client SDK for C to a new platform, check out the porting guide document.

Contribution, Feedback and Issues

If you encounter any bugs, have suggestions for new features or if you would like to become an active contributor to this project please follow the instructions provided in the contribution guidelines.

Support

• Have a feature request for SDKs? Please post it on User Voice to help us prioritize.
• Have a technical question? Ask on Stack Overflow with tag "azure-iot-hub".
• Need Support? Every customer with an active Azure subscription has access to support with guaranteed response time. Consider submitting a ticket and get assistance from Microsoft support team
• Found a bug? Please help us fix it by thoroughly documenting it and filing an issue on our GitHub issues.

Read More

• Azure IoT Hub documentation
• Prepare your development environment to use the Azure IoT device SDK for C
• Setup IoT Hub
• Azure IoT device SDK for C tutorial
• How to port the C libraries to other OS platforms
• Cross compilation example

SDK Folder Structure

/c-utility, /deps, /umqtt, /uamqp -

These are git submodules that contain code, such as adapters and protocol implementations, shared with other projects.

/build, /build_all

Build and checkin gate related folders.

/certs

Contains certificates needed to communicate with Azure IoT Hub.

/doc

This folder contains application development guides and device setup instructions.

/iothub_client

Contains Azure IoT Hub client components that provide the raw messaging capabilities of the library. Refer to the API documentation and samples for information on how to use it.

• build: has one subfolder for each platform (e.g. Windows, Linux, Mbed). Contains makefiles, batch files, and solutions that are used to generate the library binaries.
• devdoc: contains requirements, designs notes, manuals.
• inc: public include files.
• src: client libraries source files.
• samples: contains simple samples.
• tests: unit and end-to-end tests for source code.

/provisioning_client

This folder contains client library for device provisioning client.

/samples

Contains samples demonstrating more complex E2E scenarios using SDK.

/testtools

Contains tools that are used in testing the libraries.

/tools

Miscellaneous tools.

Deprecated Folders

The following folders are deprecated.

/iothub_service_client

Contains libraries that enable interactions with the IoT Hub service to perform operations such as sending messages to devices and managing the device identity registry.

/provisioning_service_client

Contains libraries that enable interactions with the Device Proviosining service to perform operations such as setting policy around the enrollments.

/serializer

Contains libraries that provide modeling and JSON serialization capabilities on top of the raw messaging library.

Releases

The C SDK offers releases for new features, critical bug fixes, and Long Term Support (LTS). General bug fixes will not receive a separate release, but are instead contained within the LTS release. Versioning follows semantic versioning, x.y.z. or major.minor.patch. Any time the version is updated, it will be tagged x.y.z.

New Features and Critical Bug Fixes

New features and critical bug fixes (including security updates) will be released on the main branch. These releases will be tagged using the date formatted yyyy-mm-dd. A feature release will bump the minor version and reset the patch version to 0. A critical bug fix will bump the patch version only.

Long Term Support (LTS)

New LTS releases branch off of main every six months and will be tagged LTS_<mm_yyyy>_Ref01. A new LTS release will inherit the version from the main branch at the time of the release. LTS branches are named lts_mm_yyyy for the month and year the branch was created.

An updated LTS release will occur when a critical bug fix (including security updates) is ported from the main branch. These updated releases will be tagged in the same manner except for a bumped Ref##, e.g. LTS_<mm_yyyy>_Ref02. The patch version will also be bumped. No new features and no general bug fixes will be ported to an LTS update.

LTS Schedule

Below is a table showing the mapping of the LTS branches to the packages released.

Release Example

Below is a hypothetical example of versioning and tagging for the C SDK. minor versions are distinguished by color.

• The main branch is at version 1.8.2.
• February 23, 2020: A new feature is released on main. The version bumps to 1.9.0, is tagged 1.9.0, and the release is tagged 2020-02-23.
• July 9, 2020: A new LTS release occurs. A new release branch lts_07_2020 is created, the version remains 1.9.0, and the LTS release is tagged LTS_07_2020_Ref01. The main branch bumps to 1.10.0 and is tagged 1.10.0.
• August 2, 2020: A new feature is released on main: The main branch has already been bumped for an upcoming release so the version is unchanged. The release is tagged 2020-08-02.
• September 28, 2020: A critical bug fix is released: The version on main bumps to 1.10.1, is tagged 1.10.1, and the release is tagged 2020-09-28. The critical bug fix is ported to the lts branch lts_07_2020 (and any other existing LTS branch). The lts branch version bumps to 1.9.1, is tagged 1.9.1, and the updated LTS release is tagged LTS_07_2020_Ref02. Any submodules that were part of the critical bug fix will be tagged with LTS_07_2020_Ref02.
• December 14, 2020: A new feature is released on main. The version bumps to 1.11.0, is tagged 1.11.0, and the release is tagged 2020-12-14.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Microsoft collects performance and usage information which may be used to provide and improve Microsoft products and services and enhance your experience. To learn more, review the privacy statement.