Quality RTOS & Embedded Software

LIBRARIES
NOTE: The MQTT library and documentation are part of the FreeRTOS LTS Roadmap – the library will be released into the main FreeRTOS download with long term support (LTS) when the refactoring described on the FreeRTOS LTS Roadmap page is complete. This page presents the work-in-progress output of that work for the MQTT library, which has the LTS rc 1 tag.

MQTT LTS Release Candidate 1 Library

Introduction

The MQTT (Message Queue Telemetry Transport) library provides a lightweight publish/subscribe (or PubSub) messaging protocol that runs on top of TCP/IP and is often used in Machine to Machine (M2M) and Internet of Things (IoT) use cases.

The MQTT LTS Release Candidate 1 (MQTT LTS rc1) library implements the complete specification of the MQTT 3.1.1 protocol standard. The refactored design embraces different use-cases, ranging from resource-constrained platforms using only QoS 0 MQTT PUBLISH messages to, resource-rich platforms using QoS 2 MQTT PUBLISH over TLS connections.

Updates to the MQTT library since the previous LTS Snapshot release include:

  • Complete implementation of the MQTT 3.1.1 standard. The prior version did not support QoS 2 operations or the “session present” flag in MQTT CONNACK messages.
  • No dependencies on additional libraries other than the standard C library and a customer-implemented network transport interface.
  • No platform dependencies, such as threading or synchronization.
  • Closer compliance with the code quality criteria.
  • Smaller memory footprint.
  • Both managed and low level interfaces (see the provided demos, more comprehensive demos will follow).

The MQTT library is decoupled from the underlying network drivers through the provision of a simple send and receive transport interface specification. The application writer can select an existing or otherwise implement a transport interface appropriate for their application. It is recommended to use a secure transport interface in IoT applications, such as one that that uses the TLS protocol.

 

Code Size of MQTT LTS rc1(example generated with GCC for ARM Cortex-M)
FileWith -O1 OptimisationWith -Os Optimisation
mqtt.c3.3K2.9K
mqtt_state.c2.1K1.6K
mqtt_lightweight.c3.5K2.9K
Total estimate (configurations defined here)8.9K7.4K


Transport Interface

The MQTT library requires the application developer to select (or otherwise provide) a transport interface. The transport interface must provide a send and receive functions that have the following prototypes:

/** * @brief Transport interface for receiving data on the network. * * @param[in] pNetworkContext Implementation-defined network context. For * example, this could be a connected socket or TLS context. * @param[in] pBuffer Buffer to receive the data into. * @param[in] bytesToRecv Number of bytes requested from the network. * * @return The number of bytes received or a negative error code. */ int32_t receive_function( NetworkContext_t * pNetworkContext, void * pBuffer, size_t bytesToRecv ); /** * @brief Transport interface for sending data over the network. * * @param[in] pNetworkContext Implementation-defined network context. For * example, this could be a connected socket or TLS context. * @param[in] pBuffer Buffer containing the bytes to send over the network stack. * @param[in] bytesToSend Number of bytes to send over the network. * * @return The number of bytes sent or a negative error code. */ int32_t send_function( NetworkContext_t * pNetworkContext, const void * pBuffer, size_t bytesToSend );


Example Transport Interface
Using FreeRTOS+TCP without TLS

The following code snippet implements a suitable transport interface for the FreeRTOS+TCP TCP/IP stack without using TLS (Note: Production IoT devices should use encrypted and mutually authenticated communications, such as TLS).

/* It is left to the application writer to define the NetworkContext_t structure. In these examples it is assumed the NetworkContext_t structure contains a member called tcpSocket that has already been created and connected FreeRTOS+TCP socket. */ /* A network receive function that complies with the network interface specification. */ int32_t Transport_FreeRTOS_recv( NetworkContext_t * pNetworkContext, void * pBuffer, size_t bytesToRecv ) { int32_t socketStatus = 0; socketStatus = FreeRTOS_recv( pNetworkContext->tcpSocket, pBuffer, bytesToRecv, 0 ); return socketStatus; } /* A network receive function that complies with the network interface specification. */ int32_t Transport_FreeRTOS_send( NetworkContext_t * pNetworkContext, const void * pBuffer, size_t bytesToSend ) { int32_t socketStatus = 0; socketStatus = FreeRTOS_send( pNetworkContext->tcpSocket, pBuffer, bytesToSend, 0 ); return socketStatus; }
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.