Azure IoT Middleware for FreeRTOS

The Azure IoT middleware for FreeRTOS simplifies the connection of devices running FreeRTOS to Azure IoT services. It builds on top of the Azure SDK for Embedded C and adds MQTT client support. Below are key points of this project:

• The Azure IoT middleware for FreeRTOS is non allocating. That is, customers must allocate our data structures where they desire (global memory, heap, stack, etc.) and then pass the address of the allocated structure into our functions to initialize them and in order to perform various operations.
• The Azure IoT middleware for FreeRTOS operates at the MQTT level. Establishing the MQTT connection, subscribing and unsubscribing from topics, sending and receiving of messages, and disconnections are handled by the customer via middleware APIs.
• Customers control the TLS/TCP connection to the endpoint. This allows for flexibility between software or hardware implementations of either. For porting, please see the porting section below.
• No background threads are created by the Azure IoT middleware for FreeRTOS. Messages are sent and received synchronously.
• Retries with backoff are handled by the customer. FreeRTOS makes use of their own backoff and retry logic which customers are free to use (we demo this in our samples).

Table of Contents

• Azure IoT Middleware for FreeRTOS
  • Table of Contents
  • Samples
  • Docs
  • Repo Structure
  • Dependencies
  • Library Architecture
  • Code Size
  • Building
  • Using CMake
  • Using Source Files
  • Using Amazon FreeRTOS
  • Porting
  • TCP/IP and TLS
  • MQTT
  • Port Application from Azure IoT C SDK
  • Support
  • Contributing
  • Code Style
  • License
  • Trademarks

Samples

To keep this repo simple without board specific dependencies, we have a separate repo with all of the samples (please see the link here for working samples). There we have samples for several devices including:

For a video deep dive into this repo and the samples, please see the Microsoft Developers video below.

Docs

We have published doxygen-generated documentation for all of our APIs. Please see the link here to review how to use the APIs.

Azure Device Update

For details on using this library for over-the-air updates, please refer to this document: How to use the ADU Agent Client in Azure IoT Middleware for FreeRTOS.

Repo Structure

This repo is built for integration into your project. As mentioned above, if you would like to try out our samples, please clone that repo to get started. Otherwise, this repo will allow you to integrate the Azure IoT middleware for FreeRTOS into your embedded project. To see how that integration works, please see our below sections for building.

The most relevant sections of the repo are the following:

• /config_templates: Template config files to use for the library. Provided to easily bootstrap your project with the middleware.

• /libraries: Submodule dependencies for the middleware. To initialize these after cloning, you can run:

  git submodule update --init

• /ports: The source code for the MQTT abstraction (currently coreMQTT). If you would like to create your own MQTT abstraction implementation, please see the porting guide below.

• /source: All source files and headers for the middleware. To see how to build the project by using source files only, please see our below section for source file building.

• /tests: All unit and end-to-end tests used for validation.

Dependencies

We have dependencies on two libraries under the /libraries directory: Azure IoT SDK for Embedded C and coreMQTT. coreMQTT is used as a default MQTT implementation but may be swapped out by following our porting guide below.

Library Architecture

Below is a diagram showing the architecture for the middleware. Fundamentally, this middleware is build on top of the Azure SDK for Embedded C and adds MQTT functionality to abstract one layer away for simplified application building. All green boxes are taken care of by the middleware and are supported by Microsoft, while blue boxes are up to the user. Please see the porting section for details on the blue boxes.

Code Size

Total library size can depend on feature usage. Rough approximations and averages from our samples are the following with -Os and no logging:

For total binary sizes for each of our samples, please see the "Size Chart" section in each of our board specific readmes on our samples repo.

Building

Please note that this repository does not clone FreeRTOS. If using CMake, we require the user to pass build variables to point to FreeRTOS artifacts. If using other methods to build, we still require those artifacts to be available at compile time. Details are provided below for both scenarios.

Using CMake

