{"id":19775042,"url":"https://github.com/freertos/coremqtt","last_synced_at":"2025-05-16T10:08:31.703Z","repository":{"id":37957883,"uuid":"290620959","full_name":"FreeRTOS/coreMQTT","owner":"FreeRTOS","description":"Client implementation of the MQTT 3.1.1 specification for embedded devices","archived":false,"fork":false,"pushed_at":"2025-05-09T21:05:05.000Z","size":5097,"stargazers_count":180,"open_issues_count":6,"forks_count":110,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-05-09T22:19:49.497Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FreeRTOS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-26T22:49:32.000Z","updated_at":"2025-05-09T21:05:10.000Z","dependencies_parsed_at":"2023-02-01T12:02:24.610Z","dependency_job_id":"8b4f4e57-f629-4733-9e49-c18e784ce66e","html_url":"https://github.com/FreeRTOS/coreMQTT","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FcoreMQTT","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FcoreMQTT/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FcoreMQTT/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FcoreMQTT/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreeRTOS","download_url":"https://codeload.github.com/FreeRTOS/coreMQTT/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509477,"owners_count":22082892,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:14:43.202Z","updated_at":"2025-05-16T10:08:26.690Z","avatar_url":"https://github.com/FreeRTOS.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# coreMQTT Client Library\n\n**[API Documentation Pages for current and previous releases of this library can be found here](https://freertos.github.io/coreMQTT/)**\n\nThis repository contains the coreMQTT library that has been optimized for a low\nmemory footprint. The coreMQTT library is compliant with the\n[MQTT 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/mqtt-v3.1.1.html)\nstandard. It has no dependencies on any additional libraries other than the\nstandard C library, a customer-implemented network transport interface, and\n_optionally_ a user-implemented platform time function. This library is\ndistributed under the [MIT Open Source License](LICENSE).\n\nThis library has gone through code quality checks including verification that no\nfunction has a\n[GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html)\nscore over 8, and checks against deviations from mandatory rules in the\n[MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA\nC:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This\nlibrary has also undergone both static code analysis from\n[Coverity static analysis](https://scan.coverity.com/), and validation of memory\nsafety through the\n[CBMC automated reasoning tool](https://www.cprover.org/cbmc/).\n\nSee memory requirements for this library\n[here](./docs/doxygen/include/size_table.md).\n\n**coreMQTT v2.3.1\n[source code](https://github.com/FreeRTOS/coreMQTT/tree/v2.3.1/source) is part\nof the\n[FreeRTOS 202406.01 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202406.01-LTS)\nrelease.**\n\n## MQTT Config File\n\nThe MQTT client library exposes build configuration macros that are required for\nbuilding the library. A list of all the configurations and their default values\nare defined in\n[core_mqtt_config_defaults.h](source/include/core_mqtt_config_defaults.h). To\nprovide custom values for the configuration macros, a custom config file named\n`core_mqtt_config.h` can be provided by the application to the library.\n\nBy default, a `core_mqtt_config.h` custom config is required to build the\nlibrary. To disable this requirement and build the library with default\nconfiguration values, provide `MQTT_DO_NOT_USE_CUSTOM_CONFIG` as a compile time\npreprocessor macro.\n\n**Thus, the MQTT library can be built by either**:\n\n- Defining a `core_mqtt_config.h` file in the application, and adding it to the\n  include directories list of the library\n  **OR**\n- Defining the `MQTT_DO_NOT_USE_CUSTOM_CONFIG` preprocessor macro for the\n  library build.\n\n## Sending metrics to AWS IoT\n\nWhen establishing a connection with AWS IoT, users can optionally report the\nOperating System, Hardware Platform and MQTT client version information of their\ndevice to AWS. This information can help AWS IoT provide faster issue resolution\nand technical support. If users want to report this information, they can send a\nspecially formatted string (see below) in the username field of the MQTT CONNECT\npacket.\n\nFormat\n\nThe format of the username string with metrics is:\n\n```\n\u003cActual_Username\u003e?SDK=\u003cOS_Name\u003e\u0026Version=\u003cOS_Version\u003e\u0026Platform=\u003cHardware_Platform\u003e\u0026MQTTLib=\u003cMQTT_Library_name\u003e@\u003cMQTT_Library_version\u003e\n```\n\nWhere\n\n- \u003cActual_Username\u003e is the actual username used for authentication, if username\n  and password are used for authentication. When username and password based\n  authentication is not used, this is an empty value.\n- \u003cOS_Name\u003e is the Operating System the application is running on (e.g.\n  FreeRTOS)\n- \u003cOS_Version\u003e is the version number of the Operating System (e.g. V10.4.3)\n- \u003cHardware_Platform\u003e is the Hardware Platform the application is running on\n  (e.g. WinSim)\n- \u003cMQTT_Library_name\u003e is the MQTT Client library being used (e.g. coreMQTT)\n- \u003cMQTT_Library_version\u003e is the version of the MQTT Client library being used\n  (e.g. 1.0.2)\n\nExample\n\n- Actual_Username = “iotuser”, OS_Name = FreeRTOS, OS_Version = V10.4.3,\n  Hardware_Platform_Name = WinSim, MQTT_Library_Name = coremqtt,\n  MQTT_Library_version = 2.3.0. If username is not used, then “iotuser” can be\n  removed.\n\n```\n/* Username string:\n * iotuser?SDK=FreeRTOS\u0026Version=v10.4.3\u0026Platform=WinSim\u0026MQTTLib=coremqtt@2.3.0\n */\n\n#define OS_NAME                   \"FreeRTOS\"\n#define OS_VERSION                \"V10.4.3\"\n#define HARDWARE_PLATFORM_NAME    \"WinSim\"\n#define MQTT_LIB                  \"coremqtt@2.3.0\"\n\n#define USERNAME_STRING           \"iotuser?SDK=\" OS_NAME \"\u0026Version=\" OS_VERSION \"\u0026Platform=\" HARDWARE_PLATFORM_NAME \"\u0026MQTTLib=\" MQTT_LIB\n#define USERNAME_STRING_LENGTH    ( ( uint16_t ) ( sizeof( USERNAME_STRING ) - 1 ) )\n\nMQTTConnectInfo_t connectInfo;\nconnectInfo.pUserName = USERNAME_STRING;\nconnectInfo.userNameLength = USERNAME_STRING_LENGTH;\nmqttStatus = MQTT_Connect( pMqttContext, \u0026connectInfo, NULL, CONNACK_RECV_TIMEOUT_MS, pSessionPresent );\n```\n\n## Upgrading to v2.0.0 and above\n\nWith coreMQTT versions \u003e=v2.0.0, there are breaking changes. Please refer to the\n[coreMQTT version \u003e=v2.0.0 Migration Guide](MigrationGuide.md).\n\n## Building the Library\n\nThe [mqttFilePaths.cmake](mqttFilePaths.cmake) file contains the information of\nall source files and the header include path required to build the MQTT library.\n\nAdditionally, the MQTT library requires two header files that are not part of\nthe ISO C90 standard library, `stdbool.h` and `stdint.h`. For compilers that do\nnot provide these header files, the [source/include](source/include) directory\ncontains the files [stdbool.readme](source/include/stdbool.readme) and\n[stdint.readme](source/include/stdint.readme), which can be renamed to\n`stdbool.h` and `stdint.h`, respectively, to provide the type definitions\nrequired by MQTT.\n\nAs mentioned in the previous section, either a custom config file (i.e.\n`core_mqtt_config.h`) OR `MQTT_DO_NOT_USE_CUSTOM_CONFIG` macro needs to be\nprovided to build the MQTT library.\n\nFor a CMake example of building the MQTT library with the `mqttFilePaths.cmake`\nfile, refer to the `coverity_analysis` library target in\n[test/CMakeLists.txt](test/CMakeLists.txt) file.\n\n## Building Unit Tests\n\n### Checkout CMock Submodule\n\nBy default, the submodules in this repository are configured with `update=none`\nin [.gitmodules](.gitmodules) to avoid increasing clone time and disk space\nusage of other repositories (like\n[amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this\nrepository).\n\nTo build unit tests, the submodule dependency of CMock is required. Use the\nfollowing command to clone the submodule:\n\n```\ngit submodule update --checkout --init --recursive test/unit-test/CMock\n```\n\n### Platform Prerequisites\n\n- Docker\n\nor the following:\n\n- For running unit tests\n  - **C90 compiler** like gcc\n  - **CMake 3.13.0 or later**\n  - **Ruby 2.0.0 or later** is additionally required for the CMock test\n    framework (that we use).\n- For running the coverage target, **gcov** and **lcov** are additionally\n  required.\n\n### Steps to build **Unit Tests**\n\n1. If using docker, launch the container:\n\n   1. `docker build -t coremqtt .`\n   1. `docker run -it -v \"$PWD\":/workspaces/coreMQTT -w /workspaces/coreMQTT coremqtt`\n\n1. Go to the root directory of this repository. (Make sure that the **CMock**\n   submodule is cloned as described [above](#checkout-cmock-submodule))\n\n1. Run the _cmake_ command:\n\n    For Linux machines:\n    ```\n    cmake -S test -B build/ \\\n              -G \"Unix Makefiles\" \\\n              -DCMAKE_BUILD_TYPE=Debug  \\\n              -DBUILD_CLONE_SUBMODULES=ON \\\n              -DUNITTEST=1 \\\n              -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Wsign-compare -Werror -DNDEBUG -DLIBRARY_LOG_LEVEL=LOG_DEBUG'\n    ```\n    For Mac machines:\n\n    ```\n    cmake -S test -B build/ \\\n              -G \"Unix Makefiles\" \\\n              -DCMAKE_BUILD_TYPE=RelWithDebInfo  \\\n              -DBUILD_CLONE_SUBMODULES=ON \\\n              -DUNITTEST=1 \\\n              -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Wsign-compare -Werror -DNDEBUG -DLIBRARY_LOG_LEVEL=LOG_DEBUG' \\\n              -DCMAKE_C_STANDARD=99\n    ```\n\n1. Run this command to build the library and unit tests: `make -C build all`.\n\n1. The generated test executables will be present in `build/bin/tests` folder.\n\n1. Run `cd build \u0026\u0026 ctest` to execute all tests and view the test run summary.\n\n1. Run `make coverage` to generate coverage report in the `build/coverage`\n   folder.\n\n## CBMC\n\nTo learn more about CBMC and proofs specifically, review the training material\n[here](https://model-checking.github.io/cbmc-training).\n\nThe `test/cbmc/proofs` directory contains CBMC proofs.\n\nIn order to run these proofs you will need to install CBMC and other tools by\nfollowing the instructions\n[here](https://model-checking.github.io/cbmc-training/installation.html).\n\n## Reference examples\n\nPlease refer to the demos of the MQTT client library in the following locations\nfor reference examples on POSIX and FreeRTOS platforms:\n\n| Platform |                                                    Location                                                    |         Transport Interface Implementation         |\n| :------: | :------------------------------------------------------------------------------------------------------------: | :------------------------------------------------: |\n|  POSIX   | [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/mqtt) | POSIX sockets for TCP/IP and OpenSSL for TLS stack |\n| FreeRTOS |             [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo)             | FreeRTOS+TCP for TCP/IP and mbedTLS for TLS stack  |\n| FreeRTOS |     [FreeRTOS AWS Reference Integrations](https://github.com/aws/amazon-freertos/tree/main/demos/coreMQTT)     |        Based on Secure Sockets Abstraction         |\n\n## Documentation\n\n### Existing Documentation\n\nFor pre-generated documentation, please see the documentation linked in the\nlocations below:\n\n|                                                       Location                                                       |\n| :------------------------------------------------------------------------------------------------------------------: |\n| [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) |\n|       [API Reference](https://freertos.github.io/coreMQTT/main/index.html)        |\n\nNote that the latest included version of coreMQTT may differ across\nrepositories.\n\n### Generating Documentation\n\nThe Doxygen references were created using Doxygen version 1.9.2. To generate the\nDoxygen pages, please run the following command from the root of this\nrepository:\n\n```shell\ndoxygen docs/doxygen/config.doxyfile\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on\ncontributing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Fcoremqtt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreertos%2Fcoremqtt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Fcoremqtt/lists"}