azure iot sdk c
LTS_08_2024
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 to Azure IoT Device Provisioning. This repo includes the source code for the libraries, setup instructions, and samples demonstrating use scenarios.
For constrained devices, where memory is measured in kilobytes and not megabytes, there are even lighter weight SDK options available. See Other Azure IoT SDKs to learn more.
All Azure IoT SDK users are advised to be aware of upcoming TLS certificate changes for Azure IoT Hub and Device Provisioning Service that will impact the SDK's ability to connect to these services. In October 2022, both services will migrate from the current Baltimore CyberTrust CA Root to the DigiCert Global G2 CA root. There will be a transition period beforehand where your IoT devices must have both the Baltimore and Digicert public certificates which 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 see this article.
Please note, for constrained device scenarios like mbed and Arduino, there are better, lighter weight SDK options available. See Other Azure IoT SDKs to learn more.
The simplest way to get started with the Azure IoT SDKs on supported platforms is to use the following packages and libraries:
Arduino: Device SDK library in the Arduino IDE
Windows: Device SDK on Vcpkg
iOS: Device SDK on CocoaPod
iOS Limitations
For a more complete iOS experience including the two missing features above, please see our sample native Swift library built on top of the Embedded C SDK.
For other platforms - including Linux - you need to clone and build the SDK directly. You may also build it directly for the platforms above.
There are many samples available for the SDK. More information can be found here.
The API reference documentation for the C SDKs can be found here.
To find Azure IoT SDKs in other languages, please refer to the guidance here.
To learn more about building Azure IoT Applications, you can visit the Azure IoT Dev Center.
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.
The Device/Module Client SDK optionally allows creation of IoT Plug and Play devices.
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
| Features | mqtt | mqtt-ws | amqp | amqp-ws | https | Description |
|---|---|---|---|---|---|---|
| Authentication | ✔️ | ✔️* | ✔️ | ✔️* | ✔️* | Connect your device to IoT Hub securely with supported authentication, including private key, SASToken, X-509 Self Signed and Certificate Authority (CA) Signed. *IoT Hub only supports X-509 CA Signed over AMQP and MQTT at the moment. |
| Send Device-to-Cloud Message | ✔️* | ✔️* | ✔️* | ✔️* | ✔️* | Send device-to-cloud messages (max 256KB) to IoT Hub with the option to add custom properties. IoT Hub only supports batch send over AMQP and HTTPS only at the moment. This SDK supports batch send over HTTP. * Batch send over AMQP and AMQP-WS, and add system properties on D2C messages are in progress. |
| Receive Cloud-to-Device Messages | ✔️* | ✔️* | ✔️ | ✔️ | ✔️ | Receive cloud-to-device messages and read associated custom and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages. *IoT Hub supports the option to complete/reject/abandon C2D messages over HTTPS and AMQP only at the moment. |
| Device Twins | ✔️* | ✔️* | ✔️* | ✔️* | ➖ | IoT Hub persists a device twin for each device that you connect to IoT Hub. The device can perform operations like get twin tags, subscribe to desired properties. *Send reported properties version and desired properties version are in progress. |
| Direct Methods | ✔️ | ✔️ | ✔️ | ✔️ | ➖ | IoT Hub gives you the ability to invoke direct methods on devices from the cloud. The SDK supports handler for method specific and generic operation. |
| Upload File to Blob | ➖ | ➖ | ➖ | ➖ | ✔️ | A device can initiate a file upload and notifies IoT Hub when the upload is complete. File upload requires HTTPS connection, but can be initiated from client using any protocol for other operations. |
| Connection Status and Error reporting | ✔️* | ✔️* | ✔️* | ✔️* | ✖️ | Error reporting for IoT Hub supported error code. *This SDK supports error reporting on authentication and Device Not Found. |
| Retry policies | ✔️* | ✔️* | ✔️* | ✔️* | ✖️ | Retry policy for unsuccessful device-to-cloud messages have two options: no try, exponential backoff with jitter (default). *Custom retry policy is in progress. |
| Devices multiplexing over single connection | ➖ | ➖ | ✔️ | ✔️ | ✔️ | There are more limitations to multiplexing than captured in this table. See this document for more information. |
| Connection Pooling - Specifying number of connections | ➖ | ➖ | ✖️ | ✖️ | ✖️ | |
| Azure IoT Plug and Play Support | ✔️ | ✔️ | ➖ | ➖ | ➖ | Ability to build Azure IoT Plug and Play devices. |
This SDK also contains options you can set and platform specific features. You can find detail list in this document.
This repository contains provisioning client SDK for the Device Provisioning Service.
✔️ feature available ✖️ feature planned but not supported ➖ no support planned
| Features | mqtt | mqtt-ws | amqp | amqp-ws | https | Description |
|---|---|---|---|---|---|---|
| TPM Individual Enrollment | ➖ | ➖ | We are announcing the deprecation of the utpm-c library support and DPS-TPM authentication support within the Azure IoT C-SDK. Starting May 2023, Microsoft will not provide support for this library. Existing applications using this library will continue to work as-is. We strongly recommend switching to DPS-X509 authentication using the tpm2tss OpenSSL Engine. Connecting your device to the Device Provisioning Service via individual enrollment using Trusted Platform Module will continue to work as-is. This quickstart reviews how to create a simulated device for individual enrollment with TPM. TPM over MQTT is currently not supported by the Device Provisioning Service. |
|||
| X.509 Individual Enrollment | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | This SDK supports connecting your device to the Device Provisioning Service via individual enrollment using X.509 leaf certificate. This quickstart reviews how to create a simulated device for individual enrollment with X.509. |
| X.509 Enrollment Group | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | This SDK supports connecting your device to the Device Provisioning Service via enrollment group using X.509 root certificate. |
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:
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.
The C SDKs and Libraries:
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.
MBED OS
See also Deprecated Folders below for other relevant notes.
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.
/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.
/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.
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.
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 (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.
New LTS releases branch off of main and will be tagged LTS_. 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_. The patch version will also be bumped. No new features and no general bug fixes will be ported to an LTS update.
Below is a table showing the mapping of the LTS branches to the packages released.
| Package | GitHub Branch | LTS Tag | LTS Start Date | Maintenance End Date |
|---|---|---|---|---|
| vcpkg: 2024-08-12 | lts_08_2024 | LTS_08_2024 | 2024-08-12 | 2025-08-12 |
| vcpkg: 2024-03-04 | lts_03_2024 | LTS_03_2024 | 2024-03-04 | 2025-03-04 |
'Maintenance End Date' refers to the end of life support of the related version.
Below is a hypothetical example of versioning and tagging for the C SDK. minor versions are distinguished by color.
1.9.0, and the release is tagged 2020-02-23.LTS_07_2020. The main branch bumps to 1.10.0 and is tagged 1.10.0.2020-08-02.1.10.1, and the release is tagged 2020-09-28. The critical bug fix is ported to the lts release LTS_07_2020 (and any other existing LTS branch) by creating a branch with name lts_07_2020_ref02, its version bumps to 1.9.1 and is tagged 1.9.1 and LTS_07_2020_Ref02. Any submodules that were part of the critical bug fix will be tagged with LTS_07_2020_Ref02.1.11.0, and the release is tagged as 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 [email protected] 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.
