Qualifying your board - FreeRTOS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Qualifying your board


Hardware requirements:

The MCU-based development board on which the FreeRTOS Amazon IoT libraries run must have:

  • Ethernet, Wi-Fi, or cellular connectivity capability

Software requirements:

The Porting flowchart in the FreeRTOS Porting Guide identifies the required FreeRTOS Amazon IoT libraries for any given MCU-based development board. The minimum subset is:

  • FreeRTOS kernel

  • coreMQTT

  • Amazon IoT Over-The-Air update (OTA)

Testing requirements:


For improved security, we recommend the following.

Qualification steps

Verify the FreeRTOS libraries ported using Amazon IoT Device Tester (IDT)

  1. Port the FreeRTOS libraries to your board. See the FreeRTOS Porting Guide for instructions.

  2. Create a test project, and port the required tests from FreeRTOS-Libraries-Integration-Tests GitHub repository. Call the test runner task RunQualificationTest.


    For a good developer experience, it is recommended to port the FreeRTOS libraries, and run corresponding individual test group locally using an IDE to verify the integration.

    The test runner task runs in an individual test project, or in your demo application project.

  3. Create a manifest.yml file to list all dependencies used in your qualifications. The dependencies include the FreeRTOS libraries, and test repositories. See FreeRTOS manifest file instructions for details.


    The manifest.yml is used by IDT to find the required dependencies for integrity checks against specific FreeRTOS library versions, and to configure test project to build, flash and run the test binaries.

    IDT does not mandate a specific project structure, and uses the reference path included in the manifest.yml file.

  4. Verify Amazon IoT interoperability using Device Advisor.

    1. Create a demo project that uses the same components including FreeRTOS libraries, porting, integration tasks like OTA used in the above testing.

      For qualification, the demo application must provide the following features:

      • Perform MQTT publish and subscribe to a topic.

      • Perform OTA updates.

      • Create a bootloader that supports OTA updates. Use your own bootloader or MCUBoot . See Labs-FreeRTOS-Plus-MCUBoot.


      The FreeRTOS GitHub repository has pre-configured examples demonstrating individual tasks. There is also an integrated coreMQTT Agent Demo that incorporates both coreMQTT and OTA tasks. Also, see FreeRTOS Featured IoT Integrations at Examples of qualification projects.

    2. Amazon IoT Device Tester will run your demo against Amazon IoT Device Advisor. The following Device Advisor test cases are required for qualification.

      Test cases
      Test case Test cases Required
      TLS TLS Connect Yes
      TLS TLS Support Amazon Amazon IoT Cipher Suites Yes with recommended cipher suites
      TLS TLS Unsecure Server Cert Yes
      TLS TLS Incorrect Subject Name Servr Cert Yes
      MQTT MQTT Connect Yes
      MQTT MQTT Connect Jitter Retries Yes without warnings
      MQTT MQTT Subscribe Yes
      MQTT MQTT Publish Yes
      MQTT MQTT ClientPuback Qos1 Yes
      MQTT MQTT No Ack PingResp Yes
  5. Run the tests from Amazon IoT Device Tester and generate a test report.

Prepare for submission

  1. Write a Getting Started Guide to run the MQTT or OTA demo project on your device. See Creating a getting started with FreeRTOS guide for your device for instructions.

  2. Provide threat modeling document verifying that you mitigate the risks defined in the Threat Modeling for the Amazon IoT device bootloader described in Porting the OTA library in the FreeRTOS Porting Guide. This document must be uploaded as a Supporting Asset when submitting your device in APN Partner Central.

  3. Provide a public repository for code downloads. We recommend that you provide a corporate GitHub repository link.

Qualification submission

  • IDT test report.

  • Amazon IoT Device Advisor test report.

  • Threat modeling document.

  • GitHub repository with the source code for downloads.