# 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](https://docs.aws.amazon.com/freertos/latest/portingguide/porting-chart.html) 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](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) GitHub repository using AWS IoT Device Tester for FreeRTOS. See [Verify the FreeRTOS libraries ported using AWS IoT Device Tester (IDT)](#qualifying-your-device-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)](#qualifying-your-device-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](https://wikipedia.org/wiki/Secure_element), or a Secure Enclave.
+ To mitigate the risk of network [spoofing](https://wikipedia.org/wiki/Spoofing_attack) and [man-in-the-middle](https://wikipedia.org/wiki/Man-in-the-middle_attack) attacks that can result in unauthorized data disclosure, use a [True Random Number Generator (TRNG)](https://wikipedia.org/wiki/Hardware_random_number_generator) 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](https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final) (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](https://docs.aws.amazon.com/freertos/latest/portingguide/) for instructions.
1. Create a test project, and port the required tests from [FreeRTOS-Libraries-Integration-Tests](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) GitHub repository. Call the test runner task [ RunQualificationTest](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/blob/a8cafefc714cdbb4ee1d0f97c92e9c4cc75059fd/src/qualification_test.c#L52).
**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.
1. 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](afq-checklist-manifest-instr.md) 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.
1. 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](https://freertos.org/mcuboot/) . See [Labs-FreeRTOS-Plus-MCUBoot](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-MCUBoot).
**Note**
The [FreeRTOS GitHub](https://github.com/FreeRTOS/FreeRTOS) repository has pre-configured examples demonstrating individual tasks. There is also an integrated [coreMQTT Agent Demo](https://github.com/FreeRTOS/coreMQTT-Agent-Demos) that incorporates both coreMQTT and OTA tasks. Also, see FreeRTOS Featured IoT Integrations at [Examples of qualification projects](examples-qualification.md).
1. AWS IoT Device Tester will run your demo against [AWS IoT Device Advisor](https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html). The following Device Advisor test cases are required for qualification.
**Test cases**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/freertos/latest/qualificationguide/freertos-qualification.html)
1. 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](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-dt-ud) in the [IDT for FreeRTOS User Guide](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html).
+ 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](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-dt-dp) in the [IDT for FreeRTOS User Guide](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html).
+ 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](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-aws-afr) in the [IDT for FreeRTOS User Guide](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html).
### 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](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-gsg.html) for instructions.
1. Provide threat modeling document verifying that you mitigate the risks defined in the [ Threat Modeling for the AWS IoT device bootloader](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html#afr-bootloader) described in [Porting the OTA library](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html) in the *FreeRTOS Porting Guide*. This document must be uploaded as a Supporting Asset when submitting your device in [APN Partner Central](https://partnercentral.awspartner.com).
1. 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.
# Creating a Getting Started with FreeRTOS guide for your board
To qualify for FreeRTOS, you must create a Getting Started with FreeRTOS guide for your board. This guide walks users through setting up the hardware and development environment for developing applications for FreeRTOS devices, and building, running, and flashing the created demo application on a device.
This guide must be available to customers from a public website. The URL to the guide is a requirement for listing a qualified board in the AWS Partner Device Catalog.
Your guide must include the following instructions:
+ Setting up the device hardware.
+ Setting up the development environment.
+ Building and running the demo project.
+ Debugging.
+ Troubleshooting.
We also recommend that your guide includes:
+ A link to the MCU datasheet.
+ A Printed Circuit Board (PCB) schematic.
+ A default image boot up console log.
**Important**
Where instructions differ by operating system, you must provide instructions for Windows, Linux, and macOS operating systems.
Follow the [Getting started guide template](getting_started_template.md) while writing the guide for your board. You can find examples of published guides for other qualified boards in the [FreeRTOS User Guide](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html). A template for a Getting Started Guide is available at [ APN Partner Central](https://partnercentral.awspartner.com/).
# Getting started guide template
Write an overview that provides a brief description of the board. This section should answer the following questions:
+ Which hardware is required to run the demo application?
Provide links to pages on your company website for more detail.
+ Which IDEs are supported for developing applications for the board?
Provide links to IDE user guides and download pages.
+ Which toolchains and other software utilities are required for development?
Provide links to user guides and download pages.
+ Are there any other prerequisites for getting started with FreeRTOS on the board?
Provide links to purchasing pages, user guides, and download pages.
## Setting up your hardware
In this section, provide instructions for setting up the platform's hardware. Make sure that you provide links to any user guides or other documentation for setting up hardware.
These instructions include the following:
+ Configuring jumper settings.
+ Downloading and installing drivers.
Provide links to download pages and other documentation for supported driver versions.
+ Connecting the board to a computer.
+ Any other steps required to set up the hardware.
## Setting up the development environment
In this section, provide instructions for setting up the platform's supported development environment. Make sure that you provide links to any download pages, user guides, or other documentation for each item.
These instructions include the following:
+ Establishing a serial connection.
+ Downloading and installing the toolchain.
+ Downloading and installing a supported IDE.
+ Any other software that is required to develop and debug applications for the device.
## Build and run the demo application
### Build the demo application
In this section, provide instructions for building the provided demo application in a supported IDE, or with supported command line tools.
### Run the demo application project
In this section, provide instructions for flashing and running the FreeRTOS demo code on your board.
## Debugging
In this section, provide instructions for using on-board or external debuggers.
## Troubleshooting
In this section, provide troubleshooting tips for resolving common or potential problems.
A **Getting Started Guide** template is available for download from the [APN Partner Portal](https://partnercentral.awspartner.com/ContentFolderPartner?id=0690h000009VVzsAAG) here. Credentials to sign in are required.
# FreeRTOS manifest file instructions
A manifest file is required for AWS IoT Device Tester to identify versions and libraries being used. It helps customers delineate versions, libraries dependencies, and metadata.
The file should meet the following requirements:
+ The file must be named `manifest.yml`.
+ It must be in the base folder of the library or package.
+ It must be in YAML format and follow the [YAML 1.2 specifications](https://yaml.org/spec/1.2/spec.html).
The parameters can be in any order, but we recommend that you put them in the order listed below for optimal readability. Add comments to the file to help customers use your package.
**File path**
Located at the root of a package or library. There is only one manifest file per package. Dependencies that are brought in may have their own manifest files.
**Parameters**
**name**
The name of the package. All spaces should be replaced with an underscore (\$1). For example, `My project name - 2020` should be changed to `My_project_name_-_2020`.
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 40
**version**
The version of the package. The version can be a release version or version tag.
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 30
**description**
The human-readable description of the package. The description should clearly describe what the package is and what it provides.
+ type: string
+ required: true
+ minLength: 30
+ maxLength: 255
**dependencies**
A list of all first-level dependencies that are required for a user to successfully build this package and which can be retrieved by a Git, Subversion, or Mercurial source code host. Don't include dependencies that are not available through Git, SVG, or hg. Don't include dependencies used for tests, documentation generation, or development. To promote a good experience, we recommend you avoid listing dependencies that are gated or private.
+ type: array
+ required: false
+ minLength: 0
**dependencies[].name**
The package name of a dependency. This must match the package name found in the dependency's `name` parameter.
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 40
**dependencies[].version**
The version of a dependency. The version can be a release version or a version tag. If any dependencies are included within the package itself, the version must match the manifest file that is in the dependency.
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 30
**dependencies[].repository**
Describes the location of the dependency source code.
+ type: dictionary
+ required: true
**dependencies[].repository.type**
The type of repository.
+ type: string
+ required: true
+ enum: [git, svn, hg]
**dependencies[].repository.url**
The URL of the location of the repository. This must be a full URL with a protocol prefix (for example, https://github.com/*ACCOUNT\$1NAME*/*REPO\$1NAME*).
+ type: string
+ required: true
**dependencies[].repository.path**
The relative path from the project workspace for the dependency.
+ type: string
+ required: true
**dependencies[].repository.branch**
The branch of the dependency that is used. If the package uses the release branch of libraries, don't include this parameter to keep the length of the manifest at a minimum.
+ type: string
+ required: false
**license**
The SPDX license identifier of the library. For the full list, see [https://spdx.org/licenses/](https://spdx.org/licenses/). It should match the `LICENSE` file included in the root of the repository if it exists.
+ type: string
+ required: true
# Example manifest.yml
```
---
# This is an example of the manifest file that is included at the root of all FreeRTOS GitHub repositories.
name : "Project_Name"
version: "202012.00-LTS"
description: "Clear concise description of this project."
dependencies:
- name: "dependency_1"
version: "v1.0.0"
repository:
type: "git"
url: "https://github.com/account/dependency_1"
path: "/relative/path/from/project/root/to/dependency_1"
branch: "1.x"
- name: "dependency_2"
version: "v1.0.1_LTS"
repository:
type: "git"
url: "https://github.com/account/dependency_1"
path: "/relative/path/from/project/root/to/dependency_2"
license: "MIT"
```