Qualifying your board

Prerequisites

Hardware requirements:

The MCU-based development board on which the FreeRTOS AWS 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 AWS IoT libraries for any given MCU-based development board. The minimum subset is:

• FreeRTOS kernel

• coreMQTT

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

Testing requirements:

• Verify the implementation of hardware platform specific APIs required by FreeRTOS libraries against the defined tests GitHub repository using AWS IoT Device Tester for FreeRTOS. See Verify the FreeRTOS libraries ported using AWS IoT Device Tester (IDT).

• Verify the interoperability with AWS IoT Core using Device Advisor. See Step 4 of Verify the FreeRTOS libraries ported using AWS IoT Device Tester (IDT).

Recommendations

For improved security, we recommend the following.

• To prevent an offline or temporary compromise from becoming permanent, store secrets and credentials in a Hardware Root of Trust that resists physical attacks, such as a Secure Element, or a Secure Enclave.

• To mitigate the risk of network spoofing and man-in-the-middle attacks that can result in unauthorized data disclosure, use a True Random Number Generator (TRNG) for the FreeRTOS libraries that implement protocols such as DHCP, DNS, TCP/IP, and TLS. For more information, see page 50 in the Recommendation for Random Number Generation Using Deterministic Random Bit Generators (NIST SP 800-90A).

Qualification steps

Verify the FreeRTOS libraries ported using AWS 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.

   Note

   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.

   Note

   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 AWS 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.

      Note

      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. AWS IoT Device Tester will run your demo against AWS 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 AWS AWS 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 AWS IoT Device Tester and generate a test report.

   • IDT configure tests, and does a build and flash to your board automatically. To enable this, you must configure IDT to run the build and flash commands for your device in the userdata.json file. See Configure build, flash, and test settings in the IDT for FreeRTOS User Guide.

   • Provide device supported features in device.json file such as connectivity type, cryptography algorithm, key provisioning method for IDT to determine applicable tests to run. See Create a device pool in IDT for FreeRTOS in the IDT for FreeRTOS User Guide.

   • Create and configure your AWS account for IDT to create the required cloud resources. See Create and configure AWS account for IDT to create required cloud resources in the IDT for FreeRTOS User Guide.

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 AWS 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.

• AWS IoT Device Advisor test report.

• Threat modeling document.

• GitHub repository with the source code for downloads.