本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 主板资格认证
<a name="freertos-qualification"></a>

## 先决条件
<a name="prerequistes-qualification"></a>

硬件要求：

运行 FreeRTOS 库的基于 MCU 的开发板必须 AWS IoT 有：
+ 以太网、Wi-Fi 或蜂窝连接功能

软件要求：

《*FreeRTOS [移植指南》中的移植流程图](https://docs.aws.amazon.com/freertos/latest/portingguide/porting-chart.html)确定了任何基于 MC* U 的开发板所需的 FreeRTOS AWS IoT 库。最小子集为：
+ FreeRTOS 内核
+ coreMQTT
+ AWS IoT Over-The-Air 更新 (OTA)

测试要求：
+ 使用 AWS IoT Device Tester for FreeRTOS 对照[定义](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests)的 GitHub 测试存储库验证 FreeRTOS 库 APIs 所需的特定硬件平台的实现。请参阅[使用 (IDT) 验证移植 AWS IoT Device Tester 的 FreeRTOS 库](#qualifying-your-device-idt)。
+  AWS IoT Core 使用设备顾问验证互操作性。请参阅[使用 (IDT) 验证移植 AWS IoT Device Tester 的 FreeRTOS 库](#qualifying-your-device-idt)的步骤 4。

## 建议
<a name="recommendations-qualification"></a>

为提高安全性，我们建议执行以下操作。
+ 为防止离线或临时入侵成为永久性入侵，请将密钥和凭证存储在可抵御物理攻击的硬件信任根中，例如[安全元件](https://wikipedia.org/wiki/Secure_element)或安全飞地。
+ 为了降低可能导致未经授权的数据泄露的网络[欺骗](https://wikipedia.org/wiki/Spoofing_attack)和[man-in-the-middle](https://wikipedia.org/wiki/Man-in-the-middle_attack)攻击的风险，请为实现 DHCP、DNS、TCP/IP 和 [TLS 等协议的 FreeRTOS 库使用真随机数生成器 (TRNG)](https://wikipedia.org/wiki/Hardware_random_number_generator)。有关更多信息，请参阅[使用确定性随机位生成器生成随机数的推荐](https://csrc.nist.gov/publications/detail/sp/800-90a/rev-1/final) (NIST SP 800-90A) 中的第 50 页。

## 资格认证步骤
<a name="qualifying-your-device"></a>

### 使用 (IDT) 验证移植 AWS IoT Device Tester 的 FreeRTOS 库
<a name="qualifying-your-device-idt"></a>

1. 将 FreeRTOS 库移植到主板上。有关说明，请参阅[《FreeRTOS 移植指南》](https://docs.aws.amazon.com/freertos/latest/portingguide/)。

1. 创建一个测试项目，然后从 [FreerTOS-Libraries-Integration-Te](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests) GitHub sts 存储库中移植所需的测试。调用测试运行器任务[ RunQualificationTest](https://github.com/FreeRTOS/FreeRTOS-Libraries-Integration-Tests/blob/a8cafefc714cdbb4ee1d0f97c92e9c4cc75059fd/src/qualification_test.c#L52)。
**注意**  
为了获得良好的开发者体验，建议移植 FreeRTOS 库，然后使用 IDE 在本地运行相应的单个测试组来验证集成。  
测试运行器任务在单个测试项目中运行，或者在您的演示应用程序项目中运行。

1. 创建一个 `manifest.yml` 文件以列出您的资格认证中使用的所有依赖项。依赖项包括 FreeRTOS 库和测试存储库。有关详细信息，请参阅 [FreeRTOS 清单文件说明](afq-checklist-manifest-instr.md)。
**注意**  
IDT 使用 `manifest.yml` 来查找针对特定 FreeRTOS 库版本进行完整性检查所需的依赖项，并配置测试项目以构建、刷新和运行测试二进制文件。  
IDT 不强制要求特定的项目结构，而是使用 `manifest.yml` 文件中包含的参考路径。

1. <a name="qualifying-your-device-da"></a>使用设备顾问验证 AWS IoT 互操作性。

   1. 创建一个与上述测试中使用的 OTA 相同的组件的演示项目，包括 FreeRTOS 库、移植、集成任务。

      为了获得资格，该演示应用程序必须具备以下功能：
      + 执行 MQTT 发布和订阅主题。
      + 执行 OTA 更新。
      + 创建支持 OTA 更新的引导加载程序。使用自己的引导加载程序或 [MCUBoot](https://freertos.org/mcuboot/). 参见 [Labs-freertos-plus-](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-MCUBoot)。MCUBoot
**注意**  
[FreeRTO GitHub S](https://github.com/FreeRTOS/FreeRTOS) 存储库中预先配置了示例，演示了各个任务。还有一个集成的 [coreMQTT 代理演示](https://github.com/FreeRTOS/coreMQTT-Agent-Demos)，其中包含了 coreMQTT 和 OTA 任务。另请参阅 FreeRTOS 精选 IoT 集成：[资格认证项目示例](examples-qualification.md)。

   1. AWS IoT Device Tester 将针对[AWS IoT 设备顾问](https://docs.aws.amazon.com/iot/latest/developerguide/device-advisor.html)运行您的演示。资格认证需要以下 Device Advisor 测试用例。  
**测试用例**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/freertos/latest/qualificationguide/freertos-qualification.html)

1. 从中运行测试 AWS IoT Device Tester 并生成测试报告。
   + IDT 会配置测试，然后自动构建并刷写您的主板。要启用此功能，您必须将 IDT 配置为在 `userdata.json` 文件中为您的设备运行构建和刷写命令。请参阅[《适用于 FreeRTOS 的 IDT 用户指南》](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html)中的[配置构建、刷写和测试设置](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-dt-ud)。
   + 在 `device.json` 文件中提供设备支持的功能，例如连接类型、加密算法、密钥配置方法，以便 IDT 确定要运行的适用测试。请参阅[《适用于 FreeRTOS 的 IDT 用户指南》](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html)中的[在 IDT 中为 FreeRTOS 创建设备池](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-dt-dp)。
   + 为 IDT 创建和配置您的 AWS 帐户，以创建所需的云资源。请参阅 [IDT for [FreeRTOS 用户指南中的创建和配置 IDT AWS](https://docs.aws.amazon.com/freertos/latest/userguide/device-tester-for-freertos-ug.html) 帐户以创建所需的云资源](https://docs.aws.amazon.com/freertos/latest/userguide/lts-qual-steps.html#lts-cfg-aws-afr)。

### 提交准备
<a name="qualifying-your-device-preparation"></a>

1. 编写**入门指南**，以便在您的设备上运行 MQTT 或 OTA 演示项目。请参阅[利用 FreeRTOS 指南为设备创建入门指南](https://docs.aws.amazon.com/freertos/latest/qualificationguide/afq-gsg.html)的说明。

1. 提供威胁建模文档，验证您是否降低了 *FreeRTOS* 移植指南中[移植 OTA 库](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html)中所述的[AWS IoT 设备引导加载程序威胁建模](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html#afr-bootloader)中定义的风险。在 [APN 合作伙伴中心](https://partnercentral.awspartner.com)提交设备时，必须将此文档作为支持资产上传。

1. 为代码下载提供公共存储库。我们建议您提供公司 GitHub 存储库链接。

### 资格提交
<a name="qualifying-your-device-submission"></a>
+ IDT 测试报告。
+ AWS IoT 设备顾问测试报告。
+ 威胁建模文档。
+ GitHub 包含下载源代码的存储库。

# 使用 FreeRTOS 指南为主板创建入门指南
<a name="afq-gsg"></a>

要获得 FreeRTOS 资格，必须使用 FreeRTOS 指南为主板创建入门指南。本指南引导用户设置硬件和开发环境，以便为 FreeRTOS 设备开发应用程序，并在设备上构建、运行和刷写创建的演示应用程序。

本指南必须在面向公众的网站上提供给客户。指南的 URL 是在 AWS 合作伙伴设备目录中列出合格主板的必要条件。

该指南必须包含以下说明：
+ 设置设备硬件。
+ 设置开发环境。
+ 构建并运行演示项目。
+ 调试。
+ 故障排除。

我们还建议该指南中包括：
+ 指向 MCU 数据表的链接。
+ 印刷电路板 (PCB) 原理图。
+ 默认映像启动控制台日志。

**重要**  
如果说明因操作系统而异，则必须针对 Windows、Linux 和 macOS 操作系统提供说明。

为主板编写指南时遵照[入门指南模板](getting_started_template.md)。您可以在[《FreeRTOS 用户指南》](https://docs.aws.amazon.com/freertos/latest/userguide/freertos-getting-started.html)中找到其他获得资格的主板的已发布指南示例。[APN 合作伙伴中心](https://partnercentral.awspartner.com/)提供了入门指南的模板。

# 入门指南模板
<a name="getting_started_template"></a>

编写概述，提供对主板的简要说明。本部分应回答以下问题：
+ 运行演示应用程序需要什么硬件？

  提供指向公司网站页面的链接，以了解更多详细信息。
+ 开发主板应用程序时支持哪些？ IDEs 

  提供指向 IDE 用户指南和下载页面的链接。
+ 开发需要用到哪些工具链和其他软件实用程序？

  提供指向用户指南和下载页面的链接。
+ 对于有关主板的 FreeRTOS 入门，是否需要具备其他先决条件？

  提供指向购买页面、用户指南和下载页面的链接。

## 设置硬件
<a name="template-setup-hardware"></a>

本部分阐述如何设置平台的硬件。请确保提供指向用于设置硬件的任何用户指南或其他文档的链接。

这些说明包括以下内容：
+ 配置跳线设置。
+ 下载并安装驱动程序。

  提供指向支持的驱动程序版本的下载页面和其他文档的链接。
+ 将主板连接到计算机。
+ 设置硬件所需的其他任何步骤。

## 设置开发环境
<a name="template-setup-dev"></a>

本部分阐述如何设置平台支持的开发环境。请确保提供指向每一项的任何下载页面、用户指南或其他文档的链接。

这些说明包括以下内容：
+ 建立串行连接。
+ 下载并安装工具链。
+ 下载并安装支持的 IDE。
+ 为设备开发和调试应用程序所需的其他任何软件。

## 构建和运行演示应用程序
<a name="template-build-and-run-example"></a>

### 构建演示应用程序
<a name="template-freertos-import-project"></a>

本部分阐述如何在支持的 IDE 中构建提供的演示应用程序或使用支持的命令行工具进行构建的说明。

### 运行演示应用程序项目
<a name="template-run-examples"></a>

本部分阐述如何在主板上刷写和运行 FreeRTOS 演示代码。

## 调试
<a name="template-debugging"></a>

本部分阐述如何使用板载调试程序或外部调试程序。

## 问题排查
<a name="template-troubleshooting"></a>

本部分阐述用于解决常见问题或潜在问题的故障排除技巧。

**入门指南**模板可从此处的 [APN 合作伙伴门户网站](https://partnercentral.awspartner.com/ContentFolderPartner?id=0690h000009VVzsAAG)下载。需要凭证才能登录。

# FreeRTOS 清单文件说明
<a name="afq-checklist-manifest-instr"></a>

需要清单文件 AWS IoT Device Tester 才能识别正在使用的版本和库。它可以帮助客户描述版本、库依赖项和元数据。

该文件应满足以下要求：
+ 文件必须命名为 `manifest.yml`。
+ 它必须位于库或软件包的基本文件夹中。
+ 它必须采用 YAML 格式且符合 [YAML 1.2 规范](https://yaml.org/spec/1.2/spec.html)。

参数可以按任意顺序排列，但为了便于阅读，我们建议按以下顺序排列。在文件中添加注释以帮助客户使用您的软件包。

**文件路径**  
位于软件包或库的根目录中。每个软件包只有一个清单文件。引入的依赖项可能有自己的清单文件。

**参数**    
**name**  
软件包的名称。所有空格都应替换为下划线 (\$1)。例如，`My project name - 2020` 应更改为 `My_project_name_-_2020`。  
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 40  
**版本**  
软件包的版本。版本可以是发布版本或版本标签。  
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 30  
**描述**  
用户可读的软件包描述。描述应清楚地介绍软件包是什么以及提供的内容。  
+ type: string
+ required: true
+ MinLength: 1
+ MaxLength: 2048  
**依赖项**  
用户成功构建此软件包所需的所有第一级依赖项的列表，Git、Subversion 或 Mercurial 源代码主机可检索这些依赖项。不要包含无法通过 Git、SVG 或 hg 获得的依赖项。不要包含用于测试、文档生成或开发的依赖项。为了提升体验，我们建议您避免列出封闭或私有的依赖项。  
+ 类型：数组
+ required: false
+ minLength: 0  
**dependencies[].name**  
依赖项的软件包名称。这必须与依赖项的 `name` 参数中的软件包名称相匹配。  
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 40  
**dependencies[].version**  
依赖项的版本。版本可以是发布版本或版本标签。如果软件包本身包含依赖项，则版本必须与依赖项中的清单文件相匹配。  
+ type: string
+ required: true
+ minLength: 1
+ maxLength: 30  
**dependencies[].repository**  
描述依赖项源代码的位置。  
+ type: dictionary
+ required: true  
**dependencies[].repository.type**  
存储库的类型。  
+ type: string
+ required: true
+ enum: [git, svn, hg]  
**dependencies[].repository.url**  
存储库位置的 URL。这必须是带有协议前缀的完整 URL（例如 https://github.com/*ACCOUNT\$1NAME*/*REPO\$1NAME*）。  
+ type: string
+ required: true  
**dependencies[].repository.path**  
依赖项从项目工作区开始的相对路径。  
+ type: string
+ required: true  
**dependencies[].repository.branch**  
使用的依赖项的分支。如果软件包使用库的发布分支，那么，为了尽量缩短清单的长度，请不要包含此参数。  
+ type: string
+ required: false  
**license**  
库的 SPDX 许可证标识符。有关完整列表，请参阅 [https://spdx.org/licenses/](https://spdx.org/licenses/)。它应该与存储库根目录中包含的 `LICENSE` 文件（如果存在）相匹配。  
+ type: string
+ required: true

# 示例 manifest.yml
<a name="afq-checklist-manifest-example"></a>

```
---
# 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"
```