Amazon FreeRTOS
Porting Guide

Configuring the MQTT Library for Testing

Devices on the edge can use the MQTT protocol to communicate with the AWS Cloud. AWS IoT hosts an MQTT broker that sends and receives messages to and from connected devices at the edge.

The MQTT library implements the MQTT protocol for devices running Amazon FreeRTOS. The MQTT library does not need to be ported, but your device's test project must pass all MQTT tests for qualification. For more information, see Amazon FreeRTOS MQTT Library in the Amazon FreeRTOS User Guide.

Prerequisites

To set up the Amazon FreeRTOS MQTT library tests, you need the following:

  • A port of the TLS library.

    For information about porting the TLS library to your platform, see Porting the TLS Library.

If you are using an IDE to build test projects, you need to set up your library port in the IDE project.

Setting Up the IDE Test Project

To set up the MQTT library in the IDE project

  • Add all of the test source files in <amazon-freertos>/libraries/c_sdk/standard/mqtt and its subdirectories to the aws_tests IDE project.

Configuring the CMakeLists.txt File

If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file.

To define a library's portable layer target in CMakeLists.txt, follow the instructions in Amazon FreeRTOS Portable Layers.

The CMakeLists.txt template list file under <amazon-freertos>/vendors/<vendor>/boards/<board>/CMakeLists.txt includes example portable layer target definitions. You can uncomment the definition for the library that you are porting, and modify it to fit your platform.

Setting Up Your Local Testing Environment

After you set up the library in the IDE project, you need to configure some other files for testing.

To configure the source and header files for the MQTT tests

  • To enable the MQTT tests, open <amazon-freertos>/vendors/<vendor>/boards/<board>/aws_tests/config_files/aws_test_runner_config.h, and set the testrunnerFULL_MQTTv4_ENABLED macro to 1.

Running the Tests

To execute the MQTT tests

  1. Build the test project, and then flash it to your device for execution.

  2. Check the test results in the UART console. If all tests pass, then testing is complete.

Validation

To officially qualify a device for Amazon FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for Amazon FreeRTOS in the Amazon FreeRTOS User Guide to set up Device Tester for port validation. To test a specific library's port, the correct test group must be enabled in the device.json file in the Device Tester configs folder.

After you finish setting up the Amazon FreeRTOS MQTT library for your device, you can start porting the OTA agent library. See Porting the OTA Library for instructions.

If your device does not support OTA functionality, you can start porting the Bluetooth Low Energy library. See Porting the Bluetooth Low Energy Library for instructions.

If your device does not support OTA and Bluetooth Low Energy functionality, then you are finished porting and can start the Amazon FreeRTOS qualification process. See the Amazon FreeRTOS Qualification Guide for more information.