This repository uses CMake to build. To integrate into your project, use the add_subdirectory() CMake function in your CMakeLists.txt and pass three paths as CMake options. You can set these either in the configuration step of CMake with a -D or add them as cache variables in your CMake. Please see here for an example from our samples.

• FREERTOS_DIRECTORY: Full path to a directory which contains FreeRTOS (as set up on GitHub).
• FREERTOS_PORT_DIRECTORY: The full path to the freertos port that you would like to use. On GitHub you can find the list here. Locally, if you initialize the FreeRTOS submodules, you can find the options in <FREERTOS_DIRECTORY>/FreeRTOS/Source/portable
• CONFIG_DIRECTORY: The full path which has the following files: FreeRTOSConfig.h, azure_iot_config.h, and core_mqtt_config.h.

With those options added, the following CMake target will be available to integrate into your project:

• az::iot_middleware::freertos

Using Source Files

Similar to the process of building using CMake, the library requires a few components in order to build by using only the source files (maybe in make files or some proprietary build system).

The following files are for core library functionality:

• All source files under source
• All header files under source/include
• All header files under source/interface

The following includes must be available to the library for compilation.

• FreeRTOS kernel includes
• A FreeRTOS port directory
• A path or paths to the following files: FreeRTOSConfig.h, azure_iot_config.h.

If using the coreMQTT port for the MQTT, the following needs to be included and built:

• core_mqtt_config.h
• The source/interface directory
• The port files in ports/coreMQTT
• Proper compilation and linking of the coreMQTT library

Other than these, your choice of libraries for TLS and TCP/IP are up to you to choose and properly configure/compile.

Using Amazon FreeRTOS

We have a guide here which will help you port and build your Amazon FreeRTOS project with the Azure IoT middleware for FreeRTOS.

Porting

This library, by depending on FreeRTOS, will support any board with a FreeRTOS port. FreeRTOS networking stack support is not as extensive as the OS and therefore may need to be created or adapted to work with our library. You may use available resources at the FreeRTOS Plus repo and the FreeRTOS Third Party section for integration. Please see the below sections for help with networking.

TCP/IP and TLS

The middleware for FreeRTOS operates at the MQTT level. This requires customers to supply the TLS and TCP/IP stacks for their devices. The binding between the MQTT layer and the TLS/TCP/IP is defined in the azure_iot_transport_interface.h. For an example to see how that is passed to the middleware, please see the code block linked here in our samples.

Authentication

Azure IoT supports x509 certificate and SAS key authentication. For details on which to use, you can refer to this document going over the pros and cons of each. For more details on the TLS requirements of Azure IoT (TLS versions, certificate requirements, supported crypto algorithms, etc), please see this document here. Application integration hints for both authentication mechanisms can be found in our samples: for x509 please see here and for SAS keys please see here.

MQTT

THIS FEATURE IS IN PREVIEW AND THE API IS SUBJECT TO CHANGE

The middleware uses an MQTT abstraction to allow the substitution of the MQTT library. The default implementation is the FreeRTOS built coreMQTT (see the port implementation here). If you would like to create a new MQTT abstraction implementation for an MQTT library of your choosing, please complete the interface described in this header file.

Port Application from Azure IoT C SDK

If you are looking to port your application from the Azure IoT C SDK, please see our document detailing the process here: Porting from Azure IoT C SDK.

Support

If you need support, please see our SUPPORT.md file.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Code Style

This repository uses uncrustify to enforce coding style. The config in the root (uncrustify.cfg) is the same as in the FreeRTOS repo.

Note that different versions of uncrustify can produce differently rendered files. For that reason, just as the FreeRTOS repo has declared, we use version 0.67 of uncrustify. For installation instructions for uncrustify, please see their repo here. Once you have that installed, you can make sure your contributions are rendered correctly by running our uncrustify script:

# From the repo root
./.github/scripts/code_style.sh fix

License

Azure IoT middleware for FreeRTOS is licensed under the MIT license.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.