diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..2f267165 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,6 @@ +# Changelog for coreMQTT Agent Library + +## v1.0.0 (April 2021) + +This is the first release of the coreMQTT Agent library in this repository. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index e3a2b7c2..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,59 +0,0 @@ -# Contributing Guidelines - -Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional -documentation, we greatly value feedback and contributions from our community. - -Please read through this document before submitting any issues or pull requests to ensure we have all the necessary -information to effectively respond to your bug report or contribution. - - -## Reporting Bugs/Feature Requests - -We welcome you to use the GitHub issue tracker to report bugs or suggest features. - -When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already -reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: - -* A reproducible test case or series of steps -* The version of our code being used -* Any modifications you've made relevant to the bug -* Anything unusual about your environment or deployment - - -## Contributing via Pull Requests -Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: - -1. You are working against the latest source on the *main* branch. -2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. -3. You open an issue to discuss any significant work - we would hate for your time to be wasted. - -To send us a pull request, please: - -1. Fork the repository. -2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. -3. Ensure local tests pass. -4. Commit to your fork using clear commit messages. -5. Send us a pull request, answering any default questions in the pull request interface. -6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. - -GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and -[creating a pull request](https://help.github.com/articles/creating-a-pull-request/). - - -## Finding contributions to work on -Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. - - -## Code of Conduct -This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). -For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact -opensource-codeofconduct@amazon.com with any additional questions or comments. - - -## Security issue notifications -If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. - - -## Licensing - -See the [LICENSE](LICENSE.md) file for our project's licensing. We will ask you to confirm the licensing of your contribution. diff --git a/LICENSE.md b/LICENSE similarity index 100% rename from LICENSE.md rename to LICENSE diff --git a/README.md b/README.md index f229ec8b..9e695e87 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ -## MQTT Agent - Using coreMQTT +## coreMQTT Agent Library -Note: The MQTT agent and associated example project are functional but not yet complete. Be aware the agent does not yet comply with our code quality standards and is not yet fully tested. There is a chance its APIs will change before its official first release. Feedback, suggestions and comments are welcome on the [FreeRTOS support forum](https://forums.freertos.org). +The coreMQTT Agent library is a high level API that adds thread safety to the [coreMQTT](https://github.com/FreeRTOS/coreMQTT) library. The library provides thread safe equivalents to the coreMQTT's APIs, greatly simplifying its use in multi-threaded environments. The coreMQTT Agent library manages the MQTT connection by serializing the access to the coreMQTT library and reducing implementation overhead (e.g., removing the need for the application to repeatedly call to `MQTT_ProcessLoop`). This allows your multi-threaded applications to share the same MQTT connection, and enables you to design an embedded application without having to worry about coreMQTT thread safety. -[coreMQTT](https://github.com/FreeRTOS/coreMQTT) is an MIT licensed open source C MQTT client library for microcontrollers and small microprocessor based IoT devices. It’s design is intentionally simple to ensure it has no dependency on any other library or operating system, and to better enable static analysis including [memory safety proofs](https://www.freertos.org/2020/02/ensuring-the-memory-safety-of-freertos-part-1.html). That simplicity and lack of operating system dependency (coreMQTT does not require multithreading at all) means coreMQTT does not build thread safety directly into its implementation. Instead thread safety must be provided by higher level software. This labs project implements a coreMQTT extension that provides that higher level functionality in the form of an MQTT agent (or MQTT daemon). While the implementation demonstrated here is currently specific to FreeRTOS, there are not many dependencies on FreeRTOS, meaning the implementation can easily be adapted for use with other operating systems. +This library has gone through code quality checks including verification that no function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8, and checks against deviations from mandatory rules in the [MISRA coding standard](https://www.misra.org.uk/MISRAHome/MISRAC2012/tabid/196/Default.aspx). Deviations from the MISRA C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This library has also undergone both static code analysis from [Coverity static analysis](https://scan.coverity.com/), and validation of memory safety through the [CBMC automated reasoning tool](https://www.cprover.org/cbmc/). -## Getting started -The [documentation page](https://freertos.org/mqtt/mqtt-agent-demo.html) for this repository contains information on the MQTT agent and the contained demo project. +See memory requirements for this library [here](https://freertos.org/Documentation/api-ref/coreMQTT-Agent/docs/doxygen/output/html/index.html#core_mqtt_agent_memory_requirements). ## Cloning this repository This repo uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring in dependent components. @@ -24,14 +23,82 @@ If you have downloaded the repo without using the `--recurse-submodules` argumen git submodule update --init --recursive ``` +## coreMQTT Agent Library Configurations + +The MQTT Agent library uses the same `core_mqtt_config.h` configuration file as coreMQTT, with the addition of configuration constants listed at the top of [core_mqtt_agent.h](source/include/core_mqtt_agent.h) and [core_mqtt_agent_command_functions.h](source/include/core_mqtt_agent_command_functions.h). Documentation for these configurations can be found [here](https://freertos.org/Documentation/api-ref/coreMQTT-Agent/docs/doxygen/output/html/core_mqtt_agent_config.html). + +To provide values for these configuration values, they must be either: +* Defined in `core_mqtt_config.h` used by coreMQTT +**OR** +* Passed as compile time preprocessor macros + +## Building the Library + +You can build the MQTT Agent source files that are in the [source](source/) directory, and add [source/include](source/include) to your compiler's include path. Additionally, the MQTT Agent library requires the coreMQTT library, whose files follow the same `source/` and `source/include` pattern as the agent library; its build instructions can be found [here](https://github.com/FreeRTOS/coreMQTT#building-the-library). + +If using CMake, the [mqttAgentFilePaths.cmake](mqttAgentFilePaths.cmake) file contains the above information of the source files and the header include path from this repository. The same information is found for coreMQTT from `mqttFilePaths.cmake` in the [coreMQTT submodule](source/dependency/). + +For a CMake example of building the MQTT Agent library with the `mqttAgentFilePaths.cmake` file, refer to the `coverity_analysis` library target in [test/CMakeLists.txt](test/CMakeLists.txt) file. + +## Building Unit Tests + +### Checkout CMock Submodule + +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 +``` + +### Unit Test Platform Prerequisites + +- 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. + +### Steps to build **Unit Tests** + +1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule)) + +1. Run the *cmake* command: `cmake -S test -B build` + +1. Run this command to build the library and unit tests: `make -C build all` + +1. The generated test executables will be present in `build/bin/tests` folder. + +1. Run `cd build && ctest` to execute all tests and view the test run summary. + +## Reference examples + +Please refer to the demos of the MQTT Agent library in the following locations for reference examples on FreeRTOS platforms: + +| Location | +| :-: | +| [coreMQTT Agent Demos](https://github.com/FreeRTOS/coreMQTT-Agent-Demos) | +| [FreeRTOS/FreeRTOS](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask) | + + +## Documentation + +The MQTT Agent API documentation can be found [here](https://freertos.org/Documentation/api-ref/coreMQTT-Agent/docs/doxygen/output/html/index.html). + +## Generating documentation + +The Doxygen references were created using Doxygen version 1.8.20. To generate the +Doxygen pages yourself, please run the following command from the root of this repository: + +```shell +doxygen docs/doxygen/config.doxyfile +``` + ## Getting help -You can use your Github login to get support from both the FreeRTOS community and directly from the primary FreeRTOS developers on our [active support forum](https://forums.freertos.org). The [FAQ](https://www.freertos.org/FAQ.html) provides another support resource. +You can use your Github login to get support from both the FreeRTOS community and directly from the primary FreeRTOS developers on our [active support forum](https://forums.freertos.org). You can find a list of [frequently asked questions](https://www.freertos.org/FAQ.html) here. -## Security +## Contributing -See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information. +See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. ## License -This library is licensed under the MIT License. See the [LICENSE](LICENSE.md) file. - +This library is licensed under the MIT License. See the [LICENSE](LICENSE) file.