This repository contains the coreMQTT library that has been optimized for a low memory footprint. The coreMQTT library is compliant with the MQTT 3.1.1 standard. It has no dependencies on any additional libraries other than the standard C library, a customer-implemented network transport interface, and optionally a user-implemented platform time function. This library is distributed under the MIT Open Source License.
This library has gone through code quality checks including verification that no function has a GNU Complexity score over 8, and checks against deviations from mandatory rules in the MISRA coding standard. Deviations from the MISRA C:2012 guidelines are documented under MISRA Deviations. This library has also undergone both static code analysis from Coverity static analysis, and validation of memory safety and proof of functional correctness through the CBMC automated reasoning tool.
See memory requirements for this library here.
The MQTT client library exposes build configuration macros that are required for building the library.
A list of all the configurations and their default values are defined in core_mqtt_config_defaults.h.
To provide custom values for the configuration macros, a custom config file named core_mqtt_config.h
can be
provided by the application to the library.
By default, a core_mqtt_config.h
custom config is required to build the library. To disable this requirement
and build the library with default configuration values, provide MQTT_DO_NOT_USE_CUSTOM_CONFIG
as a compile time preprocessor macro.
Thus, the MQTT library can be built by either:
- Defining a
core_mqtt_config.h
file in the application, and adding it to the include directories list of the library
OR - Defining the
MQTT_DO_NOT_USE_CUSTOM_CONFIG
preprocessor macro for the library build.
The mqttFilePaths.cmake file contains the information of all source files and the header include path required to build the MQTT library.
Additionally, the MQTT library requires two header files that are not part of the ISO C90 standard library, stdbool.h
and stdint.h
. For compilers that do not provide these header files, the source/include directory contains the files stdbool.readme and stdint.readme, which can be renamed to stdbool.h
and stdint.h
, respectively, to provide the type definitions required by MQTT.
As mentioned in the previous section, either a custom config file (i.e. core_mqtt_config.h
) OR MQTT_DO_NOT_USE_CUSTOM_CONFIG
macro needs to be provided to build the MQTT library.
For a CMake example of building the MQTT library with the mqttFilePaths.cmake
file, refer to the coverity_analysis
library target in test/CMakeLists.txt file.
By default, the submodules in this repository are configured with update=none
in .gitmodules to avoid increasing clone time and disk space usage of other repositories (like amazon-freertos that submodules this repository).
To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule:
git submodule update --checkout --init --recursive test/unit-test/CMock
- For running unit tests
- C90 compiler like gcc
- CMake 3.13.0 or later
- Ruby 2.0.0 or later is additionally required for the CMock test framework (that we use).
- For running the coverage target, gcov and lcov are additionally required.
-
Go to the root directory of this repository. (Make sure that the CMock submodule is cloned as described above)
-
Run the cmake command:
cmake -S test -B build
-
Run this command to build the library and unit tests:
make -C build all
-
The generated test executables will be present in
build/bin/tests
folder. -
Run
cd build && ctest
to execute all tests and view the test run summary.
Please refer to the demos of the MQTT client library in the following locations for reference examples on POSIX and FreeRTOS platforms:
Platform | Location | Transport Interface Implementation |
---|---|---|
POSIX | AWS IoT Device SDK for Embedded C | POSIX sockets for TCP/IP and OpenSSL for TLS stack |
FreeRTOS | FreeRTOS/FreeRTOS | FreeRTOS+TCP for TCP/IP and mbedTLS for TLS stack |
FreeRTOS | FreeRTOS AWS Reference Integrations | Based on Secure Sockets Abstraction |
The Doxygen references were created using Doxygen version 1.8.20. To generate the Doxygen pages, please run the following command from the root of this repository:
doxygen docs/doxygen/config.doxyfile
See CONTRIBUTING.md for information on contributing.