C SDK and Embedded C SDK usage scenarios
Microsoft provides Azure IoT device SDKs and middleware for embedded and constrained device scenarios. This article helps device developers decide which one to use for your application.
The following diagram shows four common scenarios in which customers connect devices to Azure IoT, using a C-based (C99) SDK. The rest of this article provides more details on each scenario.
Scenario 1 – Azure IoT C SDK (for Linux and Windows)
Starting in 2015, Azure IoT C SDK was the first Azure SDK created to connect devices to IoT services. It's a stable platform that was built to provide the following capabilities for connecting devices to Azure IoT:
- IoT Hub services
- Device Provisioning Service clients
- Three choices of communication transport (MQTT, AMQP and HTTP), which are created and maintained by Microsoft
- Multiple choices of common TLS stacks (OpenSSL, Schannel and Bed TLS according to the target platform)
- TCP sockets (Win32, Berkeley or Mbed)
Providing communication transport, TLS and socket abstraction has a performance cost. Many paths require malloc and memcpy calls between the various abstraction layers. This performance cost is small compared to a desktop or a Raspberry Pi device. Yet on a truly constrained device, the cost becomes significant overhead with the possibility of memory fragmentation. The communication transport layer also requires a doWork function to be called at least every 100 milliseconds. These frequent calls make it harder to optimize the SDK for battery powered devices. The existence of multiple abstraction layers also makes it hard for customers to use or change to any given library.
Scenario 1 is recommended for Windows or Linux devices, which normally are less sensitive to memory usage or power consumption. However, Windows and Linux-based devices can also use the Embedded C SDK as shown in Scenario 2. Other options for windows and Linux-based devices include the other Azure IoT device SDKs: Java SDK, .NET SDK, Node SDK and Python SDK.
Scenario 2 – Embedded C SDK (for Bare Metal scenarios and micro-controllers)
In 2020, Microsoft released the Azure SDK for Embedded C (also known as the Embedded C SDK). This SDK was built based on customers feedback and a growing need to support constrained micro-controller devices. Typically, constrained micro-controllers have reduced memory and processing power.
The Embedded C SDK has the following key characteristics:
- No dynamic memory allocation. Customers must allocate data structures where they desire such as in global memory, a heap, or a stack. Then they must pass the address of the allocated structure into SDK functions to initialize and perform various operations.
- MQTT only. MQTT-only usage is ideal for constrained devices because it's an efficient, lightweight network protocol. Currently only MQTT v3.1.1 is supported.
- Bring your own network stack. The Embedded C SDK performs no I/O operations. This approach allows customers to select the MQTT, TLS and Socket clients that have the best fit to their target platform.
- Similar feature set as the C SDK. The Embedded C SDK provides similar features as the Azure IoT C SDK, with the following exceptions that the Embedded C SDK doesn't provide:
- Upload to blob
- The ability to run as an IoT Edge module
- AMQP-based features like content message batching and device multiplexing
- Smaller overall footprint. The Embedded C SDK, as see in a sample that shows how to connect to IoT Hub, can take as little as 74 KB of ROM and 8.26 KB of RAM.
The Embedded C SDK supports micro-controllers with no operating system, micro-controllers with a real-time operating system (like Eclipse ThreadX), Linux, and Windows. Customers can implement custom platform layers to use the SDK on custom devices. The SDK also provides some platform layers such as Arduino, and Swift. Microsoft encourages the community to submit other platform layers to increase the out-of-the-box supported platforms. Wind River VxWorks is an example of a platform layer submitted by the community.
The Embedded C SDK adds some programming benefits because of its flexibility compared to the Azure IoT C SDK. In particular, applications that use constrained devices will benefit from enormous resource savings and greater programmatic control. In comparison, if you use Eclipse ThreadX or FreeRTOS, you can have these same benefits along with other features per RTOS implementation.
Scenario 3 – Eclipse ThreadX with Azure IoT middleware (for Eclipse ThreadX-based projects)
Scenario 3 involves using Eclipse ThreadX and the Azure IoT middleware. Eclipse ThreadX is built on top of the Embedded C SDK, and adds MQTT and TLS Support. The middleware for Eclipse ThreadX exposes APIs for the application that are similar to the native Eclipse ThreadX APIs. This approach makes it simpler for developers to use the APIs and connect their Eclipse ThreadX-based devices to Azure IoT. Eclipse ThreadX is a fully integrated, efficient, real time embedded platform, that provides all the networking and IoT features you need for your solution.
Samples for several popular developer kits from ST, NXP, Renesas, and Microchip, are available. These samples work with Azure IoT Hub or Azure IoT Central, and are available as IAR Workbench or semiconductor IDE projects on GitHub.
Because it's based on the Embedded C SDK, the Azure IoT middleware for Eclipse ThreadX is non-memory allocating. Customers must allocate SDK data structures in global memory, or a heap, or a stack. After customers allocate a data structure, they must pass the address of the structure into the SDK functions to initialize and perform various operations.
Scenario 4 – FreeRTOS with FreeRTOS middleware (for use with FreeRTOS-based projects)
Scenario 4 brings the embedded C middleware to FreeRTOS. The embedded C middleware is built on top of the Embedded C SDK and adds MQTT support via the open source coreMQTT library. This middleware for FreeRTOS operates at the MQTT level. It establishes the MQTT connection, subscribes and unsubscribes from topics, and sends and receives messages. Disconnections are handled by the customer via middleware APIs.
Customers control the TLS/TCP configuration and connection to the endpoint. This approach allows for flexibility between software or hardware implementations of either stack. No background tasks are created by the Azure IoT middleware for FreeRTOS. Messages are sent and received synchronously.
The core implementation is provided in this GitHub repository. Samples for several popular developer kits are available, including the NXP1060, STM32, and ESP32. The samples work with Azure IoT Hub, Azure IoT Central, and Azure Device Provisioning Service, and are available in this GitHub repository.
Because it's based on the Azure Embedded C SDK, the Azure IoT middleware for FreeRTOS is also non-memory allocating. Customers must allocate SDK data structures in global memory, or a heap, or a stack. After customers allocate a data structure, they must pass the address of the allocated structures into the SDK functions to initialize and perform various operations.
C-based SDK technical usage scenarios
The following diagram summarizes technical options for each SDK usage scenario described in this article.
C-based SDK comparison by memory and protocols
The following table compares the four device SDK development scenarios based on memory and protocol usage.
| Memory allocation |
Memory usage |
Protocols supported |
Recommended for | |
|---|---|---|---|---|
| Azure IoT C SDK | Mostly Dynamic | Unrestricted. Can span to 1 MB or more in RAM. |
AMQP HTTP MQTT v3.1.1 |
Microprocessor-based systems Microsoft Windows Linux Apple OS X |
| Azure SDK for Embedded C | Static only | Restricted by amount of data application allocates. |
MQTT v3.1.1 | Micro-controllers Bare-metal Implementations RTOS-based implementations |
| Azure IoT Middleware for Eclipse ThreadX | Static only | Restricted | MQTT v3.1.1 | Micro-controllers RTOS-based implementations |
| Azure IoT Middleware for FreeRTOS | Static only | Restricted | MQTT v3.1.1 | Micro-controllers RTOS-based implementations |
Azure IoT Features Supported by each SDK
The following table compares the four device SDK development scenarios based on support for Azure IoT features.
| Azure IoT C SDK | Azure SDK for Embedded C |
Azure IoT middleware for Eclipse ThreadX |
Azure IoT middleware for FreeRTOS |
|
|---|---|---|---|---|
| SAS Client Authentication | Yes | Yes | Yes | Yes |
| x509 Client Authentication | Yes | Yes | Yes | Yes |
| Device Provisioning | Yes | Yes | Yes | Yes |
| Telemetry | Yes | Yes | Yes | Yes |
| Cloud-to-Device Messages | Yes | Yes | Yes | Yes |
| Direct Methods | Yes | Yes | Yes | Yes |
| Device Twin | Yes | Yes | Yes | Yes |
| IoT Plug-And-Play | Yes | Yes | Yes | Yes |
| Telemetry batching (AMQP, HTTP) |
Yes | No | No | No |
| Uploads to Azure Blob | Yes | No | No | No |
| Automatic integration in IoT Edge hosted containers |
Yes | No | No | No |
Next steps
To learn more about device development and the available SDKs for Azure IoT, see the following table.