Azure IoT C SDK
|
This document describes how to prepare your development environment to use the Microsoft Azure IoT device SDK for C.
Be sure to include Visual C++.
git version
from a command prompt.cmake -version
from a command prompt. CMake will be used to create Visual Studio projects to build libraries and samples.Our release tag names are date values in
lts_mm_yyyy
format.
>If you are using a release before 2019-04-15 then you will need to use the --recursive
argument for git submodule
. Otherwise it is highly recommended NOT to use --recursive
as this results in poor git performance.
The sample applications can be build with the help of the C SDK libraries and headers built with vcpkg. vcpkg is a package manager that facilitates building C and C++ libraries. To install the vcpkg C SDK libraries and headers, follow these steps Setup C SDK vcpkg for Windows development environment.
Note: vcpkg manager creates a directory with all the headers and generates the C SDK .lib files on your machine. If you are using Visual Studio (from 2017) the command 'vcpkg integrate install' lets Visual Studio knows where the vcpkg headers and lib directories are located. If you're using other IDEs, just add the vcpkg directories to your compiler/linker include paths.
To quickly build one of the sample applications, open the corresponding Visual Studio solution file (.sln) in Visual Studio. For example, to build the telemetry message sample, open **iothub_client\samples\iothub_ll_telemetry_sample\windows\iothub_ll_telemetry_sample.sln**.
In the sample's main source file, find the line similar to this:
...and replace [device connection string]
with a valid device connection string for a device registered with your IoT Hub. For more information, see the samples section below.
Build the sample project.
In some cases, you may want to build the SDK locally for development and testing purposes (without using vcpkg). First, take the following steps to generate project files:
This builds x86 libraries. To build for x64 for Visual Studio 2017:
cmake .. -G "Visual Studio 15 2017 Win64"
, for Visual Studio 2019:cmake .. -G "Visual Studio 16 2019" -A x64
, or for Visual Studio 2022:cmake .. -G "Visual Studio 17 2022" -A x64
When the project generation completes successfully, you will see a Visual Studio solution file (.sln) under the cmake
folder. To build the SDK, do one of the following:
To build Debug binaries, use the corresponding MSBuild argument:
cmake --build . -- /m /p:Configuration=Debug
There are many CMake configuration options available for building the SDK. For example, you can disable one of the available protocol stacks by adding an argument to the CMake project generation command:
Also, you can build and run unit tests:
By default the C-SDK will have web sockets enabled for AMQP and MQTT. The sample **iothub_client\samples\iothub_ll_telemetry_sample** lets you specify the protocol
variable.
Unless you have a reason otherwise, we recommend you use MQTT as your protocol.
By default all samples are built to handle a variety of server root CA certificates during TLS negotiation. If you would like to decrease the size of the sample, select the appropriate root certificate option during the cmake step. Follow the instructions here.
Note: Any samples you build will not work until you configure them with a valid IoT Hub device connection string. For more information, see the samples section below.
It is possible to use OpenSSL as your TLS stack instead of the default Schannel when running on Windows, although this is highly discouraged. See this document for more.
This section describes how to set up a development environment for the C SDK on Ubuntu. CMake will create makefiles and make will use them to compile the C SDK source code using the gcc compiler.
NOTE: If you are planning to use HTTP other than with the default OpenSSL, (i.e., wolfSSL or mbedTLS), you must configure cURL before installation.
Verify that CMake is at least version 2.8.12:
Our release tag names are date values in
lts_mm_yyyy
format.
>If you are using a release before 2019-04-15 then you will need to use the --recursive
argument for git submodule
. Otherwise it is highly recommended NOT to use --recursive
as this results in poor git performance.
To build the SDK:
To build Debug binaries, add the corresponding CMake option to the project generation command above, e.g.:
There are many CMake configuration options available for building the SDK. For example, you can disable one of the available protocol stacks by adding an argument to the CMake project generation command:
Also, you can build and run unit tests:
By default the C-SDK will have web sockets enabled for AMQP and MQTT. The sample **iothub_client\samples\iothub_ll_telemetry_sample** lets you specify the protocol
variable.
Unless you have a reason otherwise, we recommend you use MQTT as your protocol.
By default all samples are built to handle a variety of server root CA certificates during TLS negotiation. If you would like to decrease the size of the sample, select the appropriate root certificate option during the cmake step. Follow the instructions here.
Note: Any samples you build will not work until you configure them with a valid IoT Hub device connection string. For more information, see the samples section below.
This section describes how to set up a development environment for the C SDK on macOS. CMake will create an XCode project containing the various SDK libraries and samples.
We've tested the device SDK for C on macOS High Sierra, with XCode version 9.2.
The minimum version of curl required is 7.56, as recent previous versions presented critical failures. To upgrade see "Upgrade CURL on Mac OS" steps below.
Our release tag names are date values in
lts_mm_yyyy
format.
>If you are using a release before 2019-04-15 then you will need to use the --recursive
argument for git submodule
. Otherwise it is highly recommended NOT to use --recursive
as this results in poor git performance.
To build Debug binaries, add the corresponding CMake option to the project generation command above, e.g.:
There are many CMake configuration options available for building the SDK. For example, you can disable one of the available protocol stacks by adding an argument to the CMake project generation command:
```Shell cmake -Duse_amqp=OFF ..
</blockquote>Also, you can build and run unit tests:<blockquote>```Shellcmake -Drun_unittests=ON ..cmake --build .ctest -C "debug" -V
By default the C-SDK will have web sockets enabled for AMQP and MQTT. The sample **iothub_client\samples\iothub_ll_telemetry_sample** lets you specify the protocol
variable.
Unless you have a reason otherwise, we recommend you use MQTT as your protocol.
By default all samples are built to handle a variety of server root CA certificates during TLS negotiation. If you would like to decrease the size of the sample, select the appropriate root certificate option during the cmake step. Follow the instructions here.
Note: Any samples you build will not work until you configure them with a valid IoT Hub device connection string. For more information, see the samples section below.
To generate the XCode project:
All of the CMake options described above will work for XCode generation as well.
When project generation completes you will see an XCode project file (.xcodeproj) under the cmake
folder. To build the SDK, open **cmake\azure_iot_sdks.xcodeproj** in XCode and use XCode's build and run features.
Note: Until Mac updates the Curl library to version to 7.58 or greater it will also be necessary to modify your XCode project file (.xcodeproj) to replace all the lines that read LIBRARY_SEARCH_PATHS = "";
with LIBRARY_SEARCH_PATHS = "/usr/local/Cellar/curl/7.58.0/lib";
The example above assumes curl 7.58 has been compiled and saved into /usr/local/Cellar/curl/7.58.0
. For more details please see section "Upgrade CURL on Mac OS".
This repository contains various C sample applications that illustrate how to use the Azure IoT device SDK for C:
Once the SDK is building successfully you can run any of the available samples using the following (example given for a linux system):
-Edit the sample file entering the proper connection string from the Azure Portal:
-Navigate to the directory of the sample that was edited, build the sample with the new changes and execute the sample: