Amazon FreeRTOS
User Guide

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Amazon FreeRTOS MQTT Library, Version 2.0.0

Overview

You can use the Amazon FreeRTOS MQTT library to create applications that publish and subscribe to MQTT topics, as MQTT clients on a network. The Amazon FreeRTOS MQTT library implements the MQTT 3.1.1 standard for compatibility with the AWS IoT MQTT server. The library is also compatible with other MQTT servers.

The source files for the Amazon FreeRTOS MQTT library are located in <amazon-freertos>/.../mqtt. These files implement version 2.0.0 of the Amazon FreeRTOS MQTT library. Amazon FreeRTOS also includes a backward-compatibility layer for version 1.0.0 of the Amazon FreeRTOS MQTT library. For information about Amazon FreeRTOS MQTT version 1.0.0, see Amazon FreeRTOS MQTT Library, Version 1.0.0.

Dependencies and Requirements

The Amazon FreeRTOS MQTT library has the following dependencies:

The diagram below illustrates these dependencies.

Features

The Amazon FreeRTOS MQTT library has the following features:

  • By default, the library has a fully asynchronous MQTT API. You can opt to use the library synchronously with the AwsIotMqtt_Wait function.

  • The library is thread-aware and parallelizable for high throughput.

  • The library features scalable performance and footprint. Use the configuration setting to tailor the library to a system's resources.

API Reference

Amazon FreeRTOS and the AWS IoT Device SDK for Embedded C have the same MQTT v2.0.0 library APIs. For a full API reference, see MQTT (v2.0.0) C SDK API Reference.

Example Usage

For example usage of the Amazon FreeRTOS MQTT library, see MQTT demo application defined in iot_demo_mqtt.c.

The MQTT demo demonstrates the subscribe-publish workflow of MQTT. After subscribing to multiple topic filters, the application publishes bursts of data to various topic names. As each message arrives, the demo publishes an acknowledgement message back to the MQTT server.

To use the MQTT demo, you must create a thing in AWS IoT, including a certificate and policy. For more information, see AWS IoT Getting Started.

Global Demo Configuration Parameters

You must set values for the following constants in the <amazon-freertos>/demos/include/aws_clientcredential.h file:

clientcredentialMQTT_BROKER_ENDPOINT

Your AWS IoT endpoint.

clientcredentialIOT_THING_NAME

The name of your IoT thing.

clientcredentialWIFI_SSID

The SSID for your Wi-Fi network.

clientcredentialWIFI_PASSWORD

Your Wi-Fi password.

clientcredentialWIFI_SECURITY

The type of security used by your Wi-Fi network.

You must also set values for the following constants in the <amazon-freertos>/demos/include/aws_clientcredential_keys.h file:

keyCLIENT_CERTIFICATE_PEM

The certificate PEM associated with your thing.

keyCLIENT_PRIVATE_KEY_PEM

The private key PEM associated with your thing.

MQTT Demo Configuration Parameters

These configuration parameters apply to the MQTT demo.

AWS_IOT_DEMO_MQTT_PUBLISH_BURST_SIZE

The number of messages to publish in each burst.

AWS_IOT_DEMO_MQTT_PUBLISH_BURST_COUNT

The number of publish bursts in this demo.