The ClearBlade Cloud IoT Device SDK for Embedded C is an easy-to-port, open-source library that connects low-end IoT devices to ClearBlade IoT Core.

The Device SDK supports concurrent Pub/Sub traffic on a non-blocking socket implementation that runs on POSIX, RTOS, and no-OS devices. A board support package (BSP) facilitates portability and provides platform-specific implementations through a set of functions and directories. The BSP helps implement crypto and time functions, networking, Transport Layer Security (TLS), memory management, and random number generation without working through MQTT internals.

See the user guide in the docs directory for more details.

To get the source, clone from the master branch of the ClearBlade Cloud IoT Device SDK for Embedded C GitHub repository:

git clone https://github.com/ClearBlade/iot-device-sdk-embedded-c.git --recurse-submodules

• bin: Executables and libraries produced by a build.
• doc: Documentation: Doxygen references, user guide, and porting guide.
• examples: Example source with makefiles. After you build with make, this directory will contain the example executables.
• include: The Device SDK API's header files. You must add this directory to the header include path when compiling your application against the source.
• include/bsp: The BSP's header files. Functions declared here must be defined in a device-specific BSP implementation. When compiling your BSP source, ensure this directory is on the include path.
• make: Build system configuration files.
• obj: Object files generated during a build.
• res: Resource files (for example, trusted root CA certificates).
• src: The Device SDK's source files. A BSP implementation is provided for POSIX.
• third_party: Third-party open-source components.
• tools: Scripts the repository's maintainers use.

The default build tool for the Device SDK is make. It invokes GCC to produce a POSIX host's native build, which serves as Ubuntu's default development environment.

Run the following command to build the Device SDK:

make

The source can be cross-compiled to other target platforms via custom toolchains and the makefile or with a specific device SDK’s IDE. For more information, see the porting guide.

By default, the Device SDK is built with secure connection support. It thus requires a third-party TLS implementation to link against. When executing make, the build system defaults to mbedTLS.

As a result, the make and make IOTC_BSP_TLS=mbedtls commands are synonymous.

You can also configure the make system to build a library that uses wolfSSL.

make clean
make IOTC_BSP_TLS=wolfssl

The IOTC_BSP_TLS value determines which script is run.

• mbedTLS: res/tls/build_mbedtls.sh
• wolfSSL: res/tls/build_wolfssl.sh

The mbedTLS build script includes a git clone and branch checkout of the mbedTLS source (upon confirmation of the license agreement). However, the wolfSSL build script requires you to clone the repository yourself. When you run make IOTC_BSP_TLS=wolfSSL, instructions are provided for cloning the repository.

See Security for more details on running the scripts.

To build and execute all tests:

1. Run git submodule init from the project's root directory to initialize all test dependencies.
2. Run git submodule update from the project's root directory to clone all submodules.
3. Run make tests.

By default, test execution is the final step of the tests build process. You can also execute the tests manually.

cd bin/{host_os}/tests
./iotc_utests
./iotc_gtests
./iotc_itests

Before building the examples, build the Device SDK static library and a TLS library, as described in the preceding sections. Then, complete the steps below to run the examples.

1. Create a project, registry, and device in Cloud IoT Core.
2. Create Cloud IoT Core device credentials.
3. Follow the steps in the examples README.md files to provision the device credentials and build the client applications.
4. Run make in the examples folder. The make process automatically downloads the ClearBlade Root CA PEM file to the example directories. The file enables TLS when communicating with Cloud IoT Core.

To securely connect to Cloud IoT Core, a root CA .pem file must be in the current working directory of the example executables. By default, the file is in res/trusted_RootCA_certs/roots.pem and contains two certificates that validate Cloud IoT Core credentials. The make process automatically moves this file from res/trusted_RootCA_certs/roots.pem to the correct location.

We strongly recommend performing frequent security-related firmware updates to maintain a secure connection with Cloud IoT Core.

Follow the steps below to perform the cross-compilation process.

• Extend the build system with a new cross-compilation preset in the file make/mt-config/mt-presets.mk.
• Create a set of files representing the BSP implementation you've written for your platform. Store these in the src/bsp/platform/TARGET_PLATFORM directory.
• Build a TLS BSP implementation to invoke the TLS SDK for your platform. Store these in a new directory, src/bsp/tls/TARGET_TLS_SOLUTION.
• Build a Cryptography BSP implementation to handle key signatures of JWTs on your target platform in the directory src/bsp/crypto/TARGET_CRYPTO_SOLUCTION.

For more details on the cross-compilation process, see the porting guide.

The Device SDK supports secure connection through a third-party TLS library. The Device SDK is tested against mbedTLS and wolfSSL.

This repository does not directly include TLS libraries; you can clone the TLS git repositories and place them in the third_party/tls/mbedtls and third_party/tls/wolfssl directories, respectively. Running make without any parameters will start a build that includes git checkout, build configuration, and compilation of the mbedTLS library.

The Device SDK supports other TLS libraries through the BSP TLS API. For configuring the build process to work with your preferred library, see the porting guide in doc/porting_guide.md. Additionally, check the user guide doc/user_guide.md to ensure your TLS implementation meets the security requirements to connect to Cloud IoT Core.

Nineteen combinations of compilers and feature sets are continuously built. After each build, 58 functional, 23 integration, and 199 unit tests are executed. Tests are executed against the TLS libraries mbedTLS and wolfSSL.

For information about contributing to this repository, see CONTRIBUTING.md.

Review the following documentation:

• doc/user_guide.md: User guide that covers Device SDK features and usage.
• doc/porting_guide.md: Porting guide that provides information about porting the Device SDK to target devices.

Copyright 2023 ClearBlade Inc.

Licensed under the BSD 3-Clause license.

Copyright 2018-2020 Google LLC

Licensed under the BSD 3-Clause license.

For more information, see LICENSE.md.