iotc-c-lib

iotc-c-lib is a library which abstracts /IOTCONNECT MQTT protocol messages, device configuration and the Discovery/Identity HTTP protocol

Use the main branch for protocol 2.1 devices.

Use the rel-protocol-1.0 branch for protocol 1.0 devices.

This library not an SDK. Each target platform/os generally has its own MQTT and HTTP implementation, so the library does not have direct dependencies on any specific one.

The library provides mechanisms for parsing JSON notifications from the cloud (c2d) and composing JSON telemetry and acknowledgement messages. The general use case would require os/platform specific HTTP and MQTT implementation to be handled by the user code, where the library would only provide mechanisms for interpreting or composing the JSON that needs to be received or sent with underlying specific protocols.

Dependencies

• cJSON library v1.7.13 or greater - v1.7.19 is included as submodule at lib/cJSON.
• A dynamic memory management facility. For example malloc, FreeRTOS heap or ThreadX memory pools.
• CMake 3.22 or greater, if using CMake to build.

Licensing

This library is distributed under the MIT License.

Protocol Features

• Composing Telemetry messages.
• Parsing C2D OTA messages and providing download details.
• Parsing C2D Command messages.
• Composing OTA and command acknowledgements.
• Parsing HTTP discovery and identity Composing Telemetry messages.
• Device Config JSON parsing - iotcDeviceConfig.json at the device Info page.
• Device Identity information for Video Streaming and Telemetry Files (partial) support.
• Parsing Temporary AWS credentials for the Video Streaming and Telemetry Files features.

General Features

• Easy to use message parsing and composition.
• Customizable dynamic memory allocation for the library and the cJSON dependency.
• /IOTCONNECT topic name generation for AWS embedded devices which do not have HTTP clients or not enough resources to implement HTTPS protocol or the discovery mechanism.
• Customizable error reporting.
  • Reduces the amount of error handling required by the client application or SDK.
  • Provides an option to completely remove logging and save on const strings RAM/ROM footprint.
  • Logging with optional error handling hooks, to potentially reset or halt the device.
• Optional telemetry timestamp reporting for devices which have access to SNTP or battery backed clock.

Library Integration and Examples

Before using the library, one should read the header comments at iotcl.h to get familiar with the library concepts, goals, features and configuration.

For a quick-start, follow the links to examples to learn how to use the library:

• Sending Telemetry
• Receiving command and OTA messages and sending acknowledgements
• Using Discovery/Identity REST API to configure your MQTT connections.

Reference Implementations:

• /IOTCONNECT MTB SDK Implementation for Infineon ModusToolbox using iotc-c-lib as a a git submodule and directly added to sources.
• Microchip AVR Arduino SDK - A low level hack example where c-lib files are dropped directly into the Arduino project.
• /IOTCONNECT GreenGrass C SDK AWS GreenGrass SDK and Component examples. This project uses the CMakeLists.txt in the root of the library.
• /IOTCONNECT Generic C SDK - Paho OpenSSL implementation for Windows/Linux/MacOS and similar operating systems. This project is the best way for users to get familiar with the library and test it on their machines. However, the SDK has not been updated in a while and does not use the latest version of the library or the top level CMakeLists.txt.

If you need to generate your own certificates for device testing:

• Self-signed certificates with OpenSSL.
• CA-signed certificates with OpenSSL.

Also note that server CA certificates in C string PEM format are also available in library the sources at iotcl_certs.h

See unit test examples for working samples that can compile and run with CMake and a PC compiler.

Building and Testing

Clone this repository. Either ensure to pass --recursive flag to the git clone command or update after cloning with:

git submodule update --init --recursive

Build the library and the tests with:

cmake -B build -D CMAKE_BUILD_TYPE=Debug # this will build the library and the tests in debug mode
make -C build -j$(nproc) # If not using Git Bash on windows, set the -j flag accordingly or omit it
build/bin/test_telemetry # Run the telemetry test binary

Integrating The Library Into Your Project

Before continuing, review iotcl_example_config.h and make sure that default logging configuration will meet your needs.

If needed, create your own configuration file, add it to the include path and pass it to the compiler with add_definitions(-DIOTCL_USER_CONFIG_FILE="iotcl_config.h") or -DIOTCL_USER_CONFIG_FILE="iotcl_config.h" if not using CMake.

Library Integration For CMake Projects

If your application is built with CMake, adding this section to your CMakeLists.txt should suffice for most projects:

add_subdirectory(lib/iotc-c-lib) # or your own submodule path to the library
target_link_libraries(your-cmake-project PUBLIC iotc-c-lib)

Please review the CMake options in CMakeLists.txt to ensure that the default options satisfy the needs for your project.

Custom Project Library Integration

If you are integrating the library into your own project, here are some general notes that may help your integration, if you are using a non-CMake build system:

• Provide the required version of the cJSON library in your build or use the submodule in the lib directory.
• Add relevant sources and include directories to your project. Typically, this will be the core directory and the modules/device-rest-api directory if your device can do HTTPS requests.
• Follow examples in this document and examples in the tests/unit/ directory to learn how to initialize and use the components in your project.
• Review iotcl_example_config.h to make sure that default logging configuration will meet your needs. If needed, create your own configuration file, add it to the include path and pass it to the compiler with -DIOTCL_USER_CONFIG_FILE="iotcl_config.h" with the quotes in the actual define. Please note that if you are building the iotc-c-lib as a shared or static library, you should make sure that the library is built with the same configuration as your project. See CMakeLists.txt for more details.
• If you have SNTP, battery backed clock, network time from the mobile network or similar, consider providing a time function to timestamp messages. You can skip this option even if you have the needed facilities in order to save on network bandwidth and let the server timestamp messages as they arrive. Note that in this case, timestamping is not available, so you should not be sending "bulk" telemetry messages with iotcl_telemetry_add_new_data_set().
• Read the instructions in iotcl.h and relevant function to learn how properly configure the library to fit your needs best.

Development and Contribution

Please read the CONTRIBUTING.md before contributing to the project.

We recommend using VSCode on Linux for making modifications to the library.

We recommend using PyCharm's Git integration for Git work as it gives the user more visibility into the changes being made and better control over what ought to be committed.

• Install VSCode along with C/C++, clangd, C/C++ DevTools and CMake Tools (from Microsoft) extensions.

Note

Later, when launching VSCode, if asked to disable C/C++ extension's default IntelliSense engine, select an option to Disable C/C++ extension Intellisense and use clangd instead for better code analysis and navigation.

• Make sure you have CMake and a C compiler toolchain installed on your system. On Linux:

sudo apt update
sudo apt install build-essential cmake

• Clone this repository and open it with Open Folder in VSCode.
• Validate that you can build the tests with the instructions in the Building and Testing section above.
• Configure the CMake project with CMake Tools extension:
  • Open the Command Palette (Ctrl+Shift+P) and run CMake: Select a Kit.
  • Choose the compiler you want to use (It will be GCC if you followed the steps above). "Scan for Kit" option does not seem to work reliably.
• On the left panel click the CMake button.
• In Project Outline, select a test target under iotc-c-lib, right click and select Build.
• In order to debug a test, ensure that a debugger (apt install gdb on Ubuntu). You can right lick a specific test in Project Outline and Set as Debug/Launch Target. Clicking the Debug or Run icon at the bottom toolbar will do the appropriate action. You may need to restart the IDE after selecting a kit or after building for this to be properly detected.
• You can set breakpoints in the code and debug the tests to step through the library code.
• If adding a new feature, please make sure to add at least a positive flow test for it in the tests/unit/ directory.