Embed Size (px)
Citation preview
FreeRTOS移植指南
FreeRTOS 移植指南
FreeRTOS: 移植指南Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon 的商标和商业外观不得用于任何非 Amazon 的商品或服务，也不得以任何可能引起客户混淆或者贬低或诋毁Amazon 的方式使用。所有非 Amazon 拥有的其他商标均为各自所有者的财产，这些所有者可能附属于 Amazon、与Amazon 有关联或由 Amazon 赞助，也可能不是如此。
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。
FreeRTOS 移植指南
Table of ContentsFreeRTOS 移植 .................................................................................................................................. 1
什么是 FreeRTOS 投票？ ............................................................................................................ 1移植 FreeRTOS .......................................................................................................................... 1
系统要求 ............................................................................................................................ 2移植较旧版本的 FreeRTOS .................................................................................................. 2移植常见问题 ..................................................................................................................... 5
下载要 FreeRTOS 植的 ....................................................................................................................... 6为移植设置 FreeRTOS 源代码 .............................................................................................................. 7
配置 FreeRTOS 下载项目 ............................................................................................................ 7为供应商提供的主板特定库配置目录 ....................................................................................... 7为项目文件配置目录 ............................................................................................................ 8配置FreeRTOSConfig.h .................................................................................................... 8
为测试设置 FreeRTOS 源代码 ...................................................................................................... 8创建 IDE 项目 .................................................................................................................... 9创建 CMake 列表文件 ........................................................................................................ 10
移植 FreeRTOS 库 ............................................................................................................................ 22移植流程图 ............................................................................................................................... 23configPRINT_STRING() ......................................................................................................... 25
Prerequisites .................................................................................................................... 25Implementation ................................................................................................................. 25Testing ............................................................................................................................ 25
FreeRTOS 内核 ........................................................................................................................ 25Prerequisites .................................................................................................................... 26配置 FreeRTOS 内核 ......................................................................................................... 26Testing ............................................................................................................................ 27
Wi-Fi ....................................................................................................................................... 27Prerequisites .................................................................................................................... 27Porting ............................................................................................................................ 27Testing ............................................................................................................................ 28Validation ......................................................................................................................... 31
TCP/IP .................................................................................................................................... 32移植 FreeRTOS+TCP ........................................................................................................ 32移植 lwIP ......................................................................................................................... 34
安全套接字 ............................................................................................................................... 36Prerequisites .................................................................................................................... 36Porting ............................................................................................................................ 37Testing ............................................................................................................................ 37Validation ......................................................................................................................... 40设置 Echo 服务器 ............................................................................................................. 40
第 11 届联合国代表团 ................................................................................................................ 43Prerequisites .................................................................................................................... 43Porting ............................................................................................................................ 44Testing ............................................................................................................................ 45Validation ......................................................................................................................... 47
TLS ........................................................................................................................................ 47Prerequisites .................................................................................................................... 47Porting ............................................................................................................................ 48将您的设备连接到 AWS IoT ................................................................................................ 48为 TLS 测试设置证书和密钥 ............................................................................................... 49创建 BYOC (ECDSA) ........................................................................................................ 54Testing ............................................................................................................................ 62Validation ......................................................................................................................... 63
科雷姆 ..................................................................................................................................... 64Prerequisites .................................................................................................................... 64
iii
FreeRTOS 移植指南
设置 IDE 测试项目 ............................................................................................................ 64设置本地测试环境 .............................................................................................................. 64运行测试 .......................................................................................................................... 64Validation ......................................................................................................................... 65
核心 HTTP ............................................................................................................................... 65Prerequisites .................................................................................................................... 65设置 IDE 测试项目 ............................................................................................................ 65设置本地测试环境 .............................................................................................................. 65运行测试 .......................................................................................................................... 66
无线 (OTA) 更新 ....................................................................................................................... 66Prerequisites .................................................................................................................... 66Porting ............................................................................................................................ 66IoT 设备引导加载程序 ........................................................................................................ 67Testing ............................................................................................................................ 70Validation ......................................................................................................................... 72
低功耗蓝牙 ............................................................................................................................... 72Prerequisites .................................................................................................................... 72Porting ............................................................................................................................ 73Testing ............................................................................................................................ 74Validation ......................................................................................................................... 76
使用 BLE 的 OTA 更新 .............................................................................................................. 76Introduction ...................................................................................................................... 76Prerequisites .................................................................................................................... 76Setup .............................................................................................................................. 77Testing ............................................................................................................................ 83Validation ......................................................................................................................... 84References ...................................................................................................................... 84
通用 I/O ................................................................................................................................... 84Prerequisites .................................................................................................................... 85Testing ............................................................................................................................ 85移植 I2C 库 ...................................................................................................................... 87移植 UART 库 .................................................................................................................. 89移植 SPI 库 ..................................................................................................................... 91
蜂窝 ........................................................................................................................................ 93Prerequisites .................................................................................................................... 93
从版本 1.4.x 迁移到版本 201906.00（和更高版本） ................................................................................ 94迁移应用程序 ............................................................................................................................ 94迁移移植项 ............................................................................................................................... 94
FreeRTOS 代码目录结构 .................................................................................................... 94CMake 构建系统 ............................................................................................................... 94迁移 Wi-Fi 库移植项 .......................................................................................................... 94
.................................................................................................................................................... xcvi
iv
FreeRTOS 移植指南什么是 FreeRTOS 投票？
FreeRTOS 移植什么是 FreeRTOS 投票？
FreeRTOS 与世界领先的芯片公司合作开发了 15 年，现在每 175 秒下载一次，是面向微控制器和小型微处理器的市场领先的实时操作系统 (RTOS)。FreeRTOS 在 MIT 开源许可证下免费分发，其中包含一个内核和一组持续增加的库，可广泛应用于各个行业领域。FreeRTOS 的设计重点是可靠性和易用性。
FreeRTOS 包含用于连接、安全性和无线 (OTA) 更新的库。FreeRTOS 还包括演示应用程序，在合格的主板上展示 FreeRTOS 功能。
FreeRTOS 是一个开源项目。您可以在 GitHub 网站 (https://github.com/aws/amazon-freertos) 上下载源代码，提供更改或增强功能或报告问题。我们根据 MIT 开源许可证发布 FreeRTOS 代码，以便您可以在商业和个人项目中使用它。
我们也欢迎为 FreeRTOS 文档（FreeRTOS 用户指南、FreeRTOS 移植指南, 和FreeRTOS 资格认证指南)。有关文档的 markdown 来源，请访问 https://github.com/awsdocs/aws-freertos-docs。这是根据知识共享(CC BY-ND) 许可证发布的。
FreeRTOS 内核和组件是单独发布的，并使用语义版本控制。定期发布集成的 FreeRTOS 版本。所有版本使用基于日期的版本控制，格式为 YYYYMM.NN，其中：
• Y 表示年份。• M 表示月份。• N 表示指定月份的版本顺序（00 表示第一个版本）。
例如，2022021 年 6 月的第二个版本为 202106.01。
以前，FreeRTOS 版本在主要版本中使用语义版本控制。虽然它已改用基于日期的版本控制（FreeRTOS1.4.8 更新为 FreeRTOS AWS 参考集成 201906.00），但 FreeRTOS 内核和每个单独的 FreeRTOS 库仍保留语义版本控制。在语义版本控制中，版本号本身 (X.Y.Z) 表示版本是主要版本、次要版本还是修订版本。您可以使用库的语义版本评估新版本对应用程序的影响以及适用范围。
LTS 版本的维护方式与其他版本类型不同。除了解决缺陷以外，还经常使用新功能更新主要版本和次要版本。LTS 版本仅使用解决严重缺陷和安全漏洞的更改进行更新。在发布后，不会在给定 LTS 版本中引入新功能。它们在发布后至少保留三个日历年，并为设备制造商提供使用稳定基准的选项，而不是使用主要和次要版本表示的更动态的基准。
将 FreeRTOS 移植到您的 IoT 设备在微控制器主板能够运行 FreeRTOS 之前，必须将部分 FreeRTOS 代码移植到设备的硬件。基本内核端口应参考FreeRTOS 移植指南，发布时间：www.freertos.org。对于打算包含 FreeRTOS 库以实现安全性、连接性等的移植，以下说明建立在内核移植之上。
将 FreeRTOS 移植到您的设备
1. 按照中的说明进行操作下载要 FreeRTOS 植的 (p. 6)下载最新版本的 FreeRTOS 移植。2. 按照中的说明进行操作为移植设置 FreeRTOS 源代码 (p. 7)配置 FreeRTOS 下载中的文件和文件夹
以进行移植和测试。3. 按照中的说明进行操作移植 FreeRTOS 库 (p. 22)将 FreeRTOS 库移植到您的设备。每个移植主题包
含有关测试移植的说明。
1
FreeRTOS 移植指南系统要求
系统要求将移植到 FreeRTOS 的设备必须是满足以下最低要求的微控制器主板：
• 25 MHz 的处理速度• 64KB RAM• 为存储在 MCU 上的每个可执行映像提供 128 KB 程序内存• （如果 移植 OTA 库 (p. 66)）MCU 上存储两个可执行映像
移植较旧版本的 FreeRTOS如果您要移植旧版本的 FreeRTOS，请转到FreeRTOS AWS 参考集成存储库，并按版本标签签出要移植的FreeRTOS 版本。tests 文件夹中的资格认证和测试文档为 PDF 格式。请参阅下表中的资格认证和测试文档历史记录。
FreeRTOS 移植和资格认证文档的修订历史记录
日期 移植和资格认证指南的文档版本
更改历史记录 FreeRTOS 版本
2020 年 12 月 202012.00（移植指南）
202012.00（资格认证指南）
• 发布• 添加了 配置核心
HTTP 库以进行测试 (p. 65)
• 添加了 移植移植移植移植库 (p. 93)
202012.00
2020 年 11 月 202011.00（移植指南）
202011.00（资格认证指南）
• 发布• 添加了 配置
CoremQTT 库以进行测试 (p. 64)
202011.00
2020 年 7 月 202007.00（移植指南）
202007.00（资格认证指南）
• 发布版本 202007.00
2020 年 2 月 18 日 202002.00（移植指南）
202002.00（资格认证指南）
• 版本 202002.00• Amazon FreeRTOS
投票现已成为FreeRTOS 投票
202002.00
2019 年 12 月 17 日 201912.00（移植指南）
201912.00（资格认证指南）
• 版本 201912.00• 增加了 移植通用 I/O
库 (p. 84)。
201912.00
2019 年 10 月 29 日 201910.00（移植指南）
201910.00（资格认证指南）
• 版本 201910.00• 更新了随机数生成器
移植信息。
201910.00
2019 年 8 月 26 日 201908.00（移植指南）
201908.00（资格认证指南）
• 版本 201908.00• 添加了配置 HTTPS 客
户端库以进行测试
201908.00
2
FreeRTOS 移植指南移植较旧版本的 FreeRTOS
日期 移植和资格认证指南的文档版本
更改历史记录 FreeRTOS 版本
更新了 移植代码库 (p. 43)
2019 年 6 月 17 日 201906.00（移植指南）
201906.00（资格认证指南）
• 发布版本 201906.00• 更新了目录结构
201906.00 主版本
2019 年 5 月 21 日 1.4.8（移植指南）
1.4.8（资格认证指南）
• 将文档移植到FreeRTOS 移植指南
• 资格认证文档移到FreeRTOS 资格认证指南
1.4.8
2019 年 2 月 25 日 1.1.6 • 从“入门指南模板”附录中删除了下载和配置说明（第 84 页）
1.4.5
1.4.6
1.4.7
2018 年 12 月 27 日 1.1.5 • 使用 CMake 要求更新了“资格认证清单”附录（第 70 页）
1.4.5
1.4.6
2018 年 12 月 12 日 flink-client • 在 TCP/IP 移植附录中添加了 lwIP 移植说明（第 31 页）
1.4.5
2018 年 11 月 26 日 1.1.3 • 增加了低功耗蓝牙移植附录（第 52 页）
• 为 FreeRTOS 的测试信息添加了 AWS IoT设备测试器
• 在 FreeRTOS 控制台附录中添加了 CMake链接（第 85 页）
1.4.4
2018 年 11 月 7 日 1.1.2 • 更新了 PKCS # 11 移植附录中的 PKCS #11 PAL 接口移植说明（第 38 页）
• 更新了CertificateConfigurator.html的路径（第 76 页）
• 更新了“入门指南模板”附录（第 80 页）
1.4.3
3
FreeRTOS 移植指南移植较旧版本的 FreeRTOS
日期 移植和资格认证指南的文档版本
更改历史记录 FreeRTOS 版本
2018 年 10 月 8 日 1.1.1 • 在aws_test_runner_config.h测试配置表中新增了“AFQP 所需”列（第16 页）
• 更新了“创建测试项目”部分中的 Unity 模块目录路径（第 14页）
• 更新了“建议的移植顺序”图表（第 22 页）
• 更新了 TLS 附录“测试设置”中的客户端证书和密钥变量名称（第40 页）
• 更改了 SecureSockets 库移植附录“测试设置”（第 34页）、TLS 移植附录“测试设置”（第 40页）和“TLS 服务器设置”附录（第 57 页）中的文件路径
1.4.2
2018 年 8 月 27 日 1.1.0 • 添加了 OTA 更新移植附录（第 47 页）
• 添加了引导加载程序移植附录（第 51 页）
1.4.0
1.4.1
2018 年 8 月 9 日 1.0.1 • 更新了“建议的移植顺序”图表（第 22 页）
• 更新了 PKCS # 11 移植附录（第 36 页）
• 更改了 TLS 移植附录“测试设置”（第 40页）和“TLS 服务器设置”附录第 9 步（第 51页）中的文件路径
• 修补了 MQTT 移植附录“先决条件”中的超链接（第 45 页）
• 在 “创建 BYOC 的说明” 附录中的示例中添加了 AWS CLI 配置说明（第 57 页）
1.3.1
1.3.2
2018 年 7 月 31 日 1.0.0 FreeRTOS 资格认证计划指南的初始版本
1.3.0
4
FreeRTOS 移植指南移植常见问题
移植常见问题什么是 FreeRTOS 移植？
FreeRTOS 移植是指特定于主板的 API 实现，用于所需 FreeRTOS 库和您的平台支持的 FreeRTOS库。通过移植，API 可在主板上工作，并实现设备驱动程序与平台供应商提供的 BSP 之间的必需集成。您的移植还应包含主板所需的所有配置调整（如时钟频率，堆栈大小、堆大小）。
我的设备不支持 Wi-Fi、低功耗蓝牙或无线 (OTA) 更新。移植 FreeRTOS 是否需要所有库？
移植 FreeRTOS 连接库的主要求是您的设备可以连接到云。例如，如果您可以通过安全的以太网连接来连接到云，则 Wi-Fi、低功耗蓝牙和无线 (OTA) 库是不需要的。请记住，在未导入所有库的情况下，部分测试和演示应用程序将不起作用。
我可以达到”Echo 服务器”（例如，通过跨 2 个不同接入点的两个子网）？
需要 Echo 服务器才能通过 TCP/IP 和 TLS 端口测试。必须通过主板连接的网络访问 Echo 服务器。如果您需要不同子网中的设备都可以与单个 Echo 服务器通信，请咨询您的 IT 支持人员以启用通过子网路由。
需要打开哪些网络端口以运行 FreeRTOS 端口测试？
运行 FreeRTOS 端口测试需要以下网络连接：
端口 协议
443、8883 MQTT
8443 Greengrass Discovery
如果您对移植的疑问在本页面或 FreeRTOS 移植指南的其余部分中都找不到答案，请联系 FFreeRTOS 工程团队。
5
FreeRTOS 移植指南
下载要 FreeRTOS 植的在开始将 FreeRTOS 移植到您的平台之前，您需要下载 FreerTFreeRTOS 或从GitHub。有关说明，请参阅README.md 文件。
Note
我们建议您克隆存储库。通过进行克隆，在更新被推送到存储库时，您可以更轻松地获得主分支的更新。
下载或克隆 FreeRTOS 后，您可以开始将 FreerTOS 代码移植到您的平台。有关说明，请参阅为移植设置FreeRTOS 源代码 (p. 7)，然后参阅移植 FreeRTOS 库 (p. 22)。
Note
在整个 FreeRTOS 文档中，FreeRTOS 下载被称为freertos。
6
FreeRTOS 移植指南配置 FreeRTOS 下载项目
为移植设置 FreeRTOS 源代码在您下载 FreeRTOS 之后，您需要在 FreerTOS 下载中配置一些文件和文件夹，然后才能开始移植。
要为移植准备 FreeRTOS 下载，您需要按照配置 FreeRTOS 下载项目 (p. 7)配置 FreeRTOS 下载的目录结构以适合您的设备。
如果您计划在实施移植的库时进行测试以用于调试用途，您还需要在开始移植之前，为测试配置一些文件。有关测试设置的更多信息，请参阅为测试设置 FreeRTOS 源代码 (p. 8)。
Note
您必须为 FreeRTOS 使用 AWS IoT Device TOS 设备测试程序来正式验证您的端口资格认证。有关FreeRTOS AWS IoT Device TOS 设备测试程序的更多信息，请参阅为 FreeRTOS 使用 AWS IoTDevice Tester 设备测试器（在 FreeRTOS 用户指南中）。有关您的设备使用 FreeRTOS 资格认证的信息，请参阅FreeRTOS 资格认证指南。
在您配置您的 FreeRTOS 下载并设置测试环境之后，您可以开始移植 FreerTOS。有关移植和测试的说明，请参阅移植 FreeRTOS 库 (p. 22)。
配置 FreeRTOS 下载项目按照下面的说明，为移植 FreeRTOS 代码到您的设备配置下载。
为供应商提供的主板特定库配置目录在下载的根目录 (freertos) 中，vendors 文件夹的结构如下所示：
vendors+ - vendor (Template, to be renamed to the name of the MCU vendor) + - boards | + - board (Template, to be renamed to the name of the development board) | + - aws_demos | + - aws_tests | + - CMakeLists.txt | + - ports + - driver_library (Template, to be renamed to the library name) + - driver_library_version (Template, to be renamed to the library version)
vendor and board 文件夹是模板文件夹，我们提供这些文件夹是为了简化创建演示和测试项目的过程。其目录结构可确保所有演示和测试项目具有一致的组织结构。
aws_tests 文件夹具有以下结构：
vendors/vendor/boards/board/aws_tests+ - application_code (Contains main.c, which contains main())| + - vendor_code (Contains vendor-supplied, board-specific files)| + - main.c (Contains main())+ - config_files (Contains FreeRTOS config files)
所有测试项目需要供应商提供的驱动程序库。一些供应商提供的文件特定于目标开发主板，例如将 GPIO 输出映射到 LED 灯的标头文件。这些文件在 vendor_code 文件夹中。
其他供应商提供的文件，例如 GPIO 库，在主板的 MCU 系列之间通用。这些文件属于 driver_libraryfolder。
7
FreeRTOS 移植指南为项目文件配置目录
为供应商提供的 MCU 系列通用库设置目录
1. 将供应商提供的在目标主板 MCU 系列中通用的所有必需库保存到 driver_library_version 文件夹中。
2. 将 vendor 文件夹重命名为供应商的名称，将 driver_library 和 driver_library_version 文件夹重命名为驱动程序库的名称及其版本。
Important
不要将供应商提供的目标主板 MCU 系列通用库保存到 freertos/test 或 freertos/demos 的任何子目录中。
为项目文件配置目录在 freertos 中，projects 文件夹的结构如下所示：
projects+ - vendor (Template, to be renamed to the name of the MCU vendor) + - board (Template, to be renamed to the name of the development board) + - ide (Contains an IDE-specific project) + - visual_studio (contains project files for Visual Studio)
设置项目目录
1. 将 ide 文件夹重命名为您用于构建测试项目的 IDE 的名称。2. 将 vendor 文件夹重命名为供应商的名称，将 board 文件夹重命名为开发主板的名称。
配置FreeRTOSConfig.h在您配置了 FreeRTOS 下载的目录结构之后，在FreeRTOSConfig.h配置头文件。
在 FreeRTOSConfig.h 中配置主板名称
1. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSConfig.h。
2. 在行中#define configPLATFORM_NAME "Unknown", 更改 Unknown 以与您的主板名称匹配。
为测试设置 FreeRTOS 源代码FreeRTOS 包括针对每个移植库的测试。aws_test_runner.c 文件定义一个 RunTests 函数，运行您在aws_test_runner_config.h 标头文件中指定的每个测试。当您移植每个 FFreeRTOS 库时，您可以构建移植的 FreerTOS 源代码，将编译后的代码刷写到主板中，然后在主板上运行代码，从而测试移植。
要构建 FreeRTOS 源代码进行测试，您可以使用以下选项之一：
• 支持的 IDE。
如果使用 IDE 构建 FreeRTOS 源代码，则需要设置 IDE 测试项目。按照创建 IDE 项目 (p. 9)中的说明，在 IDE 中创建测试项目。移植 FreeRTOS 库 (p. 22) 下的各个特定于库的移植部分包含附加说明，用于设置 IDE 测试项目中库的已移植源文件。
• CMake 生成系统。
如果您使用的是 CMake，则需要创建一个 CMakeLists.txt CMake 列表文件。按照创建 CMake 列表文件 (p. 10)中的说明，创建 CMakeLists.txt CMake 列表文件。
8
FreeRTOS 移植指南创建 IDE 项目
Important
ACMakeLists.txt文件在 FreeRTOS 控制台上列出合格设备需要文件，而不论您使用什么测试方法。
构建代码后，请使用您平台的闪存实用程序，将编译后的代码刷写到设备中。
Note
您在 userdata.json 文件中为 Device Tester 指定构建和刷写工具，因此，如果您使用 DeviceTester 验证移植项，就无需手动刷写代码。
创建 IDE 项目在您配置了 FreeRTOS 下载之后，您可以创建一个 IDE 项目并将代码导入到该项目。
按照以下说明创建具有所需 IDE 项目结构的 IDE 项目以进行测试。
Important
如果您使用基于 Eclipse 的 IDE，请不要配置项目在任意指定文件夹中构建所有文件。相反，通过分别链接到每个源文件来将源文件添加到项目。
1. 打开 IDE，然后在 freertos/projects/vendor/board/ide 目录中创建一个名为 aws_tests 的项目。
2. 在 IDE 中，在 aws_tests 项目下创建两个虚拟文件夹：
• application_code
• config_files
UDERaws_tests，IDE 项目中现在应有两个虚拟文件夹：application_code和config_files。
Note
Eclipse 会生成一个额外的 includes 文件夹。此文件夹不属于所需的结构。3. 在 IDE 中，将 freertos/vendors/vendor/boards/board/aws_tests/application_code 及
其子目录中的所有文件导入到 aws_tests/application_code 虚拟文件夹中。4. 在 IDE 中，将 freertos/tests 及其子目录中的所有文件导入到 aws_tests/application_code
虚拟目录中。5. 在 IDE 中，将 freertos/vendors/vendor/boards/board/aws_tests/config_files 目录中
的所有标头文件导入到 aws_tests/config_files 虚拟文件夹中。
Note
如果您不是移植到特定库，则不需要将该库的文件导入到您的项目。例如，如果您不是移植OTA 库，则可以留下 aws_ota_agent_config.h 和 aws_test_ota_config.h 文件。如果您不是移植 Wi-Fi 库，则可以留下 aws_test_wifi_config.h 和 aws_wifi_config.h文件。
6. 将 freertos/libraries 中所需的库及其子目录导入 aws_tests IDE 项目中，包括任何必需的第三方库。有关所需的库的信息，请遵循FreeRTOS 移植流程图。特定库的移植部分提供了有关哪些FreeRTOS 库依赖于需与测试项目一起包含的第三方库的信息。
最后，将以下目录中的 Unity 文件导入您的项目中。
• freertos/libraries/3rdparty/unity/src/
• freertos/libraries/3rdparty/unity/extras/fixture/src/
9
FreeRTOS 移植指南创建 CMake 列表文件
Note
如果您不是移植到特定库，则不需要将该库的文件导入到您的项目。7. 将 freertos/freertos_kernel 和 freertos/freertos_kernel/include 目录中的所有源文
件导入到 aws_tests IDE 项目中。8. 将与您的编译器和平台架构对应的 freertos/freertos_kernel/portable 子目录导入到
aws_tests IDE 项目中。9. 将您为设备使用的 FreeRTOS 内存管理实施导入到 aws_tests IDE 项目。
freertos/freertos_kernel/portable/MemMang 目录包含 FreeRTOS 内存管理实施。我们强烈建议您使用 heap_4.c 或 heap_5.c。
有关 FreeRTOS 内存管理的更多信息，请参阅内存管理。10. 打开项目的 IDE 属性，并将以下路径添加到编译器的包含路径：
• freertos/vendors/vendor/boards/board/aws_tests/config_files
• freertos/freertos_kernel/include
• freertos/freertos_kernel/portable/compiler/architecture
• 供应商提供的驱动程序库所需的任何路径11. 在项目属性中，定义 UNITY_INCLUDE_CONFIG_H 和 AMAZON_FREERTOS_ENABLE_UNIT_TESTS 作
为项目级别的宏。
完成设置您的 IDE 项目之后，您已准备好将 FreeRTOS 库移植到您的设备。有关说明，请参阅移植FreeRTOS 库 (p. 22)。
创建 CMake 列表文件在您为移植配置 FreeRTOS 下载之后，您可以为项目和平台设置 CMake 列表文件。
主题• Prerequisites (p. 10)• 根据 CMakeLists.txt 模板为平台创建列表文件 (p. 11)• 使用 CMake 构建 FreeRTOS (p. 17)
Prerequisites请先确保主机符合以下先决条件，再继续下一步：
• 设备的编译工具链必须支持计算机的操作系统。CMake 支持所有版本的 Windows、macOS 和 Linux。
不支持 Windows Subsystem for Linux (WSL)。在 Windows 计算机上使用本机 CMake。• 必须安装了 CMake 3.13 版或更高版本。
可以从 CMake.org 下载 CMake 的二进制发行版。
Note
如果下载 CMake 的二进制发行版，请确保先将 CMake 可执行文件添加到 PATH 环境变量，然后再从命令行使用 CMake。
也可以使用程序包管理器下载并安装 CMake，例如，macOS 上的 homebrew，Windows 上的 scoop 或chocolatey。
10
FreeRTOS 移植指南创建 CMake 列表文件
Note
许多 Linux 发行版的程序包管理器中的 CMake 程序包版本已过时。如果发布版本的程序包管理器不包括最新版本的 CMake，那么可以尝试linuxbrew或者nix。
• 必须具有兼容的本机构建系统。
CMake 可以针对许多本机构建系统，包括 GNU Make 或 Ninja。Make 和 Ninja 都可以使用程序包管理器安装在 Linux、macOS 和 Windows 上。如果在 Windows 上使用 Make，则可从 Equation 安装独立版本，或安装捆绑了 Make 的 MinGW。
Note
MinGW 中的 Make 可执行文件名为 mingw32-make.exe，而不是 make.exe。
我们建议使用 Ninja，因为它不仅速度快于 Make，还可提供对所有桌面操作系统的本机支持。
根据 CMakeLists.txt 模板为平台创建列表文件ACMakeLists.txt模板文件是随 FreeRTOS 提供的，它位于freertos/vendors/vendor/boards/board/CMakeLists.txt。
CMakeLists.txt 模板文件由以下四个部分组成：
• FreeRTOS 控制台元数据 (p. 11)• 编译器设置 (p. 12)• FreeRTOS 可移植层 (p. 13)• FreeRTOS 演示和测试 (p. 16)
可以按照说明编辑列表文件的这四个部分，以与平台相匹配。您可以参考 freertos/vendors 中其他符合条件的供应商主板的 CMakeLists.txt 文件以作为示例。
整个文件中会调用以下两个主要函数：
afr_set_board_metadata(name value)
此函数为 FreeRTOS 控制台定义元数据。该函数是在 freertos/tools/cmake/afr_metadata.cmake 中定义的。
afr_mcu_port(module_name [<DEPENDS> [targets...]])
此函数定义与 FreeRTOS 模块（即库）关联的可移植层目标。此函数采用以下名称形式创建 CMakeGLOBAL INTERFACE IMPORTED 目标：AFR:module_name::mcu_port。如果使用 DEPENDS，则其他目标通过 target_link_libraries 链接在一起。该函数是在 freertos/tools/cmake/afr_module.cmake 中定义的。
FreeRTOS 控制台元数据
模板文件的第一部分定义用于在 FreeRTOS 控制台中显示主板信息的元数据。使用函数afr_set_board_metadata(name value) 定义模板中列出的每个字段。下表提供了每个字段的说明。
字段名称 值说明
ID 主板的唯一 ID。
DISPLAY_NAME 要显示在 FreeRTOS 控制台上的主板的名称。
11
FreeRTOS 移植指南创建 CMake 列表文件
字段名称 值说明
DESCRIPTION FreeRTOS 控制台的主板的简短说明。
VENDOR_NAME 主板供应商的名称。
FAMILY_NAME 主板 MCU 系列的名称。
DATA_RAM_MEMORY 主板 RAM 的大小，后跟单位缩写。例如，使用 KB表示千字节。
PROGRAM_MEMORY 主板程序内存的大小，后跟单位缩写。例如，使用MB 表示兆字节。
CODE_SIGNER 用于 OTA 更新的代码签名平台。使用AmazonFreeRTOS-Default 作为 SHA256 散列算法和 ECDSA 加密算法。如果要使用不同的代码签名平台，请联系我们。
SUPPORTED_IDE 主板支持的 IDE 的 ID 列表，用分号分隔。
IDE_ID_NAME 支持的 IDE 的名称。Replace ID 中列出了 IDE 的IDSUPPORTED_IDE字段。
IDE_ID_COMPILER 对于所支持的 IDE，支持的编译器的名称列表，用分号分隔。Replace ID 中列出了 IDE 的IDSUPPORTED_IDE字段。
KEY_IMPORT_PROVISIONING 如果板演示项目从预配置的aws_clientcredential_keys.h头文件；在这种情况下，快速 Connect 连接将在 FreeRTOS 控制台中启用。
如果预期的主板配置机制是 JITR/JITP 或多账户注册，则设置为 FALSE；在这种情况下，快速Connect 连接将在 FreeRTOS 控制台中禁用。
编译器设置模板文件的第二部分为主板定义编译器设置。要创建具有编译器设置的目标，可调用afr_mcu_port函数与compiler来代替 module_name 创建INTERFACE具有名称的目标AFR::compiler::mcu_port。内核会公开链接到此 INTERFACE 目标，以便编译器设置能以传递的方式填充到所有模块。
在列表文件的此部分中，使用标准的内置 CMake 函数定义编译器设置。在定义编译器设置时，请遵循以下最佳实践：
• 使用 target_compile_definitions 提供编译定义和宏。• 使用 target_compile_options 提供编译器标记。• 使用 target_include_directories 提供包含目录。• 使用 target_link_options 提供链接器标记。• 使用 target_link_directories 提供链接器搜索目录。• 使用 target_link_libraries 提供链接的库。
Note
如果在其他位置定义编译器设置，则不需要重复文件此部分中的信息。相反，使用 DEPENDS 调用afr_mcu_port，可从其他位置引入目标定义。
12
FreeRTOS 移植指南创建 CMake 列表文件
例如：
# your_target is defined somewhere else. It does not have to be in the same file.afr_mcu_port(compiler DEPENDS your_target)
使用 DEPENDS 调用 afr_mcu_port 时，它会调用target_link_libraries(AFR::module_name::mcu_port INTERFACEyour_targets)，这会填充所需 AFR::compiler::mcu_port 目标的编译器设置。
使用多个编译器
如果主板支持多个编译器，则可使用 AFR_TOOLCHAIN 变量动态选择编译器设置。该变量设置为使用的编译器的名称，该名称应该与位于 freertos/tools/cmake/toolchains 中的工具链文件的名称相同。
例如：
if("${AFR_TOOLCHAIN}" STREQUAL "arm-gcc") afr_mcu_port(compiler DEPENDS my_gcc_settings).elseif("${AFR_TOOLCHAIN}" STREQUAL "arm-iar") afr_mcu_port(compiler DEPENDS my_iar_settings).else() message(FATAL_ERROR "Compiler ${AFR_TOOLCHAIN} not supported.")endif()
高级编译器设置
如果要设置更高级的编译器设置，如设置基于编程语言的编译器标记，或更改不同版本的设置及调试配置，则可使用 CMake 生成器表达式。
例如：
set(common_flags "-foo")set(c_flags "-foo-c")set(asm_flags "-foo-asm")target_compile_options( my_compiler_settings INTERFACE $<$<COMPILE_LANGUAGE:C>:${common_flags} ${c_flags}> # This only have effect on C files. $<$<COMPILE_LANGUAGE:ASM>:${common_flags} ${asm_flags}> # This only have effect on ASM files.)
CMake 在读取列表文件时，不会在配置阶段评估 CMake 生成器表达式。它们会在生成阶段进行评估，当CMake 完成列表文件的读取，并为目标构建系统生成构建文件时。
FreeRTOS 可移植层模板文件的第三部分为 FreeRTOS（即库）定义所有可移植层目标。
您必须使用afr_mcu_port(module_name)函数为计划实施的每个 FreeRTOS 模块定义可移植层目标。
可以使用任何所需的 CMake 函数，只要afr_mcu_port调用所创建目标的名称提供了构建相应 FreeRTOS模块所需的信息。
afr_mcu_port 函数采用以下名称形式创建 GLOBAL INTERFACE 库目标：AFR::module_name::mcu_port。作为 GLOBAL 目标时，可以在 CMake 列表文件中进行引用。作为INTERFACE目标时，不能构建为独立的目标或库，但可以编译到相应的 FreeRTOS 模块。作为IMPORTED 目标时，其名称在目标名称中包含命名空间 (::)，例如，AFR::kernel::mcu_port。
默认情况下，无相应可移植层目标的模块处于禁用状态。如果运行 CMake 配置 FreeRTOS，而未定义任何可移植层目标，那么应该看到以下输出：
13
FreeRTOS 移植指南创建 CMake 列表文件
FreeRTOS modules: Modules to build: Disabled by user: Disabled by dependency: kernel, posix, pkcs11, secure_sockets, mqtt, ...
Available demos: Available tests:
在更新CMakeLists.txt文件，将启用相应的 FreeRTOS 模块。您还应该能构建其依赖性要求随后得以满足的任何 FreeRTOS 模块。例如，如果已启用 CoreMqtt 库，则 Device Shadow 库也会启用，因为它唯一的依赖项是 CoreMqtt 库。
Note
FreeRTOS 内核依赖性是最低要求。如果 FreeRTOS 内核依赖性未满足，CMake 配置将失败。
设置内核移植目标
要创建内核移植目标 AFR::kernel::mcu_port，可使用模块名称 kernel 调用 afr_mcu_port。调用afr_mcu_port 时，为 FreeRTOS 可移植层和驱动程序代码指定目标。创建目标后，可以提供依赖性信息以及 FreeRTOS 可移植层和驱动程序代码信息，供目标使用。
按照说明设置内核移植目标。
设置内核移植目标
1. 为驱动程序代码创建目标。
例如，可以为驱动程序代码创建 STATIC 库目标：
add_library(my_board_driver STATIC ${driver_sources})
# Use your compiler settingstarget_link_libraries( my_board_driver PRIVATE AFR::compiler::mcu_port# Or use your own target if you already have it.# PRIVATE ${compiler_settings_target})
target_include_directories( my_board_driver PRIVATE "include_dirs_for_private_usage" PUBLIC "include_dirs_for_public_interface")
或者，可以为驱动程序代码创建 INTERFACE 库目标：
# No need to specify compiler settings since kernel target has them.add_library(my_board_driver INTERFACE ${driver_sources})
Note
INTERFACE 库目标无构建输出。如果使用的是 INTERFACE 库目标，则驱动程序代码将编译到内核库。
2. 配置 FreeRTOS 可移植层：
add_library(freertos_port INTERFACE)
14
FreeRTOS 移植指南创建 CMake 列表文件
target_sources( freertos_port INTERFACE "${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F/port.c" "${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F/portmacro.h" "${AFR_MODULES_DIR}/freertos_kernel/portable/MemMang/heap_4.c")target_include_directories( freertos_port INTERFACE "${AFR_MODULES_DIR}/freertos_kernel/portable/GCC/ARM_CM4F" "${include_path_to_FreeRTOSConfig_h})
Note
要配置 FreeRTOS 可移植层，也可以在 AFR::kernel::mcu_port 目标中直接指定这些源文件及其包含目录。
3. 创建内核可移植层目标：
# Bring in driver code and freertos portable layer dependency.afr_mcu_port(kernel DEPENDS my_board_driver freertos_port)
# If you need to specify additional configurations, use standard CMake functions with# AFR::kernel::mcu_port as the target name.target_include_directories( AFR::kernel::mcu_port INTERFACE "${additional_includes}" # e.g. board configuration files)target_link_libraries( AFR::kernel::mcu_port INTERFACE "${additional_dependencies}")
4. 要测试列表文件和配置，可以编写一个简单的应用程序以使用 FreeRTOS 内核移植。有关使用 CMake开发和构建 FreeRTOS 应用程序的更多信息，请参阅使用 CMake 构建 FreeRTOS (p. 17)。
5. 创建演示之后，将 add_executable 和 target_link_libraries 调用添加到列表文件，并将内核编译为静态库，以检验内核可移植层的配置是否正确。
add_executable( my_demo main.c)target_link_libraries( my_demo PRIVATE AFR::kernel)
为 FreeRTOS 模块设置移植目标
为内核添加可移植层目标之后，您可以为其他 FreeRTOS 模块添加可移植层目标。
例如，为 Wi-Fi 模块添加可移植层：
afr_mcu_port(wifi)target_sources( AFR::wifi::mcu_port INTERFACE "${AFR_MODULES_DIR}/vendors/vendor/boards/board/ports/wifi/iot_wifi.c"
15
FreeRTOS 移植指南创建 CMake 列表文件
)
此 Wi-Fi 模块可移植层示例只有一个基于驱动程序代码的实施文件。
如果要为 FreeRTOS 安全套接字模块添加可移植层，则该模块依赖于 TLS。这会使其可移植层目标较 Wi-Fi模块的可移植层目标略微复杂。FreeRTOS 提供了基于 mbedTLS 的默认 TLS 实施，您可以与之链接：
afr_mcu_port(secure_sockets)target_sources( AFR::secure_sockets::mcu_port INTERFACE ${portable_layer_sources})target_link_libraries( AFR::secure_sockets::mcu_port AFR::tls)
在此示例代码中，标准 CMake 函数 target_link_libraries 声明安全套接字可移植层依赖于AFR::tls。
可以通过使用目标名称来引用所有 FreeRTOS 模块。AFR::module_name。例如，可以使用相同的语法声明对 FreeRTOS-Plus-TCP 的依赖性：
target_link_libraries( AFR::secure_sockets::mcu_port AFR::freertos_plus_tcp AFR::tls)
Note
如果平台自己处理 TLS，则可直接使用驱动程序代码。如果将驱动程序代码直接用于 TLS，则无需调用target_link_libraries，因为所有 FreeRTOS 模块隐式依赖于包含驱动程序代码的内核。由于所有非内核 FreeRTOS 模块隐式依赖于内核，因此其移植层不需要将内核指定为依赖项。不过，POSIX 模块定义为可选的内核模块。如果要使用 POSIX，则必须将其显式包括在内核可移植层中。例如：
# By default, AFR::posix target does not expose standard POSIX headers in its public# interface, i.e., You need to use "freertos_plus_posix/source/FreeRTOS_POSIX_pthread.c" instead of "pthread.h".# Link to AFR::use_posix instead if you need to use those headers directly.target_link_libraries( AFR::kernel::mcu_port INTERFACE AFR::use_posix)
FreeRTOS 演示和测试
模板文件的最后一个部分定义 FreeRTOS 的演示和测试目标。对于满足依赖性要求的每个演示和测试，会自动创建 CMake 目标。
在本节中，使用 add_executable 函数定义可执行目标。如果要编译测试，则使用 aws_tests 作为目标名称。如果要编译演示，则使用 aws_demos。可能还需要提供其他项目设置，如链接器脚本和构建后命令。例如：
if(AFR_IS_TESTING)
16
FreeRTOS 移植指南创建 CMake 列表文件
set(exe_target aws_tests)else() set(exe_target aws_demos)endif()
set(CMAKE_EXECUTABLE_SUFFIX ".elf")add_executable(${exe_target} "${board_dir}/application_code/main.c")
随后调用 target_link_libraries，将可用的 CMake 演示或测试目标链接到可执行目标。
Note
仍需要修改 aws_demos/config_files/aws_demo_config.h 和 aws_tests/config_files/aws_test_runner_config.h，以启用演示和测试。
运行构建后命令
有关运行构建后命令的信息，请参阅 add_custom_command。使用第二个签名。例如：
# This should run an external command "command --arg1 --arg2".add_custom_command( TARGET ${exe_target} POST_BUILD COMMAND "command" "--arg1" "--arg2")
Note
CMake 支持许多常见的、独立于平台的操作，如创建目录、复制文件等。有关 CMake 命令行操作的更多信息，请参阅 CMake 命令行工具参考。可以使用内置变量 ${CMAKE_COMMAND}，从CMake 列表文件引用 CMake 命令行工具。
使用 CMake 构建 FreeRTOS默认情况下，CMake 将主机操作系统作为目标系统。要使用 CMake 进行交叉编译，您必须提供一个工具链文件以指定要使用的编译器。FreeRTOS 提供了一些默认工具链文件，它位于中freertos/tools/cmake/toolchains。工具链文件的使用说明因您是使用 CMake 命令行界面还是 GUI 而异。生成构建文件（CMake 命令行工具） (p. 17)提供了更多详细信息。要了解有关 CMake 中的交叉编译的更多信息，请访问正式 CMake Wiki 中的交叉编译。
构建基于 CMake 的项目
1. 运行 CMake 为本机构建系统生成构建文件，如 Make 或 Ninja。
可以使用 CMake 命令行工具或 CMake GUI 为本机构建系统生成构建文件。
有关生成 FreeRTOS 构建文件的信息，请参阅生成构建文件（CMake 命令行工具） (p. 17)和生成构建文件 (CMake GUI) (p. 19)。
2. 调用本机构建系统，将项目制作为可执行文件。
有关如何制作 FreeRTOS 构建文件的信息，请参阅使用生成的构建文件构建 FreeRTOS 构建 (p. 21)。
生成构建文件（CMake 命令行工具）
可以使用 CMake 命令行工具 (cmake）以从命令行为 FreeRTOS 生成构建文件。
要生成构建文件，您必须指定目标主板、编译器以及源代码和构建目录的位置。使用-DVENDOR选项。使用-DCOMPILER 选项指定编译器。使用 -S 开关指定源代码的位置，并使用 -B 开关指定生成的构建文件的位置。
17
FreeRTOS 移植指南创建 CMake 列表文件
Note
编译器必须包含在系统的 PATH 变量中，否则您必须指定编译器的位置。
例如，如果供应商是 Texas Instruments，主板是 CC3220 Launchpad，编译器是 GCC for ARM，则您可以发出以下命令，从当前目录中的源文件构建到名为 build-directory 的目录：
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory
Note
如果使用的是 Windows，则必须指定本机构建系统，因为 CMake 默认使用 Visual Studio。例如：
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G Ninja
或者:
cmake -DVENDOR=ti -DBOARD=cc3220_launchpad -DCOMPILER=arm-ti -S . -B build-directory -G "MinGW Makefiles"
正则表达式 ${VENDOR}.* 和 ${BOARD}.* 用于搜索匹配的主板，因此对于 VENDOR 和 BOARD 选项，不必使用完整的供应商和主板名称。在只有单个名称匹配的情况下，部分名称也是可行的。例如，以下命令可从同一源文件生成相同的构建文件：
cmake -DVENDOR=ti -DCOMPILER=arm-ti -S . -B build-directory
cmake -DBOARD=cc3220 -DCOMPILER=arm-ti -S . -B build-directory
cmake -DVENDOR=t -DBOARD=cc -DCOMPILER=arm-ti -S . -B build-directory
如果要使用不在默认目录 cmake/toolchains 中的工具链文件，则可使用 CMAKE_TOOLCHAIN_FILE 选项。例如：
cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -S . -B build-directory
如果工具链文件未使用编译器的绝对路径，并且编译器未添加到 PATH 环境变量中，那么 CMake 可能无法找到编译器。要确保 CMake 找到工具链文件，可以使用 AFR_TOOLCHAIN_PATH 选项。此选项将搜索指定的工具链目录路径以及 bin 下的工具链子文件夹。例如：
cmake -DBOARD=cc3220 -DCMAKE_TOOLCHAIN_FILE='/path/to/toolchain_file.cmake' -DAFR_TOOLCHAIN_PATH='/path/to/toolchain/' -S . -B build-directory
要启用调试，可将 CMAKE_BUILD_TYPE 设置为 debug。启用此选项后，CMake 将调试标志添加到编译选项，并构建带调试符号的 FreeRTOS。
# Build with debug symbolscmake -DBOARD=cc3220 -DCOMPILER=arm-ti -DCMAKE_BUILD_TYPE=debug -S . -B build-directory
也可以将 CMAKE_BUILD_TYPE 设置为 release，将优化标志添加到编译选项。
18
FreeRTOS 移植指南创建 CMake 列表文件
生成构建文件 (CMake GUI)
可以使用 CMake GUI 生成 FreeRTOS 构建文件。
使用 CMake GUI 生成构建文件
1. 从命令行中发出 cmake-gui 以启动 GUI。2. 选择 Browse Source (浏览源) 并指定源输入，然后选择 Browse Build (浏览构建) 并指定构建输出。
3. 选择 Configure (配置)，然后在 Specify the build generator for this project (指定此项目的构建生成器)下，查找并选择构建系统，以用于构建所生成的构建文件。
Note
如果未显示弹出窗口，则您可能正在重用现有的构建目录。在这种情况下，首先通过单击菜单中的 File -> Delete Cache (文件 -> 删除缓存) 来删除 CMake 缓存。
4. 选择 Specify toolchain file for cross-compiling (指定用于交叉编译的工具链文件)，然后选择 Next (下一步)。
5. 选择工具链文件（例如，freertos/tools/cmake/toolchains/arm-ti.cmake），然后选择Finish (完成)。
19
FreeRTOS 移植指南创建 CMake 列表文件
FreeRTOS 的默认配置为模板主板，该主板不提供任何可移植层目标。此时将显示一个窗口，其中显示消息 Error in configuration process (配置过程出错)。
Note
如果您看到以下错误消息：
CMake Error at tools/cmake/toolchains/find_compiler.cmake:23 (message):Compiler not found, you can specify search path with "AFR_TOOLCHAIN_PATH".
这意味着编译器不在您的环境变量 PATH 中。您可以在 GUI 中设置 AFR_TOOLCHAIN_PATH变量，向 CMake 提供编译器的安装位置。如果您未看到 AFR_TOOLCHAIN_PATH 变量，请单击弹出窗口中的 Add Entry (添加条目) 按钮，输入 AFR_TOOLCHAIN_PATH 作为 name (名称)，选择 PATH 作为 type (类型)，并在 value (值) 中输入编译器路径，例如“C:/toolchains/arm-none-eabi-gcc”。
6. GUI 现在应如下所示：
选择 AFR_BOARD，选择主板，然后选择 Configure (配置)。
20
FreeRTOS 移植指南创建 CMake 列表文件
7. 选择 Generate (生成)。CMake 生成构建系统文件（例如，makefile 或 ninja 文件），这些文件位于第一步指定的构建目录中。按照下一节中的说明生成二进制映像。
使用生成的构建文件构建 FreeRTOS 构建
可以使用本机构建系统构建，方法是从输出二进制目录调用构建系统命令。例如，如果构建文件输出目录为build-directory，并且您使用 Make 作为本机构建系统，则可运行以下命令：
cd build-directory make -j4
也可以使用 CMake 命令行工具构建 FreeRTOS。CMake 提供了抽象层用于调用本机构建系统。例如：
cmake --build build-directory
以下是 CMake 命令行工具构建模式的其他一些常见用例：
# Take advantage of CPU cores.cmake --build build-directory --parallel 8
# Build specific targets.cmake --build build-directory --target afr_kernel
# Clean first, then build.cmake --build build-directory --clean-first
有关 CMake 构建模式的更多信息，请参阅 CMake 文档。
21
FreeRTOS 移植指南
移植 FreeRTOS 库开始移植之前，按照为移植设置 FreeRTOS 源代码 (p. 7)中的说明进行操作。
要将 FreeRTOS 移植到您的设备，请按照以下主题中的说明操作。
1. 实现 configPRINT_STRING() 宏 (p. 25)2. 配置 FreeRTOS 内核移植 (p. 25)3. 移植 Wi-Fi 库 (p. 27)
Note
如果设备不支持 Wi-Fi，则可改用以太网连接来连接到 AWS 云。FreeRTOS Wi-Fi 库并不是必需的。
4. 移植 TCP/IP 堆栈 (p. 32)5. 移植安全套接字库 (p. 36)6. 移植代码库 (p. 43)7. 移植 TLS 库 (p. 47)8. 配置 CoremQTT 库以进行测试 (p. 64)9. 配置核心 HTTP 库以进行测试 (p. 65)10.移植 OTA 库 (p. 66)
Note
目前，资格认证无需移植 FreeRTOS OTA 更新库。11.移植低功耗蓝牙库 (p. 72)
Note
目前，资格认证无需移植 FreeRTOS 低功耗蓝牙库。12.使用低功耗蓝牙执行无线更新 (p. 76)
Note
目前，AWS IoT 设备测试程序不支持使用低功耗蓝牙库进行无线更新的鉴定。对此资格感兴趣的合作伙伴应通过 APN（AWS 合作伙伴网络）团队联系 AWS。
13.移植通用 I/O 库 (p. 84)
Note
目前，资格认证无需移植 FreeRTOS 常用 I/O 库。14.移植移植移植移植库 (p. 93)
Note
目前，资格认证无需移植 FreeRTOS 移植移植移植移植 FreeRTOS 移植移植移植移
将 FreeRTOS 移植到您的主板后，可以使用适用于 FreeRTOS 的 AWS IoT Device Tester，对资格认证的端口进行正式验证。有关适用于 FreeRTOS 的 AWS IoT Device Tester 的更多信息，请参阅使用适用于FreeRTOS 的 AWS IoT Device Tester（在用户指南中）。22
FreeRTOS 移植指南移植流程图
Note
您在使用适用于 FreeRTOS 的 AWS IoT Device Tester 验证 FreeRTOS 端口之前，必须删除您可能已在用于测试的代码中插入的日志记录消息，否则该验证可能会失败。
有关您的设备使用 FreeRTOS 的资格认证的信息，请参阅FreeRTOS 资格认证指南。
FreeRTOS 移植流程图使用以下流程图，在将 FreeRTOS 移植到您的设备时作为可视化帮助。
23
FreeRTOS 移植指南移植流程图
24
FreeRTOS 移植指南configPRINT_STRING()
实现 configPRINT_STRING() 宏您必须实施configPRINT_STRING()宏，然后再移植 FreeRTOS 库。FreeRTOS 使用configPRINT_STRING()将测试结果输出为人类可读的 ASCII 字符串。
Prerequisites要实现 configPRINT_STRING() 宏，需要具备以下条件：
• 支持 UART 或虚拟 COM 端口输出的开发主板。• 针对您的平台配置的 FreeRTOS 项目以及移植测试 IDE 项目。
有关信息，请参阅 为移植设置 FreeRTOS 源代码 (p. 7)。
Implementation实现 configPRINT_STRING()
1. 将您的设备连接至终端仿真器以输出测试结果。2. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c
文件，然后在 prvMiscInitialization() 函数中找到对 configPRINT_STRING("TestMessage") 的调用。
3. 在对 configPRINT_STRING("Test Message") 的调用之前，添加使用供应商提供的 UART 驱动程序的代码，以将 UART 波特率级别初始化为 115200。
4. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSConfig.h，然后找到 configPRINT_STRING() 的空定义。该宏使用以 NULL 终止的ASCII C 字符串作为其唯一参数。
5. 更新 configPRINT_STRING() 的空定义，使其调用供应商提供的 UART 输出函数。
例如，假设 UART 输出函数具有以下原型：
void MyUARTOutput( char *DataToOutput, size_t LengthToOutput );
您可以将 configPRINT_STRING() 实现为：
#define configPRINT_STRING( X ) MyUARTOutput( (X), strlen( (X) ) )
Testing构建并执行测试演示项目。如果 Test Message 显示在 UART 控制台中，说明已正确连接和配置该控制台、configPRINT_STRING() 可正常工作并且测试已完成。您可以从 prvMiscInitialization() 中删除对 configPRINT_STRING("Test Message") 的调用。
实现 configPRINT_STRING() 宏后，您可以开始为您的设备配置 FreeRTOS 内核移植。有关说明，请参阅配置 FreeRTOS 内核移植 (p. 25)。
配置 FreeRTOS 内核移植此部分提供有关将 FreeRTOS 内核移植集成到 FreeRTOS 移植测试项目的说明。有关可用内核移植的列表，请参阅 FreeRTOS 内核移植。
25
FreeRTOS 移植指南Prerequisites
FreeRTOS 使用 FreeRTOS 内核支持多任务处理和任务间通信。有关更多信息，请参阅 。FreeRTOS 内核基础知识在 FreeRTOS 用户指南和自由投资。
Note
将 FreeRTOS 内核移植到新架构不在本文档的讨论范围内。如果您对将 FreeRTOS 内核移植到新架构感兴趣，请联系 FFreeRTOS 工程团队。对于 FreeRTOS 资格认证计划，仅支持现有端口。资格认证计划中不接受对这些端口进行修改。只接受可以从 GitHub 或 Sourceforge 下载的官方端口。
Prerequisites要设置 FreeRTOS 内核以进行移植，需要具备以下条件：
• 用于目标平台的正式 FreeRTOS 内核移植。• 一个 IDE 项目或 CMakeLists.txt 列表文件，其中包括用于目标平台和编译器的正确 FreeRTOS 内核移
植文件。
有关设置测试项目的信息，请参阅为移植设置 FreeRTOS 源代码 (p. 7)。• configPRINT_STRING() 宏针对您设备的实施。
有关实施 configPRINT_STRING() 的信息，请参阅 实现 configPRINT_STRING() 宏 (p. 25)。
配置 FreeRTOS 内核freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSConfig.h 标头文件为 FreeRTOS 内核指定应用程序特定的配置设置。有关每个配置选项的说明，请参阅 FreeRTOS.org上的自定义。
要将 FreeRTOS 内核配置为可使用您的设备，请打开 FreeRTOSConfig.h，并验证是否已为您的平台正确指定下表中的配置选项。
配置选项 描述
configCPU_CLOCK_HZ 指定用于生成时钟周期中断的时钟频率。
configMINIMAL_STACK_SIZE 指定最小堆栈大小。作为起点，可将其设置为在正式 FreeRTOS 演示中、为要使用的 FreeRTOS内核移植使用的值。正式 FreeRTOS 演示是指通过 FreeRTOS.org 网站发布的演示。确保将堆栈溢出检查设置为 2，并在发生溢出时增加configMINIMAL_STACK_SIZE。为节省 RAM，将堆栈大小设置为不会导致堆栈溢出的最小值。
configTOTAL_HEAP_SIZE 设置 FreeRTOS 堆的大小。与任务堆栈大小一样，可以调整堆大小以确保未使用的堆空间不会消耗RAM。
Note
如果您正在移植 ARM Cortex-M3、M4 或 M7 设备，还必须正确地指定 configPRIO_BITS 和configMAX_SYSCALL_INTERRUPT_PRIORITY。
26
FreeRTOS 移植指南Testing
Testing1. 打开 /libraries/freertos_plus/standard/utils/src/iot_system_init.c，然后注释掉
从 SYSTEM_Init() 函数中调用 SOCKETS_Init() 的行。此初始化函数属于您尚未移植的库。此库的移植部分包括用于取消注释此函数的说明。
2. 构建测试项目，然后将其刷写到您的设备以执行该项目。3. 如果“.”每 5 秒钟在 UART 控制台上显示一次，则 FreeRTOS 内核已正确配置且测试已完成。
打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSConfig.h，然后将 configUSE_IDLE_HOOK 设置为 0，以停止内核执行vApplicationIdleHook() 和输出“.”。
4. 如果“.”以 5 秒钟以外的任何频率显示，打开 FreeRTOSConfig.h 并验证 configCPU_CLOCK_HZ 是否设置为适合您主板的正确值。
为您的设备配置 FreeRTOS 内核移植后，即可开始移植 Wi-Fi 库。有关说明，请参阅移植 Wi-Fi库 (p. 27)。
移植 Wi-Fi 库FreeRTOS Wi-Fi 库与供应商提供的 Wi-Fi 驱动程序接口。有关 FreeRTOS Wi-Fi 库的更多信息，请参阅FreeRTOS Wi-Fi 库（在 FreeRTOS 用户指南中）。
如果设备不支持 Wi-Fi 联网，则可跳过移植 FreeRTOS Wi-Fi 库，开始移植 TCP/IP 堆栈 (p. 32)。
Note
要进行资格认证，设备必须连接到 AWS 云。如果设备不支持 Wi-Fi，则可改用以太网连接。FreeRTOS Wi-Fi 库并不是必需的。
Prerequisites要移植 Wi-Fi 库，需要具备以下条件：
• 包括供应商提供的 Wi-Fi 驱动程序在内的 IDE 项目或 CMakeLists.txt 列表文件。
有关设置测试项目的信息，请参阅为移植设置 FreeRTOS 源代码 (p. 7)。• FreeRTOS 内核的经验证配置。
有关为您的平台配置 FreeRTOS 内核的信息，请参阅配置 FreeRTOS 内核移植 (p. 25)。• 两个无线接入点。
Portingfreertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c 包含一组 Wi-Fi 管理函数的空定义。可使用供应商提供的 Wi-Fi 驱动程序库，至少实施下表中列出的函数。
函数 描述
WIFI_On 打开 Wi-Fi 模块并初始化驱动程序。
27
FreeRTOS 移植指南Testing
函数 描述
WIFI_ConnectAP 连接到 Wi-Fi 接入点 (AP)。
WIFI_Disconnect 从 AP 断开。
WIFI_Scan 执行 Wi-Fi 网络扫描。
WIFI_GetIP 检索 Wi-Fi 接口的 IP 地址。
WIFI_GetMAC 检索 Wi-Fi 接口的 MAC 地址。
WIFI_GetHostIP 使用 DNS 从主机名检索主机 IP 地址。
freertos/libraries/abstractions/wifi/include/iot_wifi.h 提供实施这些函数所需的信息。
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置 Wi-Fi 库
1. 将源文件 freertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c 添加到aws_tests IDE 项目中。
2. 将源文件 aws_test_wifi.c 添加到 aws_tests IDE 项目中。
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
有关示例，请参阅以下 Wi-Fi 库的可移植层目标定义。
# WiFiafr_mcu_port(wifi)target_sources( AFR::wifi::mcu_port INTERFACE "freertos/vendors/vendor/boards/board/ports/wifi/iot_wifi.c")
设置本地测试环境在 IDE 项目中设置库后，您需要配置一些其他文件以进行测试。
28
FreeRTOS 移植指南Testing
配置 Wi-Fi 测试的源文件和标头文件
1. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c，然后在 vApplicationDaemonTaskStartupHook(void) 和 prvWifiConnect(void) 的函数定义中删除 #if 0 和 #endif 编译器指令。
2. 如果尚未移植安全套接字库，则打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c，然后注释掉调用 SOCKETS_Init() 的行。当您浏览至移植安全套接字库 (p. 36)部分时，该部分将指导您如何取消注释此初始化函数调用。
3. 打开 freertos/tests/include/aws_clientcredential.h，然后为第一个 AP 设置下表中的宏。
宏 值
clientcredentialWIFI_SSID 作为 C 字符串的 Wi-Fi SSID（用引号引起）。
clientcredentialWIFI_PASSWORD 作为 C 字符串的 Wi-Fi 密码（用引号引起）。
clientcredentialWIFI_SECURITY 下列情况之一：
• eWiFiSecurityOpen
• eWiFiSecurityWEP
• eWiFiSecurityWPA
• eWiFiSecurityWPA2
推荐使用 eWiFiSecurityWPA2。
4. 打开 freertos/libraries/abstractions/wifi/test/aws_test_wifi.h，然后为第二个 AP设置下表中的宏。
宏 值
testWIFI_SSID 作为 C 字符串的 Wi-Fi SSID（用引号引起）。
testWIFI_PASSWORD 作为 C 字符串的 Wi-Fi 密码（用引号引起）。
testWIFI_SECURITY 下列情况之一：
• eWiFiSecurityOpen
• eWiFiSecurityWEP
• eWiFiSecurityWPA
• eWiFiSecurityWPA2
推荐使用 eWiFiSecurityWPA2。
5. 要启用 Wi-Fi 测试，请打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h 并将 testrunnerFULL_WIFI_ENABLED 设置为1。
Important
以下测试需要移植安全套接字库并运行回声服务器：
• WiFiConnectionLoop
• WiFiIsConnected
• WiFiConnectMultipleAP
29
FreeRTOS 移植指南Testing
在移植安全套接字库并启动回声服务器之前，将无法通过这些测试。在移植安全套接字库并启动回声服务器之后，重新运行 Wi-Fi 测试，以确保所有测试均已通过。有关移植安全套接字库的信息，请参阅移植安全套接字库 (p. 36)。有关设置回声服务器的信息，请参阅设置 Echo服务器 (p. 40)。
运行测试执行 Wi-Fi 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
...
30
FreeRTOS 移植指南Validation
Validation要正式对设备进行 FreeRTOS 资格认证，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
31
FreeRTOS 移植指南TCP/IP
将 FreeRTOS Wi-Fi 库移植到设备之后，可以开始移植 TCP/IP 堆栈。有关说明，请参阅移植 TCP/IP 堆栈 (p. 32)。
移植 TCP/IP 堆栈FreeRTOS 为没有板载 TCP/IP 功能的主板提供了 TCP/IP 堆栈。如果您的平台将 TCP/IP 功能分载到单独的网络处理器或模块，您可以跳过此移植部分并开始移植安全套接字库 (p. 36)。
FreeRTOS+TCP 是 FreeRTOS 内核的原生 TCP/IP 堆栈。FreeRTOS 工程团队维护 FreeRTOS，是推荐与FreeRTOS 一起使用的 TCP/IP 堆栈。有关更多信息，请参阅 移植 FreeRTOS+TCP (p. 32)。
轻型 IP(lwIP) TCP/IP 堆栈是一个开源的第三方 TCP/IP 堆栈，移植到了 FreeRTOS 内核。lwIP 移植层当前支持 lwIP 版本 2.1.2。有关更多信息，请参阅 移植 lwIP (p. 34)。
Note
这些移植部分仅提供有关移植到平台的以太网或 Wi-Fi 驱动程序的说明。这些测试仅确保以太网或Wi-Fi 驱动程序可以连接到网络。在移植了安全套接字库之前，您不能在网络上测试发送和接收数据。
移植 FreeRTOS+TCPFreeRTOS+TCP 是 FreeRTOS 内核的原生 TCP/IP 堆栈。有关更多信息，请参阅 FreeRTOS.org。
Prerequisites要移植 FreeRTOS+TCP 库，您需要以下信息：
• 包括供应商提供的以太网或 Wi-Fi 驱动程序在内的 IDE 项目或 CMakeLists.txt 列表文件。
有关设置测试项目的信息，请参阅为移植设置 FreeRTOS 源代码 (p. 7)。• FreeRTOS 内核的经验证配置。
有关为您的平台配置 FreeRTOS 内核的信息，请参阅配置 FreeRTOS 内核移植 (p. 25)。
Porting在开始移植 FreeRTOS-TCP 库之前，请检查 freertos/libraries/freertos_plus/standard/freertos_plus_tcp/portable/NetworkInterface 目录以确定是否已具有到您的设备的移植。
如果移植不存在，请执行以下操作：
1. 按照 FreeRTOS.org 上将 FreeRTOS+TCP 移植到不同微控制器的说明，将 FreeRTOS+TCP 移植到您的设备。
2. 如有必要，请按照 FreeRTOS.org 上将 FreeRTOS+TCP 移植到新的嵌入式 C 编译器的说明，将FreeRTOS+TCP 移植到新的编译器。
3. 在名为 NetworkInterface.c 的文件中实施使用供应商提供的以太网或 Wi-Fi 驱动程序的新移植，并将该文件保存到 freertos/libraries/freertos_plus/standard/freertos_plus_tcp/portable/NetworkInterface/board_family 中。
Note
freertos/libraries/freertos_plus/standard/freertos_plus_tcp/portable/BufferManagement 目录中的文件由多个移植使用。请勿编辑此目录中的文件。
32
FreeRTOS 移植指南移植 FreeRTOS+TCP
在创建移植后，或者如果移植已存在，请打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSIPConfig.h 并编辑配置选项，以使它们适合您的平台。有关配置选项的更多信息，请参阅 FreeRTOS.org 上的 FreeRTOS+TCP 配置。
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目
如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置 FreeRTOS+TCP 库
1. 将 freertos/libraries/freertos_plus/standard/freertos_plus_tcp 及其子目录中的所有源文件和标头文件添加到 aws_tests IDE 项目中。
Note
FreeRTOS 在 freertos/freertos_kernel/portable/MemMang 中包含 5 个示例堆管理实施。FreeRTOS+TCP 和 BufferAllocation_2.c 需要 heap_4.c 或 heap_5.c 实施。您必须使用heap_4.c或者heap_5.c以确保 FreeRTOS 演示应用程序正常运行。请勿使用自定义堆栈实施。
2. 将 freertos/libraries/freertos_plus/standard/freertos_plus_tcp/include 添加到编译器的包含路径中。
配置 CMakeLists.txt 文件
如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
设置本地测试环境
在 IDE 项目中设置库后，您需要配置一些其他文件以进行测试。
为 TCP 测试配置源文件和标头文件
1. 如果您尚未移植安全套接字库，请打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c，并在函数 SYSTEM_Init() 中注释掉调用 SOCKETS_Init() 的行。当您浏览至移植安全套接字库 (p. 36)部分时，该部分将指导您如何取消注释此初始化函数调用。
2. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c，然后取消注释对 FreeRTOS_IPInit() 的调用。
3. 使用您网络的有效值填写以下数组：
变量 描述
uint8_t ucMACAddress[ 6 ] 默认 MAC 地址配置。
33
FreeRTOS 移植指南移植 lwIP
变量 描述
uint8_t ucIPAddress[ 4 ] 默认 IP 地址配置。
Note
默认情况下，由 DHCP 获取 IP 地址。如果 DHCP 失败，或者如果您不想使用 DHCP，则使用此处定义的静态 IP 地址。要禁用 DHCP，请打开freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSIPConfig.h，并将设置为ipconfigUSE_DHCP到0。对于演示，ipconfigUSE_DHCP定义为freertos/vendors/vendor/boards/board/aws_demos/config_files/FreeRTOSIPConfig.h。
uint8_t ucNetMask[ 4 ] 默认网络掩码配置。
uint8_t ucGatewayAddress[ 4 ] 默认网关地址配置。
uint8_t ucDNSServerAddress[ 4 ] 默认 DNS 服务器地址配置。
4. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/FreeRTOSIPConfig.h，并将宏 ipconfigUSE_NETWORK_EVENT_HOOK 设置为 1。
5. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c，然后将以下代码添加到 vApplicationIPNetworkEventHook() 的函数定义开头：
if (eNetworkEvent == eNetworkUp){ configPRINT("Network connection successful. \n\r");}
运行测试执行 FreeRTOS+TCP 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。如果 Network connection successful 显示，则以太网或 Wi-
Fi 驱动程序成功连接到网络，测试完成。
Validation要正式对设备进行 FreeRTOS 资格认证，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
移植 lwIPlwIP 是替代的开源 TCP/IP 堆栈。有关更多信息，请参阅 lwIP – 轻型 TCP/IP 堆栈 – 摘要。FreeRTOS 目前支持版本 2.1.2。
34
FreeRTOS 移植指南移植 lwIP
Prerequisites要移植 lwIP 堆栈，需要以下内容：
• 包括供应商提供的网络驱动程序在内的 IDE 项目或 CMakeLists.txt 列表文件。• FreeRTOS 内核的经验证配置。
有关为您的平台配置 FreeRTOS 内核的信息，请参阅配置 FreeRTOS 内核移植 (p. 25)。
Porting在将 lwIP TCP/IP 堆栈移植到您的设备之前，请检查 freertos/libraries/3rdparty/lwip/src/portable 目录以确定是否已具有到您的平台的移植。
1. 如果移植不存在，请执行以下操作：
在freertos/libraries/3rdparty/lwip/src/portable中，创建一个名为的目录。vendor/board/netif其中，其中，vendor 和board目录与您的平台匹配。
2. 根据存根文件中的注释移植 freertos/libraries/3rdparty/lwip/src/netif/ethernetif.c存根文件。
3. 在您创建移植之后，或者如果移植已存在，请在测试项目的 main.c 文件中，添加对 tcpip_init()的调用。
4. 在 freertos/vendors/vendor/boards/board/aws_tests/config_files 中，创建一个名为lwipopts.h 的配置文件。此文件必须包含以下行：
#include "arch/lwipopts_freertos.h"
该文件还应包含任何特定于平台的配置选项。
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
Note
没有特定于 lwIP 的 TCP/IP 移植测试。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
设置 IDE 项目中的 lwIP 源文件
1. 将 lwip/src 及其子目录中的所有源文件和标头文件添加到 aws_tests IDE 项目中。Note
如果您将 .c 文件添加到 IDE 项目，然后为移植编辑该 .c 文件，则您必须将原始 .c 文件替换为在 IDE 项目中编辑过的文件。
2. 将以下路径添加到编译器的包含路径：
• freertos/libraries/3rdparty/lwip/src/include
35
FreeRTOS 移植指南安全套接字
• freertos/libraries/3rdparty/lwip/src/portable
• freertos/libraries/3rdparty/lwip/src/portable/vendor/board/include
配置 CMakeLists.txt 文件
如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
FreeRTOS+TCP TCP/IP 堆栈和 lwIP 堆栈已存在安全套接字库实施。如果您使用的是 FreeRTOS+TCP 或lwIP，则您不需要移植安全套接字库。在您完成将 FreeRTOS+TCP 堆栈或 lwIP 堆栈移植到设备之后，您可以启动 移植代码库 (p. 43)。即使您不需要为安全套接字库创建移植，要让安全套接字库具备资格，您的平台仍需要通过 AWS IoT Device Tester 测试。
移植安全套接字库您可以使用 FreeRTOS 安全套接字库来创建和配置 TCP 套接字、连接到 MQTT 代理以及发送和接收 TCP数据。安全套接字库还封装 TLS 功能。创建 TLS 保护的套接字只需要标准 TCP 套接字。有关更多信息，请参阅 。FreeRTOS 安全套接字库（在 FreeRTOS 用户指南中）。
FreeRTOS 包括一个安全套接字实现FreeRTOS+TCP和轻量级 IP (LWIP)TCP/IP 堆栈，与mbedTLS。如果您使用的是 FreeRTOS+TCP 或 lwIP TCP/IP 堆栈，则不需要移植安全套接字库。
Note
• 即使您不需要创建安全套接字库的移植，您的平台仍必须通过安全套接字库的资格认证测试。资格认证基于 AWS IoT Device Tester 的结果。
• 您的 TLS 实现应该支持AWS IoT 支持的 TLS 密码套件。• 如果修改安全套接字库的 TLS 配置，当您尝试连接到 echo 服务器时，这可能会导致失败。并非
echo 服务器支持的所有密码套件都受到安全套接字库的支持，如果启用了库当前不支持的密码套件（例如 SHA384），则可能无法连接。
• 如果您的平台将 TCP/IP 功能分载到单独的网络芯片，则需要将 FreeRTOS 安全套接字库移植到您的设备。
Prerequisites要移植安全套接字库，您需要以下信息：
• Wi-Fi 库的移植（仅当您使用 Wi-Fi 网络连接时需要）。
有关移植 Wi-Fi 库的信息，请参阅移植 Wi-Fi 库 (p. 27)。• 如果您的主板具有蜂窝移动网络连接，则必须提供将蜂窝移动调制解调器用作传输的安全套接字库。您可
以通过以下两种方式实施安全套接字库：• 通过直接使用调制解调器的 AT 命令来实现安全套接字 API。• 使用 FreeRTOS 提供的蜂窝网络库，它隐藏 AT 命令并提供类似套接字的 API。有关更多信息，请参阅
移植移植移植移植库 (p. 93)。• 移植 TCP/IP 堆栈。
有关移植 TCP/IP 堆栈的信息，请参阅移植 TCP/IP 堆栈 (p. 32)。
36
FreeRTOS 移植指南Porting
• Echo 服务器。
FreeRTOS 包含一个使用 Go 编写的 Echo 服务器，在freertos/tools/echo_server目录。有关更多信息，请参阅 设置 Echo 服务器 (p. 40)。
Porting如果您的平台将 TCP/IP 功能分载到单独的网络芯片，则需要实施在 freertos/vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c 中具有存根的所有函数。
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置安全套接字库
1. 如果使用 FreeRTOS+TCP TCP/IP 堆栈，请将 freertos/libraries/abstractions/secure_sockets/freertos_plus_tcp/iot_secure_sockets.c 添加到 aws_tests IDE 项目中。
如果使用 lwIP TCP/IP 堆栈，请将 freertos/libraries/abstractions/secure_sockets/lwip/iot_secure_sockets.c 添加到 aws_tests IDE 项目中。
如果使用您自己的 TCP/IP 端口，请将 freertos/vendors/vendor/boards/board/ports/secure_sockets/iot_secure_sockets.c 添加到 aws_tests IDE 项目中。
2. 将 secure_sockets/test/aws_test_tcp.c 添加到 aws_tests IDE 项目。
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
有关示例，请参阅以下安全套接字库的可移植层目标定义。
# Secure socketsafr_mcu_port(secure_sockets)# Link to AFR::secure_sockets_freertos_tcp if you want use default implementation based on# FreeRTOS-Plus-TCP.target_link_libraries(AFR::pkcs11::mcu_portINTERFACE AFR::secure_sockets_freertos_tcp)# Or provide your own implementation.target_sources(AFR::secure_sockets::mcu_port
37
FreeRTOS 移植指南Testing
INTERFACE "$path/iot_secure_sockets.c")
设置本地测试环境在 IDE 项目中设置库后，您需要配置一些其他文件以进行测试。
为安全套接字测试配置源文件和标头文件
1. 打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c，并在函数 SYSTEM_Init() 中，确保注释掉调用 SOCKETS_Init() 的行。
2. 启动 Echo 服务器。
如果尚未将 TLS 库移植到您的平台，则只能使用不安全的 Echo 服务器 (freertos/tools/echo_server/echo_server.go) 测试安全套接字移植。有关设置和运行不安全的 Echo 服务器的说明，请参阅设置 Echo 服务器 (p. 40)。
3. 在 aws_test_tcp.h 中，将 IP 地址设置为服务器的正确值。例如，如果您的服务器的 IP 地址是192.168.2.6，请在 aws_test_tcp.h 中设置以下值：
宏 值
tcptestECHO_SERVER_ADDR0 192
tcptestECHO_SERVER_ADDR1 168
tcptestECHO_SERVER_ADDR2 2
tcptestECHO_SERVER_ADDR3 6
4. 打开 aws_test_tcp.h，将 tcptestSECURE_SERVER 宏设置为 0 以不使用 TLS 运行安全套接字测试。
5. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner.config.h，然后将 testrunnerFULL_TCP_ENABLED 宏设置为 1 以启用套接字测试。
6. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c，然后删除 vApplicationIPNetworkEventHook ( void ) 定义中的 #if 0 和 #endif 编译器指令以启用测试任务。
Note
此更改需要移植剩余的库。
Important
对于资格认证，您必须使用 TLS 通过安全套接字测试。移植 TLS 库之后，在启用 TLS 的情况下返回安全套接字测试，使用支持 TLS 的 Echo 服务器。要移植 TLS 库，请参阅移植 TLS 库 (p. 47)。
在移植 TLS 库之后为安全套接字设置测试
1. 启动安全的 Echo 服务器。
有关信息，请参阅 设置 Echo 服务器 (p. 40)。2. 将 freertos/tests/include/aws_test_tcp.h 中的 IP 地址和端口设置为适用于您的服务器的
值。例如，如果您的服务器的 IP 地址为 192.168.2.6，并且服务器侦听 9000，请在 freertos/tests/include/aws_test_tcp.h 中设置以下值：
38
FreeRTOS 移植指南Testing
宏 值
tcptestECHO_SERVER_TLS_ADDR0 192
tcptestECHO_SERVER_TLS_ADDR1 168
tcptestECHO_SERVER_TLS_ADDR2 2
tcptestECHO_SERVER_TLS_ADDR3 6
tcptestECHO_PORT_TLS 9000
3. 打开 freertos/tests/include/aws_test_tcp.h，然后将 tcptestSECURE_SERVER 宏设置为1 以启用 TLS 测试。
4. 下载受信任的根证书。有关接受的根证书和下载链接的信息，请参阅服务器身份验证（在 AWS IoT 开发人员指南中）。我们建议您使用 Amazon Trust Services 证书。
5. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/PEMfileToCString.html。
6. 在 PEM Certificate or Key (PEM 证书或密钥) 中，选择您下载的根 CA 文件。7. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到
aws_clientcredential_keys.h 中设置了格式的 PEM 字符串，然后复制证书字符串。8. 打开 aws_test_tcp.h，然后将设置了格式的证书字符串粘贴到 tcptestECHO_HOST_ROOT_CA 的定
义中。9. 在 freertos/tools/echo_server/readme-gencert.txt 中使用第二组 OpenSSL 命令生成由证
书颁发机构签名的客户端证书和私有密钥。证书和密钥使得自定义 Echo 服务器可以信任在 TLS 身份验证期间设备呈现的客户端证书。
10. 使用 freertos/tools/certificate_configuration/PEMfileToCString.html 格式工具设置证书和密钥格式。
11. 在设备上构建和运行测试项目之前，打开 aws_clientcredential_keys.h，并将 PEM 格式的客户端证书和私有密钥复制到 keyCLIENT_CERTIFICATE_PEM 和 keyCLIENT_PRIVATE_KEY_PEM 的定义中。
运行测试执行安全套接字测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
...
39
FreeRTOS 移植指南Validation
如果通过所有测试，则测试完成。
Validation要正式使用 FreeRTOS，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester，用于 FreeRTOS在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
完成将 FreeRTOS 安全套接字库移植到设备之后，您可以开始移植 CorepKCS11 库。有关说明，请参阅移植代码库 (p. 43)。
设置 Echo 服务器这些区域有：freertos/tools/echo_server/目录具有用于基于 Go 的 Echo 服务器的源代码，您可以使用该服务器在 FreerTos 上测试 TCP。您可以在 freertos/libraries/abstractions/secure_sockets/test/iot_test_tcp.c 文件中找到 TCP 测试。按照本节中的说明设置并运行 Echo服务器。
Prerequisites要运行 TLS Echo 服务器，您必须安装以下内容：
• Go — 您可以从下载最新版本golang.org。• OpenSSL — 有关 Linux 源代码下载的信息，请参阅Opensl.org。您还可以使用程序包管理器来安装适用
于 Linux 和 macOS 的 OpenSSL。
创建凭证完成先决条件后，必须输入以下命令才能创建凭证。
Server
以下 openssl 命令生成自签名服务器证书。
40
FreeRTOS 移植指南设置 Echo 服务器
RSA
openssl req -newkey rsa:2048 -nodes -x509 -sha256 -out certs/server.pem -keyout certs/server.key -days 365 -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"
EC
openssl req -new -x509 -nodes -newkey ec:<(openssl ecparam -name prime256v1) -keyout certs/server.key -out certs/server.pem -days 365 -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"
客户端
以下 openssl 命令生成客户端证书。RSA
openssl genrsa -out certs/client.key 2048openssl req -new -key certs/client.key -out certs/client.csr -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"openssl x509 -req -in certs/client.csr -CA certs/server.pem -CAkey certs/server.key -CAcreateserial -out certs/client.pem -days 365 -sha256
EC
ecparam -genkey -name prime256v1 -out certs/client.key openssl req -new -key certs/client.key -out certs/client.csr -subj "/C=US/ST=WA/L=Place/O=YourCompany/OU=IT/CN=www.your-company-website.com/[email protected]"openssl x509 -req -in certs/client.csr -CA certs/server.pem -CAkey certs/server.key -CAcreateserial -out certs/client.pem -days 365 -sha256
目录结构默认情况下，证书和密钥存储在名为 certs 的目录中，该目录位于在配置文件 config.json 中指定的相对路径内。如果要将凭证移动到其他目录，则可以在配置文件中更新此目录位置。
您可以在 echo_server.go 文件中找到 Echo 服务器的源代码。
服务器配置Echo 服务器读取基于 JSON 的配置文件。此 JSON 文件的默认位置为 ./config.json。要覆盖此位置，请使用 -config 标志指定 JSON 的位置。
JSON 文件包含以下选项：
server-port
指定要打开套接字的端口。
41
FreeRTOS 移植指南设置 Echo 服务器
server-certificate-location
指向在创建凭证 (p. 40)中生成的服务器证书的相对路径或绝对路径。secure-connection
启用此选项可让 Echo 服务器使用 TLS。你必须先创建凭证 (p. 40)。日志记录
启用此选项可将收到的所有日志消息输出到文件。verbose
启用此选项可输出发送到 Echo 服务器的消息的内容。server-key-location
指向在创建凭证 (p. 40)中生成的服务器密钥的相对路径或绝对路径。
示例配置
{ "verbose": false, "logging": false, "secure-connection": false, "server-port": "9000", "server-certificate-location": "./certs/server.pem", "server-key-location": "./certs/server.pem"}
从命令行运行 Echo 服务器输入以下命令以运行 Echo 服务器。
go run echo_server.go
输入以下命令以使用自定义配置位置运行。
go run echo_server.go -config=config_file_path
如果要同时运行不安全和安全的 TCP 测试，则必须同时启动安全和不安全的 Echo 服务器。为此，请创建第二个安全的配置文件，并使用 -config 标志将其位置传递给 Echo 服务器的第二个实例。还要记住在第二个配置文件中指定不同的 TCP 端口。
客户端设备配置在设备上运行 TCP 测试之前，我们建议您先阅读开始使用 FreeRTOS中的FreeRTOS 用户指南。
完成创建凭证 (p. 40)中的步骤后，您应该具有以下文件：
• certs/server.pem
• certs/server.key
• certs/server.srl
• certs/client.pem
• certs/client.key
42
FreeRTOS 移植指南第 11 届联合国代表团
• certs/client.csr
对这些文件进行以下更改：
freertos/tests/include/aws_clientcredential.h
• 定义代理终端节点。• 定义事物名称。• 定义对 Wi-Fi 的访问（如果不在以太网上）。
freertos/tests/include/aws_clientcredential_keys.h
• 将 keyCLIENT_CERTIFICATE_PEM 设置为 certs/client.pem 的内容。• LEAVEkeyJITR_DEVICE_CERTIFICATE_AUTHORITY_PEM作为NULL。• 将 keyCLIENT_PRIVATE_KEY_PEM 设置为 certs/client.key 的内容。• 有关更多信息，请参阅配置 FreeRTOS 演示。
freertos/tests/include/aws_test_tcp.h
• 将 tcptestECHO_HOST_ROOT_CA 设置为 certs/server.pem 的内容。• 设置 Echo 服务器的 IP 地址和端口：
• tcptestECHO_SERVER_ADDR[0-3]
• tcptestECHO_PORT
• 设置安全 Echo 服务器的 IP 地址和端口：• tcptestECHO_SERVER_TLS_ADDR0[0-3]
• tcptestECHO_PORT_TLS
移植代码库CorepKCS11 库包含基于软件的 PKCS #11 接口 (API) 模拟实现，该接口使用 mbed TLS 提供的加密功能。在通用闪存中存储私有密钥对于评估和快速原型设计场景非常方便。在生产场景中，为了减少数据窃取和设备重复的威胁，我们建议您使用专用加密硬件。加密硬件包含具有防止导出加密密钥功能的组件。
要将专用加密硬件用于 FreeRTOS，请移植您正在使用的硬件的 PKCS #11 API。一般来说，安全加密处理器（如受信任的平台模块 (TPM)、硬件安全模块 (HSM)、安全元素或任何其他类型的安全硬件飞地）的供应商都会随硬件分发 PKCS #11 实现。您可以将库添加到 CMake 和 IDE 项目中，编译它并运行 PKCS #11 测试套件。
本节介绍了如何使用 FreeRTOS CorepKCS11 库作为您自己的 PKCS #11 API 端口的基础。只实现了PKCS #11 标准的一个子集，重点是涉及非对称键、随机数生成和散列的操作。PKCS #11 API 调用由 TLS帮助程序接口生成，目的是为了在期间执行 TLS 客户端身份验证。SOCKETS_Connect。PKCS #11 API调用也可以由一次性开发人员预置工作流程生成，以将用于身份验证的 TLS 客户端证书和私有密钥导入到AWS IoT MQTT 代理。以上两个使用案例（预置和 TLS 客户端身份验证）都只需要实施 PKCS #11 接口标准的一小部分。
有关 FreeRTOS CorepkCS11 库的信息，请参阅FreeRTOS 图书馆中的FreeRTOS 用户指南。
Prerequisites要移植 CorepkCS11 库，需要具备以下条件：
• 一个 IDE 项目或 CMakeLists.txt 列表文件，其中包含供应商提供的驱动程序，而这些驱动程序适用于敏感数据。
43
FreeRTOS 移植指南Porting
有关设置测试项目的信息，请参阅为移植设置 FreeRTOS 源代码 (p. 7)。• FreeRTOS 内核的经验证配置。
有关为您的平台配置 FreeRTOS 内核的信息，请参阅配置 FreeRTOS 内核移植 (p. 25)。
Porting移植代表 KCS11 库
1. 移植 PKCS #11 API 函数
PKCS #11 API 依赖于加密基元的实施，如 SHA256 哈希和椭圆曲线数字签名算法 (ECDSA) 签名。
PKCS #11 的 FreeRTOS 实施使用在 mbedTLS 库中实施的加密基元。FreeRTOS 包括一个用于mbedTLS 的端口。如果您的目标硬件将加密分载到单独的模块，或者如果您想要使用软件实施mbedTLS 以外的加密基元，则需要修改现有 PKCS #11 实施。
2. 移植 CorepKCS11 平台抽象层 (PAL)，以实现设备特定的证书和密钥存储。
如果您决定使用 FreeRTOS 实施 PKCS #11 的 FreeRTOS 实施，只需进行少量的自定义即可在非易失性存储 (NVM) 中读取和写入加密对象，例如板载内存。
加密对象应存储在设备重新编程时未初始化且未擦除的 NVM 部分。CorepKCS11 库的用户应能够预置设备凭证，然后使用能够通过 CorepKCS11 接口访问这些凭证的新应用程序重新编程备。
COREPKCS11 PAL 移植必须提供一个位置来存储：
• 设备客户端证书。• 设备客户端私有密钥。• 设备客户端公有密钥。• 受信任的根 CA。• 代码验证公有密钥（或包含代码验证公有密钥的证书），用于安全引导加载程序和无线 OTA 更新。• 即时预置证书。
freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 包含 PAL函数的空定义。您必须至少为此表中列出的函数提供移植：
函数 描述
PKCS11_PAL_Initialize 初始化 PAL 层。由 CorepKCS11 库在其初始化序列开始时调用。
PKCS11_PAL_SaveObject 将数据写入非易失性存储。
PKCS11_PAL_FindObject 使用 PKCS #11 CKA_LABEL 来在非易失性存储中搜索相应的 PKCS #11 对象，并返回该对象的句柄（如果存在）。
PKCS11_PAL_GetObjectValue 检索对象的值，给定句柄。
PKCS11_PAL_GetObjectValueCleanup PKCS11_PAL_GetObjectValue 调用的清除。可用于释放 PKCS11_PAL_GetObjectValue 调用中分配的内存。
3. 为您的移植增加对加密随机熵源的支持：
44
FreeRTOS 移植指南Testing
• 如果您的移植为底层加密和 TLS 支持使用 mbedTLS 库，并且您的设备有真随机数生成器 (TRNG)，请执行以下操作：1. 实施mbedtl _ 硬件投票 ()函数为 mbedTLS 用于生成加密随机位流的确定性随机位生成器
(DRBG) 注入种子。mbedtls_hardware_poll() 函数位于 freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c 中。
• 如果您的移植为底层加密和 TLS 支持使用 mbedTLS 库，但您的设备没有 TRNG，请执行以下操作：
1. 创建 freertos/libraries/3rdparty/mbedtls/include/mbedtls/config.h 的副本，然后在该副本中取消注释 MBEDTLS_ENTROPY_NV_SEED 并注释掉MBEDTLS_ENTROPY_HARDWARE_ALT。
将修改的 config.h 版本保存到 freertos/vendors/vendor/boards/board/aws_tests/config_files/config.h 中。请勿覆盖原始文件。
2. 实现函数mbedtls_nv_seed_poll()、nv_seed_read_func(),和nv_seed_write_func()。
有关实施这些函数的信息，请参阅 mbedtls/include/mbedtls/entropy_poll.h 中的注释以及mbedtls/include/mbedtls/config.h mbedTLS 标头文件。
Important
必须在制造时向设备提供具有 NIST 批准的熵源的种子文件。
Note
如果您对 FreeRTOS 资格认证计划感兴趣，请参阅我们对RNG。
有关 NIST 批准的 DRBG 和熵源的更多信息，请参阅以下 NIST 出版物：
• 使用确定性随机位生成器生成随机数的推荐• 适用于随机位生成器 (RBG) 结构的建议
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置 CorepKCS11 库
1. 将源文件 freertos/vendors/vendor/boards/board/ports/pkcs11/core_pkcs11_pal.c添加到 aws_tests IDE 项目中。
2. 将 freertos/libraries/abstractions/pkcs11 目录及其子目录中的所有文件添加到aws_tests IDE 项目中。
3. 将 freertos/libraries/freertos_plus/standard/pkcs11 目录及其子目录中的所有文件添加到 aws_tests IDE 项目中。这些文件实施了通常分组的 PKCS #11 函数集的包装程序。
4. 将源文件 freertos/libraries/freertos_plus/standard/crypto/src/iot_crypto.c 添加到 aws_tests IDE 项目中。此文件为 mbedTLS 实施 CRYPTO 抽象包装程序。
45
FreeRTOS 移植指南Testing
5. 将 freertos/libraries/3rdparty/mbedtls 及其子目录中的所有源文件和标头文件添加到aws_tests IDE 项目中。
6. Addfreertos/libraries/3rdparty/mbedtls/include和freertos/libraries/abstractions/pkcs11添加到编译器的包含路径中。
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
请参阅以下可移植层目标定义，它使用基于 mbedTLS 的 PKCS #11 软件实施，并提供移植特定的CorepkCS11 PAL 文件。
# PKCS11afr_mcu_port(pkcs11_implementation DEPENDS AFR::pkcs11_mbedtls)target_sources( AFR::pkcs11_implementation::mcu_port INTERFACE "${afr_ports_dir}/pkcs11/core_pkcs11_pal.c")
设置本地测试环境在 IDE 项目中设置库后，您需要配置一些其他文件以进行测试。
为 PKCS #11 测试配置源文件和标头文件
1. 如果已经移植了安全套接字库，请打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c，并在函数 SYSTEM_Init() 中取消注释对 SOCKETS_Init() 的调用。
2. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h，然后将 testrunnerFULL_PKCS11_ENABLED 宏设置为 1 以启用PKCS #11 测试。
运行测试执行 PKCS #11 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
...
46
FreeRTOS 移植指南Validation
当所有测试均已通过后，测试完成。
Validation要正式对设备进行 FreeRTOS 进行资格认证，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
完成将 CorepKCS11 库移植到设备之后，您可以开始移植 TLS 库。有关说明，请参阅移植 TLS库 (p. 47)。
移植 TLS 库对于传输层安全性 (TLS) 身份验证，FreerTOS 使用 mbedTLS 或片外 TLS 实施，例如某些网络协处理器上的情况。FreerTOS 包括一个 MBedTL 端口。如果您为 TLS 使用 mbedTLS，则无需 TLS 移植。为允许不同TLS 实施，第三方 TLS 库通过 TLS 抽象层访问。
Note
无论您设备的 FreerTOS 移植使用什么 TLS 实施，该移植都必须通过 TLS 的资格认证测试。资格认证基于 AWS IoT Device Tester 的结果。此外，您的 TLS 实现应支持AWS IoT 支持的 TLS 密码套件。
要为测试 TLS 准备您的平台，您需要在 AWS 云中配置您的设备，并且您需要在设备上预置证书和密钥。
Prerequisites要移植 FreeTOS TLS 库，您需要以下信息：
• FreeRTOS 安全套接字库的端口。
有关移植安全套接字库到您平台的信息，请参阅移植安全套接字库 (p. 36)。• 移植代理 KCS11 库。
有关移植 CorepKCS11 库到您平台的信息，请参阅移植代码库 (p. 43)。• AWS 账户。
有关设置 AWS 账户的信息，请参阅如何创建并激活新的 Amazon Web Services 账户？（位于 AWS 知识中心内）。
• OpenSSL。
您可从 Shining Light 下载适用于 Windows 的 OpenSSL 版本。有关 Linux 源代码下载的信息，请参阅OpenSSL.org。您还可以使用程序包管理器来安装适用于 Linux 和 macOS 的 OpenSSL。
47
FreeRTOS 移植指南Porting
Porting如果您的目标硬件将 TLS 功能分载到网络芯片，您需要在以下表中实施 TLS 抽象层功能。
函数 描述
TLS_Init 初始化 TLS 上下文。
TLS_Connect 协商 TLS 并连接到服务器。
TLS_Recv 从 TLS 连接读取请求的字节数。
TLS_Send 将请求的字节数写入到 TLS 连接。
TLS_Cleanup 释放 TLS 上下文使用的资源。
iot_tls.h 包含实施这些函数所需的信息。将您在其中实施函数的文件另存为 iot_tls.c。
将您的设备连接到 AWS IoT您的设备必须已向 AWS IoT 注册才能与 AWS 云通信。要将主板注册到 AWS IoT，您需要以下信息：
AWS IoT 策略
AWS IoT 策略向您的设备授予访问 AWS IoT 资源的权限。它存储在 AWS 云中。AWS IoT 事物
AWS IoT 事物允许您在 AWS IoT 中管理设备。它存储在 AWS 云中。私有密钥和 X.509 证书
通过私有密钥和证书，您可以用 AWS IoT 对设备进行身份验证。
按照以下步骤创建策略、事物和密钥以及证书。
创建 AWS IoT 策略
1. 浏览至AWS IoT 控制台。2. 在导航窗格中依次选择安全、策略和创建。3. 输入用于标识您的策略的名称。4. 在添加语句部分中，选择高级模式。将以下 JSON 复制并粘贴到策略编辑器窗口中：
{ "Version": "2012-10-17", "Statement": [ {"Effect": "Allow","Action": "iot:*","Resource": "*"} ]}
Important
此策略将所有 AWS IoT 资源的访问权限授予所有 AWS IoT 操作。此策略便于开发和测试，但不建议用于生产环境。
48
FreeRTOS 移植指南为 TLS 测试设置证书和密钥
5. 选择创建。
为设备创建 IoT 事物、私有密钥和证书
1. 浏览至AWS IoT 控制台。2. 在导航窗格中，选择管理，然后选择事物。3. 如果您的账户中未注册任何事物，此时将显示您还没有任何事物页面。如果您看到此页面，请选择注册
事物。否则，选择 Create。4. 在创建 AWS IoT 事物页面上，选择创建单个事物。5. 在将设备添加到事物注册表页面上，输入您事物的名称，然后选择下一步。6. 在添加事物的证书页面上的一键式创建证书下，选择创建证书。7. 选择各项的下载链接来下载私有密钥和证书。8. 选择激活来激活您的证书。必须先激活证书，然后才能使用它们 。9. 选择附加策略将策略附加到证书，授予您的设备访问 AWS IoT 操作的权限。10. 选择您刚刚创建的策略，然后选择注册事物。
从 AWS IoT 控制台中获取证书和密钥之后，您需要将freertos/tests/include/aws_clientcredential.h头文件，以便您的设备可以连接到 AWS IoT。
配置 freertos/tests/include/aws_clientcredential.h
1. 浏览至AWS IoT 控制台。2. 在导航窗格中，选择 Settings。
您的 AWS IoT 终端节点将显示在Endpoint。它应该类似于 123456789012-ats.iot.us-east-1.amazonaws.com。记下此终端节点。
3. 在导航窗格中，选择管理，然后选择事物。
您的设备应具有 AWS IoT 事物名称。记下此名称。4. 在构建 FreeRTOS 源代码的计算机上，打开freertos/test/include/
aws_clientcredential.h文件，并为以下常量指定值：
• static const char clientcredentialMQTT_BROKER_ENDPOINT[] = "Your AWS IoTendpoint";
• #define clientcredentialIOT_THING_NAME "The AWS IoT thing name of yourboard"
为 TLS 测试设置证书和密钥TLS_ConnectRSA()
本节提供了有关为测试 TLS 移植设置证书和密钥的说明。
对于 RSA 设备身份验证，您可以使用注册设备时从 AWS IoT 控制台下载的私有密钥和证书。
Note
将设备注册为 AWS 物联网事物之后，您可以从 AWS IoT 控制台检索设备证书，但无法检索私有密钥。
FreeRTOS 是一个 C 语言项目。您必须设置证书和密钥格式，然后再将其添加到 freertos/tests/include/aws_clientcredential_keys.h 标头文件中。
49
FreeRTOS 移植指南为 TLS 测试设置证书和密钥
为 freertos/tests/include/aws_clientcredential_keys.h 设置证书和密钥格式
1. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/CertificateConfigurator.html。
2. UDER证书 PEM 文件中，选择ID-certificate.pem.crt文件，您从 AWS IoT 控制台下载的文件。3. UDER私钥 PEM 文件中，选择ID-private.pem.key文件，您从 AWS IoT 控制台下载的文件。4. 选择 Generate and save aws_clientcredential_keys.h (生成并保存 aws_clientcredential_keys.h)，然后
将文件保存到 freertos/tests/include 中。这将覆盖目录中的现有文件。
Note
仅出于演示目的对证书和私有密钥进行了硬编码。生产级应用程序应将这些文件存储在安全位置。
TLS_ConnectEC()
对于椭圆曲线数字签名算法 (ECDSA) 身份验证，您需要生成私有密钥、证书签名请求 (CSR) 和证书。您可以使用 OpenSSL 生成私有密钥和 CSR，并且您可以在 AWS 物联网控制台中使用 CSR 生成证书。
生成私有密钥和 CSR
1. 使用以下命令在当前工作目录中创建名为 p256_privatekey.pem 的私有密钥：
openssl ecparam -name prime256v1 -genkey -noout -out p256_privatekey.pem
2. 使用以下命令在当前工作目录中创建名为 csr.csr 的 CSR 文件。
openssl req –new –key p256_privatekey.pem –out csr.csr
在 AWS IoT 控制台中使用 CSR 创建证书
1. 打开AWS IoT 控制台。2. 在导航窗格中依次选择安全、证书和创建。3. 选择利用 CSR 创建，然后查找并上传使用 OpenSSL 创建的 csr.csr 文件。4. 选择激活来激活证书，然后选择下载以下载 .cert.pem 文件格式的证书。5. 选择附加策略，然后查找并选择您在将您的设备连接到 AWS IoT (p. 48)说明，然后选择Done。6. 将证书附加到您在注册设备时创建的 AWS IoT 事物。7. 在证书页面上，找到并选择您刚刚创建的证书。在页面右上角，选择操作，然后选择附加事物。8. 查找并选择您创建的事物作为设备，然后选择附加。
您必须为设备设置证书和私有密钥格式，然后再将其添加到 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 标头文件中。
为 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 设置证书和密钥格式
1. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/PEMfileToCString.html。
2. UDERPEM 证书或密钥中，选择ID-certificate.pem.crt您从 AWS IoT 控制台下载的。3. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到
aws_clientcredential_keys.h 中设置了格式的 PEM 字符串，然后复制证书字符串。
50
FreeRTOS 移植指南为 TLS 测试设置证书和密钥
4. 打开 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h，然后将设置了格式的证书字符串粘贴到 tlstestCLIENT_CERTIFICATE_PEM_EC 的定义中。
Note
仅出于演示目的对证书和私有密钥进行了硬编码。生产级应用程序应将这些文件存储在安全位置。
5. 按照相同的步骤获取您使用 OpenSSL 创建的私有密钥文件的已设置格式的字符串(p256_privatekey.pem)。将设置了格式的私有密钥字符串复制并粘贴到 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 中的tlstestCLIENT_PRIVATE_KEY_PEM_EC 的定义中。
Infreertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h，定义tlstestMQTT_BROKER_ENDPOINT_EC使用的 AWS IoT MQTT 代理终端节点地址，地址与您在将您的设备连接到 AWS IoT (p. 48)。
TLS_ConnectMalformedCert()
此测试验证您可以使用格式错误的证书与服务器进行身份验证。随机修改证书有可能在发送连接请求之前被X.509 证书验证拒绝。要设置格式错误的证书，我们建议您修改证书的发布者。
修改证书的发布者
1. 获取您已使用的有效的客户端证书 ID-certificate.pem.crt。
在 Windows 证书管理器中，证书属性如下所示：
2. 使用以下命令，将证书从 PEM 转换为 DER：
51
FreeRTOS 移植指南为 TLS 测试设置证书和密钥
openssl x509 -outform der -in ID-certificate.pem.crt -out ID-certificate.der.crt
3. 打开 DER 证书，然后搜索以下十六进制序列：
41 6d 61 7a 6f 6e 20 57 65 62 20 53 65 72 76 69 63 65 73
此序列转换为纯文本“Amazon Web Services”。4. 将 53 更改为 43，这样序列的纯文本变为“Amazon Web Cervices”，然后保存该文件。
在 Windows 证书管理器中，证书属性现在如下所示：
5. 使用以下命令可将证书转换回 PEM：
openssl x509 -inform der -in ID-certificate.der.crt -out ID-cert-modified.pem.crt
您必须纠正设备的错误证书格式，然后再将其添加到 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 标头文件中。
52
FreeRTOS 移植指南为 TLS 测试设置证书和密钥
为 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 设置证书格式
1. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/PEMfileToCString.html。
2. 在 PEM Certificate or Key (PEM 证书或密钥) 下，选择您创建的 ID-certificate.pem.crt 并修改。
3. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到aws_clientcredential_keys.h 中设置了格式的 PEM 字符串，然后复制证书字符串。
4. 打开 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h，然后将设置了格式的证书字符串粘贴到 tlstestCLIENT_CERTIFICATE_PEM_MALFORMED 的定义中。
Note
仅出于演示目的对证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。
TLS_ConnectBYOCCredentials()
您可以使用自己的证书进行身份验证。要创建并注册一个具有有效 rootCA/CA 链的证书，请按照创建 BYOC(ECDSA) (p. 54) 中的说明进行操作。创建证书后，您需要将一些策略附加到设备证书，然后您需要将设备的事物附加到证书。
将策略附加到设备证书
1. 打开AWS IoT 控制台。2. 在导航窗格中，依次选择安全、证书和您在创建 BYOC (ECDSA) (p. 54) 中创建和注册的设备证书。3. 选择操作，然后选择附加策略。4. 查找并选择您在创建并附加到 RSA 证书的 AWS 物联网策略，请参阅将您的设备连接到 AWS
IoT (p. 48)说明，然后选择Attach。
将事物附加到设备证书
1. 在证书页面上，找到并选择相同的设备证书，选择操作，然后选择附加事物。2. 查找并选择您创建的事物作为设备，然后选择附加。
为 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 设置证书格式
1. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/PEMfileToCString.html。
2. 在 PEM Certificate or Key (PEM 证书或密钥) 下，选择您创建的 ID-certificate.pem.crt 并修改。
3. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到aws_clientcredential_keys.h 中设置了格式的 PEM 字符串，然后复制证书字符串。
4. 打开 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h，然后将设置了格式的证书字符串粘贴到 tlstestCLIENT_BYOC_CERTIFICATE_PEM 的定义中。
Note
仅出于演示目的对证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。5. 按照相同的步骤获取您创建的私有密钥文件的设置了格式的字符串。将设置了格式的私有密钥字符串复
制并粘贴到 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 中的 tlstestCLIENT_BYOC_PRIVATE_KEY_PEM 的定义中。
53
FreeRTOS 移植指南创建 BYOC (ECDSA)
TLS_ConnectUntrustedCert()
您可以使用自己的证书进行身份验证，而无需将证书注册到 AWS IoT。要创建具有效 rootCA/CA 链的证书，请按照中的说明操作，请按照创建 BYOC (ECDSA) (p. 54)，但跳过将设备注册到 AWS IoT 的说明。
为 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 设置证书格式
1. 在浏览器窗口中，打开 freertos/tools/certificate_configuration/PEMfileToCString.html。
2. 在 PEM Certificate or Key (PEM 证书或密钥) 下，选择您创建的 ID-certificate.pem.crt 并修改。
3. 选择 Display formatted PEM string to be copied into aws_clientcredential_keys.h (显示要复制到aws_clientcredential_keys.h 中设置了格式的 PEM 字符串，然后复制证书字符串。
4. 打开 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h，然后将设置了格式的证书字符串粘贴到 tlstestCLIENT_UNTRUSTED_CERTIFICATE_PEM 的定义中。
Note
仅出于演示目的对证书进行了硬编码。生产级应用程序应将这些文件存储在安全位置。5. 按照相同的步骤获取您创建的私有密钥文件的设置了格式的字符串。将设置了格式的私有密钥字符串复
制并粘贴到 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 中的 tlstestCLIENT_UNTRUSTED_PRIVATE_KEY_PEM 的定义中。
创建 BYOC (ECDSA)在这些步骤中，您将使用 AWS IoT 控制台、AWS 命令行界面和 OpenSSL 为 AWS 云上的设备创建并注册证书和密钥。请确保您已在计算机上安装并配置了 AWS CLI，然后才能运行 AWS CLI 命令。
Note
创建 CA 证书时，在提示时请为可分辨名称 (DN) 字段使用一致的有效值。对于“Common Name (公用名)”字段，您可以使用任意值，除非另有说明。
生成根 CA
1. 使用以下命令生成根 CA 私有密钥：
openssl ecparam -name prime256v1 -genkey -noout -out rootCA.key
2. 使用以下命令生成根 CA 证书：
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt
生成中间 CA
1. 创建所需的文件：
touch index.txt
echo 1000 > serial
2. 将 ca.config (p. 56) 文件保存到当前工作目录中。
54
FreeRTOS 移植指南创建 BYOC (ECDSA)
3. 使用以下命令来生成中间 CA 的私有密钥：
openssl ecparam -name prime256v1 -genkey -noout -out intermediateCA.key
4. 使用以下命令来生成中间 CA 的 CSR：
openssl req -new -sha256 -key intermediateCA.key -out intermediateCA.csr
5. 使用以下命令将中间 CA 的 CSR 注册到根 CA：
openssl ca -config ca.config -notext -cert rootCA.crt -keyfile rootCA.key -days 500 -in intermediateCA.csr -out intermediateCA.crt
生成设备证书
Note
此处使用的 ECDSA 证书为示例。
1. 使用以下命令生成私有密钥。
openssl ecparam -name prime256v1 -genkey -noout -out deviceCert.key
2. 使用以下命令为设备证书生成 CSR ：
openssl req -new -key deviceCert.key -out deviceCert.csr
3. 使用以下命令将设备证书注册到中间 CA：
openssl x509 -req -in deviceCert.csr -CA intermediateCA.crt -CAkey intermediateCA.key -CAcreateserial -out deviceCert.crt -days 500 -sha256
注册 CA 证书
1. 使用以下 AWS CLI 命令获取注册代码：
aws iot get-registration-code
2. 使用以下命令为验证证书生成私有密钥：
openssl ecparam -name prime256v1 -genkey -noout -out verificationCert.key
3. 使用以下命令为验证证书创建 CSR：
openssl req -new -key verificationCert.key -out verificationCert.csr
在系统提示时，对于 Common Name，输入您在第一步中获取的注册代码。4. 通过以下命令使用根 CA 签名验证证书：
openssl x509 -req -in verificationCert.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out rootCAverificationCert.crt -days 500 -sha256
5. 通过以下命令使用中间 CA 签名验证证书：
55
FreeRTOS 移植指南创建 BYOC (ECDSA)
openssl x509 -req -in verificationCert.csr -CA intermediateCA.crt -CAkey intermediateCA.key -CAcreateserial -out intermediateCAverificationCert.crt -days 500 -sha256
6. 使用以下 AWS CLI 命令将两个 CA 证书注册到 AWS IoT：
aws iot register-ca-certificate --ca-certificate file://rootCA.crt --verification-cert file://rootCAverificationCert.crt
aws iot register-ca-certificate --ca-certificate file://intermediateCA.crt --verification-cert file://intermediateCAverificationCert.crt
7. 使用以下 AWS CLI 命令激活两个 CA 证书：
aws iot update-ca-certificate --certificate-id ID --new-status ACTIVE
其中 ID 是其中一个证书的证书 ID。
注册设备证书
1. 使用以下 AWS CLI 命令将设备证书注册到 AWS IoT：
aws iot register-certificate --certificate-pem file://deviceCert.crt --ca-certificate-pem file://intermediateCA.crt
2. 使用以下 AWS CLI 命令激活设备证书：
aws iot update-certificate --certificate-id ID --new-status ACTIVE
其中 ID 是证书的证书 ID。
ca.config
将以下文本保存到您当前工作目录中名为 ca.config 的文件。
此文件是修改后的 openssl.cnfOpenSSL 示例配置文件。
## OpenSSL example configuration file.# This is mostly being used for generation of certificate requests.#
# This definition stops the following lines choking if HOME isn't# defined.HOME = .RANDFILE = $ENV::HOME/.rnd
# Extra OBJECT IDENTIFIER info:#oid_file = $ENV::HOME/.oidoid_section = new_oids
# To use this configuration file with the "-extfile" option of the# "openssl x509" utility, name here the section containing the
56
FreeRTOS 移植指南创建 BYOC (ECDSA)
# X.509v3 extensions to use:# extensions = # (Alternatively, use a configuration file that has only# X.509v3 extensions in its main [= default] section.)
[ new_oids ]
# We can add new OIDs in here for use by 'ca', 'req' and 'ts'.# Add a simple OID like this:# testoid1=1.2.3.4# Or use config file substitution like this:# testoid2=${testoid1}.5.6
# Policies used by the TSA examples.tsa_policy1 = 1.2.3.4.1tsa_policy2 = 1.2.3.4.5.6tsa_policy3 = 1.2.3.4.5.7
####################################################################[ ca ]default_ca = CA_default # The default ca section
####################################################################[ CA_default ]
dir = . # Where everything is keptcerts = $dir # Where the issued certs are keptcrl_dir = $dir # Where the issued crl are keptdatabase = $dir/index.txt # database index file.#unique_subject = no # Set to 'no' to allow creation of # several ctificates with same subject.new_certs_dir = $dir # default place for new certs.
certificate = $dir/cacert.pem # The CA certificateserial = $dir/serial # The current serial numbercrlnumber = $dir/crlnumber # the current crl number # must be commented out to leave a V1 CRLcrl = $dir/crl.pem # The current CRLprivate_key = $dir/private/cakey.pem# The private keyRANDFILE = $dir/private/.rand # private random number file
x509_extensions = usr_cert # The extentions to add to the cert
# Comment out the following two lines for the "traditional"# (and highly broken) format.name_opt = ca_default # Subject Name optionscert_opt = ca_default # Certificate field options
# Extension copying option: use with caution.# copy_extensions = copy
# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs# so this is commented out by default to leave a V1 CRL.# crlnumber must also be commented out to leave a V1 CRL.# crl_extensions = crl_ext
default_days = 365 # how long to certify fordefault_crl_days= 30 # how long before next CRLdefault_md = default # use public key default MDpreserve = no # keep passed DN ordering
# A few difference way of specifying how similar the request should look# For type CA, the listed attributes must be the same, and the optional# and supplied fields are just that :-)policy = policy_match
57
FreeRTOS 移植指南创建 BYOC (ECDSA)
# For the CA policy[ policy_match ]countryName = matchstateOrProvinceName = matchorganizationName = matchorganizationalUnitName = optionalcommonName = suppliedemailAddress = optional
# For the 'anything' policy# At this point in time, you must list all acceptable 'object'# types.[ policy_anything ]countryName = optionalstateOrProvinceName = optionallocalityName = optionalorganizationName = optionalorganizationalUnitName = optionalcommonName = suppliedemailAddress = optional
####################################################################[ req ]default_bits = 2048default_keyfile = privkey.pemdistinguished_name = req_distinguished_nameattributes = req_attributesx509_extensions = v3_ca # The extentions to add to the self signed cert
# Passwords for private keys if not present they will be prompted for# input_password = secret# output_password = secret
# This sets a mask for permitted string types. There are several options. # default: PrintableString, T61String, BMPString.# pkix : PrintableString, BMPString (PKIX recommendation before 2004)# utf8only: only UTF8Strings (PKIX recommendation after 2004).# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).# MASK:XXXX a literal mask value.# WARNING: ancient versions of Netscape crash on BMPStrings or UTF8Strings.string_mask = utf8only
# req_extensions = v3_req # The extensions to add to a certificate request
[ req_distinguished_name ]countryName = Country Name (2 letter code)countryName_default = AUcountryName_min = 2countryName_max = 2
stateOrProvinceName = State or Province Name (full name)stateOrProvinceName_default = Some-State
localityName = Locality Name (eg, city)
0.organizationName = Organization Name (eg, company)0.organizationName_default = Internet Widgits Pty Ltd
# we can do this but it is not needed normally :-)#1.organizationName = Second Organization Name (eg, company)#1.organizationName_default = World Wide Web Pty Ltd
organizationalUnitName = Organizational Unit Name (eg, section)#organizationalUnitName_default =
58
FreeRTOS 移植指南创建 BYOC (ECDSA)
commonName = Common Name (e.g. server FQDN or YOUR name)commonName_max = 64
emailAddress = Email AddressemailAddress_max = 64
# SET-ex3 = SET extension number 3
[ req_attributes ]challengePassword = A challenge passwordchallengePassword_min = 4challengePassword_max = 20
unstructuredName = An optional company name
[ usr_cert ]
# These extensions are added when 'ca' signs a request.
# This goes against PKIX guidelines but some CAs do it and some software# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:TRUE
# Here are some examples of the usage of nsCertType. If it is omitted# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.# nsCertType = server
# For an object signing certificate this would be used.# nsCertType = objsign
# For normal client use this is typical# nsCertType = client, email
# and for everything including object signing:# nsCertType = client, email, objsign
# This is typical in keyUsage for a client certificate.# keyUsage = nonRepudiation, digitalSignature, keyEncipherment
# This will be displayed in Netscape's comment listbox.nsComment = "OpenSSL Generated Certificate"
# PKIX recommendations harmless if included in all certificates.subjectKeyIdentifier=hashauthorityKeyIdentifier=keyid,issuer
# This stuff is for subjectAltName and issuerAltname.# Import the email address.# subjectAltName=email:copy# An alternative to produce certificates that aren't# deprecated according to PKIX.# subjectAltName=email:move
# Copy subject details# issuerAltName=issuer:copy
#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem#nsBaseUrl#nsRevocationUrl#nsRenewalUrl#nsCaPolicyUrl#nsSslServerName
59
FreeRTOS 移植指南创建 BYOC (ECDSA)
# This is required for TSA certificates.# extendedKeyUsage = critical,timeStamping
[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSEkeyUsage = nonRepudiation, digitalSignature, keyEncipherment
[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
# This is what PKIX recommends but some broken software chokes on critical# extensions.
#basicConstraints = critical,CA:true# So we do this instead.basicConstraints = CA:true
# Key usage: this is typical for a CA certificate. However since it will# prevent it being used as a test self-signed certificate it is best# left out by default.# keyUsage = cRLSign, keyCertSign
# Some might want this also# nsCertType = sslCA, emailCA
# Include email address in subject alt name: another PKIX recommendation# subjectAltName=email:copy# Copy issuer details# issuerAltName=issuer:copy
# DER hex encoding of an extension: beware experts only!# obj=DER:02:03# Where 'obj' is a standard or added object# You can even override a supported extension:# basicConstraints= critical, DER:30:03:01:01:FF
[ crl_ext ]
# CRL extensions.# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
# issuerAltName=issuer:copyauthorityKeyIdentifier=keyid:always
[ proxy_cert_ext ]# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE
60
FreeRTOS 移植指南创建 BYOC (ECDSA)
# Here are some examples of the usage of nsCertType. If it is omitted# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.# nsCertType = server
# For an object signing certificate this would be used.# nsCertType = objsign
# For normal client use this is typical# nsCertType = client, email
# and for everything including object signing:# nsCertType = client, email, objsign
# This is typical in keyUsage for a client certificate.# keyUsage = nonRepudiation, digitalSignature, keyEncipherment
# This will be displayed in Netscape's comment listbox.nsComment = "OpenSSL Generated Certificate"
# PKIX recommendations harmless if included in all certificates.subjectKeyIdentifier=hashauthorityKeyIdentifier=keyid,issuer
# This stuff is for subjectAltName and issuerAltname.# Import the email address.# subjectAltName=email:copy# An alternative to produce certificates that aren't# deprecated according to PKIX.# subjectAltName=email:move
# Copy subject details# issuerAltName=issuer:copy
#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem#nsBaseUrl#nsRevocationUrl#nsRenewalUrl#nsCaPolicyUrl#nsSslServerName
# This really needs to be in place for it to be a proxy certificate.proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo
####################################################################[ tsa ]
default_tsa = tsa_config1 # the default TSA section
[ tsa_config1 ]
# These are used by the TSA reply generation only.dir = ./demoCA # TSA root directoryserial = $dir/tsaserial # The current serial number (mandatory)crypto_device = builtin # OpenSSL engine to use for signingsigner_cert = $dir/tsacert.pem # The TSA signing certificate # (optional)certs = $dir/cacert.pem # Certificate chain to include in reply # (optional)signer_key = $dir/private/tsakey.pem # The TSA private key (optional)
default_policy = tsa_policy1 # Policy if request did not specify it
61
FreeRTOS 移植指南Testing
# (optional)other_policies = tsa_policy2, tsa_policy3 # acceptable policies (optional)digests = md5, sha1 # Acceptable message digests (mandatory)accuracy = secs:1, millisecs:500, microsecs:100 # (optional)clock_precision_digits = 0 # number of digits after dot. (optional)ordering = yes # Is ordering defined for timestamps? # (optional, default: no)tsa_name = yes # Must the TSA name be included in the reply? # (optional, default: no)ess_cert_id_chain = no # Must the ESS cert id chain be included? # (optional, default: no)
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置 TLS 库
1. 将 iot_tls.c 添加到 aws_tests IDE 项目。2. 将源文件 iot_test_tls.c 添加到虚拟文件夹 aws_tests/application_code/common_tests/
tls 中。此文件包含 TLS 测试。
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
设置本地测试环境针对 TLS 移植有五种单独的测试，每种针对 FreerTOS TLS 库支持的一种类型的身份验证：
• TLS_ConnectRSA()
• TLS_ConnectEC()
• TLS_ConnectMalformedCert()
• TLS_ConnectBYOCCredentials()
• TLS_ConnectUntrustedCert()
要运行这些测试，您的主板必须使用 MQTT 协议与 AWS 云通信。AWS IoT 托管一个 MQTT 代理，可与连接的边缘设备相互发送和接收消息。AWS IoT MQTT 代理仅接受经过相互身份验证的 TLS 连接。
按照中的说明进行操作将您的设备连接到 AWS IoT (p. 48)将您的设备连接到 AWS IoT。
62
FreeRTOS 移植指南Validation
每个 TLS 测试需要使用不同的证书/密钥组合，并在 freertos/tests/include/aws_clientcredential_keys.h 或 freertos/libraries/freertos_plus/standard/tls/test/iot_test_tls.h 中进行格式设置和定义。
按照 为 TLS 测试设置证书和密钥 (p. 49) 中的说明操作以获取您需要的证书和密钥进行测试。
在 IDE 项目中设置库后，您需要配置一些其他文件以进行测试。
为 TLS 测试配置源文件和标头文件
1. 要启用 TLS 测试，请打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h 并将 testrunnerFULL_TLS_ENABLED 宏设置为1。
2. 打开 freertos/libraries/freertos_plus/standard/utils/src/iot_system_init.c，并在函数 SYSTEM_Init() 中，确保取消注释调用 SOCKETS_Init() 的行。
运行测试执行 TLS 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
如果通过所有测试，则测试完成。
Important
移植 TLS 库并测试移植之后，您必须运行依赖于 TLS 功能的安全套接字测试。有关更多信息，请参阅安全套接字移植文档中的 Testing (p. 37)。
Validation要正式对设备进行 FreerTOS 资格认证，您需要使用 AWS IoT 设备测试程序验证该设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreerTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
63
FreeRTOS 移植指南科雷姆
完成将 Freertos TLS 库移植到设备之后，您可以开始为测试设置 CoremQtt 库。有关说明，请参阅配置CoremQTT 库以进行测试 (p. 64)。
配置 CoremQTT 库以进行测试边缘设备可以使用 MQTT 协议与 AWS 云通信。AWS IoT 托管一个 MQTT 代理，可与连接的边缘设备相互发送和接收消息。
CoremQTT 库会为运行 FreeRTOS 的设备实现 MQTT 协议。不需要移植 CoremQTT 库，但您设备的测试项目必须通过资格认证中的所有 MQTT 测试。有关更多信息，请参阅 。库里姆 QTT 库中的FreeRTOS 用户指南。
Prerequisites要设置 CoremQtt 库测试，需要具备以下条件：
• TLS 库移植。
有关将 TLS 库移植到您的平台的信息，请参阅移植 TLS 库 (p. 47)。
如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目在 IDE 项目中设置 CoremQTT 库
1. 将所有库源文件添加到freertos/libraries/coreMQTT/source目录及其子目录添加到aws_testsIDE 项目。
2. 将网络图层的所有源文件（在测试中使用）添加到freertos/libraries/abstractions/transport目录和secure_sockets子目录添加到aws_testsIDE 项目。
3. 添加core_mqtt_config.h文件，用于构建 CoremQtt 库所需的配置文件目录freertos/vendors/vendor/boards/board/aws_tests/config_files。
4. 将测试源代码文件添加到freertos/tests/integration_test/core_mqtt_system.c添加到aws_testsIDE 项目。
设置本地测试环境在 IDE 项目中设置库后，需要配置其他文件以进行测试。
为 MQTT 测试配置源文件和标头文件
• 要启用 MQTT 测试，请打开 freertos/vendors/vendor-name/boards/board-name/aws_tests/config_files/aws_test_runner_config.h 并将testrunnerFULL_CORE_MQTT_AWS_IOT_ENABLED 宏设置为 1。
运行测试执行 MQTT 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。如果通过所有测试，则测试完成。
64
FreeRTOS 移植指南Validation
Validation要正式对设备进行 FreeRTOS 资格认证，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
为您的设备设置 CoremQTT 库后，即可开始移植 OTA 代理库。有关说明，请参阅移植 OTA 库 (p. 66)。
如果您的设备不支持 OTA 功能，您可以开始移植低功耗蓝牙库。有关说明，请参阅移植低功耗蓝牙库 (p. 72)。
如果您的设备不支持 OTA 和低功耗蓝牙功能，则您已完成移植，可以开始 FreeRTOS 资格认证流程。请参阅FreeRTOS 资格认证指南，了解更多信息。
配置核心 HTTP 库以进行测试边缘上的设备可以使用 HTTP 协议与 AWS 云进行通信。AWS IoT 服务托管一个 HTTP 服务器，可与连接的边缘设备相互发送和接收消息。
Prerequisites要设置 CoreereHTTP 库测试，需要具备以下条件：
• TLS 库移植。
有关将 TLS 库移植到您的平台的信息，请参阅移植 TLS 库 (p. 47)。
如果使用 IDE 构建测试项目，您必须在 IDE 项目中设置库端口。
设置 IDE 测试项目在 IDE 项目中设置核心 HTTP 库
1. 将所有测试源文件添加到freertos/libraries/coreHTTP/source目录及其子目录添加到aws_testsIDE 项目。
2. 将网络图层的所有源文件（在测试中使用）添加到freertos/libraries/abstractions/transport和secure_sockets子目录添加到aws_testsIDE 项目。
3. 添加core_http_config.h文件添加到配置文件目录freertos/vendors/vendor/boards/board/aws_tests/config_files。此文件是构建核心 HTTP 库所必需的。
4. 将测试源文件添加到freertos/tests/integration_test/core_http_system.c添加到aws_testsIDE 项目。
设置本地测试环境在 IDE 项目中设置库后，您必须配置其他文件以进行测试。
为 HTTP 测试配置源文件和标头文件
• 要启用 HTTP 测试，请打开freertos/vendors/vendor-name/boards/board-name/aws_tests/config_files/aws_test_runner_config.h文件并设置testrunnerFULL_CORE_HTTP_AWS_IOT_ENABLED以宏1。
65
FreeRTOS 移植指南运行测试
运行测试运行 HTTP 测试
1. 构建测试项目，然后将其刷写到您的设备以运行该项目。2. 在 UART 控制台中检查测试结果。如果通过所有测试，则测试完成。
移植 OTA 库借助 FreeRTOS 无线 (OTA) 更新，您可以执行以下操作：
• 将固件映像部署到单个设备、一组设备或整个机群。• 在将设备添加到组，或重置或重新预置设备时，将固件部署到设备。• 在新固件部署到设备之后，验证其真实性和完整性。• 监控部署进度。• 调试失败的部署。• 使用 AWS IoT 的代码签名对固件进行数字签名。
有关更多信息，请参阅 。FreeRTOS 更新中的FreeRTOS 用户指南。
您可以使用 OTA 代理库，将 OTA 功能集成到您的 FreeRTOS 应用程序中。有关更多信息，请参阅 。FreeRTOS OTA 代理库中的FreeRTOS 用户指南。
FreeRTOS 设备必须在它们接收到的 OTA 固件映像上强制实施加密代码签名验证。我们建议采用下列算法：
• 椭圆曲线数字签名算法 (ECDSA)• NIST P256 曲线• SHA-256 哈希
Note
目前，资格认证不需要移植 FreeTOS OTA 更新库。
Prerequisites要移植 OTA 代理库，需要具备以下条件：
• TLS 库移植。
有关信息，请参阅 移植 TLS 库 (p. 47)。• 支持 OTA 更新的引导加载程序。
有关移植引导加载程序演示应用程序的更多信息，请参阅移植引导加载程序演示 (p. 67)。
Portingfreertos/vendors/vendor/boards/board/ports/ota/aws_ota_pal.c 包含一组平台抽象层(PAL) 函数的空定义。至少实现此表中列出的一组函数。
66
FreeRTOS 移植指南IoT 设备引导加载程序
函数 描述
prvPAL_Abort 中止 OTA 更新。
prvPAL_CreateFileForRx 创建文件来存储收到的数据块。
prvPAL_CloseFile 关闭指定的文件。如果使用实现加密保护的存储，这可能会对文件进行身份验证。
prvPAL_WriteBlock 按照指定偏移量将数据块写入指定文件。在成功时，将返回写入的字节数。否则，将返回负数错误代码。
prvPAL_ActivateNewImage 激活或启动新的固件映像。对于某些端口，如果以编程方式同步重置设备，此函数可能不会返回。
prvPAL_SetPlatformImageState 执行平台所需的任何操作来接受或拒绝最新的 OTA固件映像（或包）。要确定如何实现此函数，请参阅您的主板（平台）的文档以了解详细信息和架构。
prvPAL_GetPlatformImageState 获取 OTA 更新映像的状态。
如果您的设备已内置相应支持，实施此表中的函数。
函数 描述
prvPAL_CheckFileSignature 验证指定文件的签名。
prvPAL_ReadAndAssumeCertificate 从文件系统读取指定的签署人证书并将其返回给调用方。
确保您有支持 OTA 更新的引导加载程序。有关移植随提供的引导加载程序演示应用程序或创建 IoT 设备引导加载程序的说明，请参阅IoT 设备引导加载程序 (p. 67)。
IoT 设备引导加载程序移植引导加载程序演示FreeTOS 包含一个用于 PIC32MZEF Microchip 平台的演示引导加载程序应用程序。有关更多信息，请参阅 。Microchip Curiosity PIC32MZEF 的演示启动加载程序中的FreeRTOS 用户指南。您可以将此演示移植到其他平台。
如果选择不将演示移植到您的平台，您可以使用自己的引导加载程序。IoT 设备引导加载程序的威胁建模 (p. 67)讨论了威胁建模，以帮助您编写自己的安全引导加载程序应用程序。
IoT 设备引导加载程序的威胁建模Background
作为工作定义，该威胁模型引用的嵌入式 IoT 设备是基于微控制器的产品，它们与云服务进行交互。它们可以部署在消费者、商业或工业环境中。IoT 设备可以收集有关用户、患者、机器或环境的数据，并且可以控制从灯泡和门锁到工厂机器的任何事物。
67
FreeRTOS 移植指南IoT 设备引导加载程序
从假设对手的角度看，威胁建模是一种保护安全的方法。通过考虑对手的目标和方法，创建了一个威胁列表。威胁是对手对资源或资产发起的攻击。该列表具有优先级，并用于确定或创建缓解措施。在选择缓解措施时，实施和维护这些措施的成本应与它们提供的实际安全价值相平衡。可以使用多种威胁模型方法。每种方法可以支持开发安全且成功的 IoT 产品。
FreeTOS 为 IoT 设备提供 OTA（“无线”）软件更新。更新工具将云服务与设备上的软件库和合作伙伴提供的引导加载程序结合使用。该威胁模型明确侧重于针对引导加载程序的威胁。
引导加载程序使用案例
• 在部署之前对固件进行数字签名和加密。• 将新的固件映像部署到单个设备、一组设备或整个队列中。• 在新固件部署到设备之后，验证其真实性和完整性。• 设备仅运行来自受信任的来源的未修改软件。• 设备可以灵活处理通过 OTA 收到的故障软件。
数据流程图
Threats一些攻击具有多种缓解措施；例如，可以在 TLS 服务器提供的证书和新固件映像的代码签名者证书中验证信任关系，以缓解旨在提供恶意固件映像的网络中间人攻击。为了最大限度提高引导加载程序的安全性，任何非引导加载程序缓解措施都被视为不可靠的。引导加载程序应具有每种攻击的内在缓解措施。设置分层缓解措施被称为纵深防御。
威胁：
• 攻击者劫持设备到服务器的连接以提供恶意固件映像。
缓解措施示例• 在引导时，引导加载程序使用已知证书验证映像的加密签名。如果验证失败，引导加载程序将回滚到上
一个映像。• 攻击者利用缓冲区溢出以将恶意行为引入到闪存中存储的现有固件映像。
缓解措施示例• 在引导时，引导加载程序将按照上面所述进行验证。如果验证失败并且没有以前的映像，引导加载程序
将停止。
68
FreeRTOS 移植指南IoT 设备引导加载程序
• 在引导时，引导加载程序将按照上面所述进行验证。如果验证失败并且没有以前的映像，引导加载程序将进入故障保护仅 OTA 模式。
• 攻击者将设备引导到以前存储的映像，从而可以利用该映像发起攻击。
缓解措施示例
• 在成功安装和测试新映像后，将擦除存储上一个映像的闪存扇区。• 在每次成功升级时，都会熔断保险丝，每个映像将会重新熔断保险丝才能运行，除非已熔断正确数量的
保险丝。• OTA 更新提供故障或恶意映像，从而导致设备无法正常运行。
缓解措施示例
• 引导加载程序启动硬件监视程序计时器，以触发回滚到上一个映像。• 攻击者修补引导加载程序以绕过映像验证，因此，设备将接受未签名的映像。
缓解措施示例
• 引导加载程序位于 ROM（只读存储器）中，无法进行修改。• 引导加载程序位于 OTP（一次性可编程存储器）中，无法进行修改。• 引导加载程序位于 ARM TrustZone 的安全区域中，无法进行修改。
• 攻击者替换验证证书，因此，设备将接受恶意映像。
缓解措施示例
• 证书位于加密协处理器中，无法进行修改。• 证书位于 ROM、OTP 或安全区域中，无法进行修改。
进一步的威胁建模
该威胁模型仅考虑引导加载程序。进一步的威胁建模可能会提高整体安全性。建议的方法是列出对手的目标、这些目标针对的资产以及资产的入口点。可以考虑为控制资产而对入口点发起的攻击以创建威胁列表。以下是 IoT 设备的目标、资产和入口点示例列表。这些列表并非详尽无遗，旨在为您提供一些启发。
对手的目标
• 敲诈钱财• 诋毁声誉• 伪造数据• 转移资源• 远程监视目标• 实际访问站点• 造成严重破坏• 灌输恐怖
主要资产
• 私有密钥• 客户端证书• CA 根证书• 安全凭证和令牌
69
FreeRTOS 移植指南Testing
• 客户的个人身份信息• 商业机密实施• 传感器数据• 云分析数据存储• 云基础设施
入口点
• DHCP 响应• DNS 响应• 基于 TLS 的 MQTT• HTTPS 响应• OTA 软件映像• 应用程序指示的其他内容，例如 USB• 实际访问总线• 开封 IC
Testing如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置 OTA 库
1. 将源文件 freertos/vendors/vendor/boards/board/ports/ota/aws_ota_pal.c 添加到aws_tests IDE 项目中。
2. 将以下测试源文件添加到 aws_tests IDE 项目：
• freertos/libraries/freertos_plus/aws/ota/test/aws_test_ota_cbor.c
• freertos/libraries/freertos_plus/aws/ota/test/aws_test_ota_agent.c
• freertos/libraries/freertos_plus/aws/ota/test/aws_test_ota_pal.c
• freertos/demos/ota/aws_iot_ota_update_demo.c
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
70
FreeRTOS 移植指南Testing
以下是 OTA 库的可移植层目标定义示例。
# OTAafr_mcu_port(ota)target_sources( AFR::ota::mcu_port INTERFACE "path/aws_ota_pal.c")
有两组 OTA 库移植测试：OTA 代理和 OTA PAL 测试 (p. 71) 和 OTA 端到端测试 (p. 72)。
OTA 代理和 OTA PAL 测试
设置本地测试环境
配置 OTA 代理和 OTA PAL 测试的源文件和标头文件
1. 打开 freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h，然后将 testrunnerFULL_OTA_AGENT_ENABLED 和testrunnerFULL_OTA_PAL_ENABLED 宏设置为 1 以启用代理和 PAL 测试。
2. 从 ota/test 中为您的设备选择签名证书。在 OTA 测试中，使用该证书进行验证。
测试代码中提供三种类型的签名证书：
• RSA/SHA1• RSA/SHA256• ECDSA/SHA256
RSA/SHA1 和 RSA/SHA256 仅可用于现有平台。ECDSA/SHA256 建议用于 OTA 更新。如果您有不同方案，联系 FFreeRTOS 工程团队。
运行测试
执行 OTA 代理和 OTA PAL 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
...
71
FreeRTOS 移植指南Validation
OTA 端到端测试设置并运行端到端 OTA 测试
1. 按照 README 文件 (freertos/tools/ota_e2e_test/README.md) 中的设置说明进行操作。2. 确保运行代理和 PAL 测试不会修改
aws_clientcredential.h、aws_clientcredential_keys.h、aws_application_version.h或 aws_ota_codesigner_certificate.h 标头文件。
3. 要运行 OTA 端到端测试脚本，请按照 README 文件 (freertos/tools/ota_e2e_test/README.md) 中的示例进行操作。
Validation要正式对设备进行 FreeRTOS ester 验证，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
移植 FreeRTOS OTA 库和引导加载程序演示后，可以开始移植低功耗蓝牙库。有关说明，请参阅移植低功耗蓝牙库 (p. 72)。
如果您的设备不支持低功耗蓝牙功能，则您已完成并可以开始 FreeRTOS 资格认证流程。有关更多信息，请参阅 。FreeRTOS 资格审查指南。
移植低功耗蓝牙库您可以使用 FreeRTOS 低功耗蓝牙库预置 Wi-Fi 并通过低功耗蓝牙发送 MQTT 消息。低功耗蓝牙库还包括更高级别的 API，可以使用它们与低功耗蓝牙堆栈直接通信。有关更多信息，请参阅 。FreeRTOS 低功耗蓝牙库（在 FreeRTOS 用户指南中）。
Note
目前，资格认证不需要移植 FreeRTOS 低功耗蓝牙库。
Prerequisites要移植低功耗蓝牙库，需要具备以下条件：
72
FreeRTOS 移植指南Porting
• 一个 IDE 项目或 CMakeLists.txt 列表文件，其中包含供应商提供的低功耗蓝牙驱动程序。
有关设置测试项目的信息，请参阅为移植设置 FreeRTOS 源代码 (p. 7)。• FreeRTOS 内核的经验证配置。
有关为您的平台配置 FreeRTOS 内核的信息，请参阅配置 FreeRTOS 内核移植 (p. 25)。• Raspberry Pi 3 Model B+，带内存卡。
Porting中的三个文件freertos/libraries/abstractions/ble_hal/include文件夹定义了 FreeRTOS 低功耗蓝牙 API：
• bt_hal_manager.h
• bt_hal_manager_adapter_ble.h
• bt_hal_gatt_server.h
每个文件包含描述 API 的注释。您必须实施以下 API：
bt_hal_manager.h
• pxBtManagerInit
• pxEnable
• pxDisable
• pxGetDeviceProperty
• pxSetDeviceProperty（所有选项都是强制性的，eBTpropertyRemoteRssi 和eBTpropertyRemoteVersionInfo 除外）
• pxPair
• pxRemoveBond
• pxGetConnectionState
• pxPinReply
• pxSspReply
• pxGetTxpower
• pxGetLeAdapter
• pxDeviceStateChangedCb
• pxAdapterPropertiesCb
• pxSspRequestCb
• pxPairingStateChangedCb
• pxTxPowerCb
bt_hal_manager_adapter_ble.h
• pxRegisterBleApp
• pxUnregisterBleApp
• pxBleAdapterInit
• pxStartAdv
• pxStopAdv
73
FreeRTOS 移植指南Testing
• pxSetAdvData
• pxConnParameterUpdateRequest
• pxRegisterBleAdapterCb
• pxAdvStartCb
• pxSetAdvDataCb
• pxConnParameterUpdateRequestCb
• pxCongestionCb
bt_hal_gatt_server.h
• pxRegisterServer
• pxUnregisterServer
• pxGattServerInit
• pxAddService
• pxAddIncludedService
• pxAddCharacteristic
• pxSetVal
• pxAddDescriptor
• pxStartService
• pxStopService
• pxDeleteService
• pxSendIndication
• pxSendResponse
• pxMtuChangedCb
• pxCongestionCb
• pxIndicationSentCb
• pxRequestExecWriteCb
• pxRequestWriteCb
• pxRequestReadCb
• pxServiceDeletedCb
• pxServiceStoppedCb
• pxServiceStartedCb
• pxDescriptorAddedCb
• pxSetValCallbackCb
• pxCharacteristicAddedCb
• pxIncludedServiceAddedCb
• pxServiceAddedCb
• pxConnectionCb
• pxUnregisterServerCb
• pxRegisterServerCb
Testing此图表显示了低功耗蓝牙测试框架。
74
FreeRTOS 移植指南Testing
为测试您的低功耗蓝牙移植，您的计算机需要通过 SSH 与启用蓝牙的外部设备 (Raspberry Pi 3 Model B+)通信，并通过低功耗蓝牙与您的设备通信。
低功耗蓝牙移植和资格认证测试以 FreeRTOS 低功耗蓝牙架构中制造商硬件堆栈之上的低级别封装层为目标。
如果使用 IDE 构建测试项目，您需要在 IDE 项目中设置库移植。
设置 IDE 测试项目如果使用 IDE 进行移植和测试，您需要先将一些源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
Important
在以下步骤中，请确保您将源文件从磁盘上位置添加到了 IDE 项目。请勿创建源文件的重复副本。
在 IDE 项目中设置低功耗蓝牙库
1. 将 freertos/vendors/vendor/boards/board/ports/ble 中的所有文件添加到 aws_testsIDE 项目中。
2. 将 freertos/libraries/abstractions/ble_hal/include 中的所有文件添加到 aws_testsIDE 项目中。
3. 将 freertos/libraries/c_sdk/standard/ble 中的所有文件添加到 aws_tests IDE 项目中。4. 打开 freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c，
然后启用所需的低功耗蓝牙驱动程序。
配置 CMakeLists.txt 文件如果使用 CMake 构建测试项目，您需要在 CMake 列表文件中为库定义一个可移植层目标。
要在 CMakeLists.txt 中定义库的可移植层目标，请按照FreeRTOS 可移植层 (p. 13)中的说明进行操作。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括示例可移植层目标定义。您可以取消注释要移植的库的定义，并对其进行修改以适合您的平台。
设置本地测试环境设置 Raspberry Pi 以用于测试
1. 按照设置 Raspberry Pi 中的说明，设置 Raspberry Pi 以及 Raspbian OS。
75
FreeRTOS 移植指南Validation
2. 从 kernel.org 存储库下载 bluez 5.50。3. 按照 kernel.org 存储库的自述文件中的说明，在 Raspberry Pi 上安装 bluez 5.50。4. 在 Raspberry Pi 中启用 SSH。有关说明，请参阅 Raspberry Pi 文档。5. 在您的计算机上，打开 freertos/libraries/abstractions/ble_hal/test/
ble_test_scripts/runPI.sh 脚本，然后将前两行中的 IP 地址更改为您的 Raspberry Pi 的 IP 地址：
#!/bin/sh
scp * [email protected]: ssh -t -t 192.168.1.4 -l root << 'ENDSSH'rm -rf "/var/lib/bluetooth/*"hciconfig hci0 resetpython test1.pysleep 1ENDSSH
运行测试执行低功耗蓝牙测试
1. 执行 runPI.sh 脚本。2. 清除存储在设备中的所有现有 BLE 绑定。3. 构建测试项目，然后将其刷写到您的设备以执行该项目。4. 在 UART 控制台中检查测试结果。
Validation要正式对设备进行 FreeRTOS，您需要使用 AWS IoT Device Tester 验证设备的移植源代码。按照中的说明进行操作使用 AWS IoT Device Tester在 FreeRTOS 用户指南中设置设备测试器以进行端口验证。要测试特定库的移植，必须在 Device Tester configs 文件夹下面的 device.json 文件中启用正确的测试组。
移植低功耗蓝牙库后，可以开始 FreeRTOS 资格认证流程。有关更多信息，请参阅 。FreeRTOS 资格认证指南。
如果设备支持 “无线更新”，则还应使用配套设备验证通过蓝牙低功耗无线更新。有关更多详细信息，请参阅下一主题使用低功耗蓝牙执行无线更新 (p. 76)。
使用低功耗蓝牙执行无线更新Introduction您可以使用 FreeRTOS 低功耗蓝牙 (BLE) 和无线更新 (OTA) 库，通过在配套设备上运行的 MQTT 代理，通过低功耗蓝牙对微控制器设备执行固件更新。此更新是使用 AWS IoT OTA 任务执行的。配套设备使用在演示应用程序中输入的 Amazon Cognito 凭证连接到 AWS IoT。授权运营商从云启动 OTA 更新。当设备通过演示应用程序连接时，会启动 OTA 更新并在设备上更新固件。
Prerequisites1. 将通过空气更新代理端口到每个微控制器设备：
76
FreeRTOS 移植指南Setup
• 按中的步骤操作。Porting (p. 66)和IoT 设备引导加载程序 (p. 67)。• 移植后，请按照Testing (p. 70)来验证 OTA PAL 测试是否通过。
2. 将低功耗蓝牙库端口到每个微控制器：• 按移植低功耗蓝牙库 (p. 72)中的步骤操作。
3. 如果您还没有 AWS 账户（免费套餐已经足够），请设置 AWS 账户。4. 您必须能够访问安卓手机作为配套设备与 Android v 6.0 或更高版本和蓝牙版本 4.2 或更高版本.5. 通过以下方式设置开发平台：
• Android Studio。• 已安装 AWS CLI。• Python3 已安装。• 适用于 Python 的 boto3 AWS 软件开发工具包 (软件开发工具包)。
Setup以下是设置所需步骤的概述。您可以跳过步骤 1 和 2，如果您已经完成这些操作来测试通过 WiFi 或以太网进行无线更新。
1. 配置存储 — 创建 S3 存储桶和策略，并配置可执行更新的 IAM 用户。2. 创建代码签名证书 — 创建签名证书并允许 IAM 用户签名固件更新。3. 配置 Amazon Cognito 身份验证 — 创建凭据提供商、用户池和应用程序对用户池的访问权限。4. 配置 Amazon FreerTos — 设置低功耗蓝牙、客户端凭据和代码签名公共证书。5. 配置 Android 应用 — — 设置凭据提供程序和用户池，然后将应用程序部署到 Android 设备。
步骤 1: 配置存储您可以跳过这些步骤，方法是启动AWS CloudFormation 模板。
1. 创建 S3 存储桶并启用版本控制以保存固件映像。2. 创建 OTA 更新服务角色并将以下托管策略添加到角色：
• AWSIotLogging• awsioTreoActions• AWSIoThings 注册• AWSS 自由更新
3. 添加内联策略添加到角色，以允许其执行 AWS IoT 操作并允许访问您创建的 S3 存储桶。4. 创建 IAM 用户，可以执行 OTA 更新。此用户可以在账户中对 AWS IoT 设备进行签名和部署固件更新，
并可以在所有设备上执行 OTA 更新。访问权限应限于受信任的实体。5. 附加 OTA 用户策略的权限。6. 创建内联策略，允许您创建的 IAM 用户对固件进行签名。
步骤 2: 创建代码签名证书创建代码签名证书，可用于对固件进行签名。导入证书时，请注意证书 ARN。
aws acm import-certificate --profile=ota-update-user --certificate file://ecdsasigner.crt --private-key file://ecdsasigner.key{
77
FreeRTOS 移植指南Setup
"CertificateArn": "arn:aws:acm:region:account:certificate/certid"}
ARN 稍后将用于创建签名配置文件。如果需要，此时可以使用以下命令创建配置文件：
aws signer put-signing-profile --profile=ota-update-user --profile-name myOTAProfile --signing-material certificateArn=arn:aws:acm:region:account:certificate/certid --platform AmazonFreeRTOS-Default --signing-parameters certname=/cert.pem{"arn": "arn:aws:signer::account:/signing-profiles/myOTAProfile"}
步骤 3: 配置 Amazon Cognito 身份验证AWS IoT 配置
首先，设置 AWS IoT 事项和策略。由于我们在 Android 手机上使用 MQTT 代理，该代理将使用 AmazonCognito 进行身份验证，因此该设备不需要 AWS IoT 证书。
在创建 AWS IoT 策略之前，您需要知道自己的 AWS 区域和 AWS 账号。
步骤 3a：创建 AWS IoT 策略
1. 登录到AWS IoT 控制台。2. 在右上角，选择您的账户，然后在我的账户记下您的 12 位账户 ID。3. 在左侧导航窗格中，选择 Settings (设置)。DEFINER自定义终端节点下，记录终端节点值。端点应
该是类似于”xxxxxxxxxxxxxx.iot.us-west-2.amazonaws.com”。在本示例中，AWS 区域为 “us-west-2”。
4. 在左侧导航窗格中，依次选择Secure中，选择策略，然后选择创建。5. 如果您的帐户中没有创建策略，您将看到消息 “您还没有任何策略”，您应该选择创建策略。6. 输入策略的名称（例如，“mqtt_iot_iot_iot_策略”）。7. 在添加语句部分中，选择高级模式。将以下 JSON 复制并粘贴到策略编辑器窗口中。将 “aws-账户编号”
替换为您的账户 ID（步骤 2）。将 “aws-区域” 替换为您的区域，例如，“us-west-2”（步骤 3）。
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iot:Connect", "Resource": "arn:aws:iot:region:account-id:*" }, { "Effect": "Allow", "Action": "iot:Publish", "Resource": "arn:aws:iot:region:account-id:*" }, { "Effect": "Allow", "Action": "iot:Subscribe", "Resource": "arn:aws:iot:region:account-id:*" }, { "Effect": "Allow", "Action": "iot:Receive", "Resource": "arn:aws:iot:region:account-id:*" }
78
FreeRTOS 移植指南Setup
]}
8. 选择创建。
步骤 3b：创建 AWS IoT 事物
1. 登录到AWS IoT 控制台。2. 在左侧导航窗格中选择管理，然后选择事物。在右上角，选择创建。3. 如果您的账户中未注册任何 IoT 事物，此时将显示消息 “您还没有任何事物”，您应选择注册事物。4. 在创建 AWS IoT 事物页面上，选择创建单个事物。5. 在存储库的将设备添加到事物注册表页面上，输入事物的名称（例如，“my_thing”）。仅允许使用字母
数字字符、连字符 (“-”) 和下划线 (“_”)。选择 Next。6. 在存储库的添加事物的证书页面，在跳过证书并创建东西中，选择创建没有证书的东西。
由于我们使用的是使用 Amazon Cognito 凭据进行身份验证和授权的 BLE 代理移动应用程序，因此不需要任何设备证书。
Amazon Cognito 配置
MQTT 代理移动应用程序的身份验证需要 Amazon Cognito。IAM 策略附加到经过身份验证的身份，以允许委托人将 AWS IoT 策略附加到证书。
步骤 3c：设置 Amazon Cognito 用户池
1. 登录 Amazon Cognito 控制台。2. 在右上方的导航区域中，选择创建用户池。3. 输入池名称（例如，“用户池”）。4. 选择 Review defaults。5. 旁边应用程序客户端中，单击添加应用程序客户端...，然后选择添加应用程序客户端。6. 输入应用程序客户端名称（例如 “mqtt_app_客户端”）。7. 确保生成客户端密钥处于选择状态。8. 选择 Create app client。9. 选择返回池详细信息。10. 在存储库的审核页上，选择创建池。11. 您应该看到一条消息，提示 “您的用户池已成功创建”。12. 记下此注册 "池 ID"。13. 在左侧导航窗格中，依次选择应用程序客户端。14. 单击显示详细信息。15. 记下 “应用程序客户端 ID” 和 “应用程序客户端密钥”。
步骤三维：Amazon Cognito 身份池
1. 登录 Amazon Cognito 控制台。2. 选择 Create new identity pool (创建新身份池)。3. 输入身份池的名称（例如，“mqtt_proxy 标识池”）。4. 扩展验证提供商。5. 选择Cognito选项卡。6. 输入用户池 ID和应用程序客户端 ID您从 “步骤 3c 保存：设置 Amazon Cognito 用户池”。
79
FreeRTOS 移植指南Setup
7. 选择 Create Pool。8. 在下一页上，选择允许为经过身份验证和未经过身份验证的身份创建新角色。9. 记下身份池 ID，其格式为 “US
eaxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
接下来，我们将 IAM 策略附加到经过身份验证的身份，以便证书可以将 IoT 策略附加到其中。
步骤 3e：将 IAM 策略附加到经过身份验证的身份
1. 打开Amazon Cognito 控制台。2. 选择您刚刚创建的身份池（例如，“mqtt_proxy 标识池”）。3. 选择编辑身份池。4. 记下分配给经过身份验证的角色的 IAM 角色（例如，“认知 _MQT_ 代理 _ 身份 _ 池认证 _ 角色”）。5. 打开 IAM 控制台。6. 在导航窗格中，选择 Roles (角色)。7. 搜索角色（例如，"Cognito_mqtt_ 代理 _ 身份 _ 池身份 _ 角色"），然后选择它。8. 选择添加内联策略，然后选择JSON。9. 输入以下策略：
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:AttachPolicy", "iot:AttachPrincipalPolicy", "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive" ], "Resource": "*" } ]}
10. 选择查看策略。11. 输入策略名称（例如，“MQttProxy 多余性”）。12. 选择 Create policy。
步骤 4: 配置 FreeRTOS启用 OTA 更新演示，如下所示：
Note
在演示运行器中，一次只能启用一个演示。
1. 打开 vendors/vendor/boards/board/aws_demos/config_files/aws_demo_config.h。
• DEFINEDCONFIG_OTA_UPDATE_DEMO_ENABLED。• 变更democonfigNETWORK_TYPES到AWSIOT_NETWORK_TYPE_BLE。
80
FreeRTOS 移植指南Setup
2. 打开 demos/include/aws_clientcredential.h:
• 更改终端节点 URLclientcredentialMQTT_BROKER_ENDPOINT[]。• 将事物名称更改为您的事物的名称（例如，“my_thing”），
在clientcredentialIOT_THING_NAME。
Note
当您使用 Amazon Cognito 凭证时，无需添加证书。3. 打开 vendors/vendor/boards/board/aws_demos/common/config_files/
aws_iot_network_config.h。
• 变更configSUPPORTED_NETWORKS和configENABLED_NETWORKS仅包含AWSIOT_NETWORK_TYPE_BLE。
4. 打开 demos/include/aws_ota_codesigner_certificate.h:
• 变更signingcredentialSIGNING_CERTIFICATE_PEM参考用于对固件二进制文件进行签名的证书。
应用程序应启动并打印演示版本：
11 13498 [iot_thread] [INFO ][DEMO][134980] Successfully initialized the demo. Network type for the demo: 212 13498 [iot_thread] [INFO ][MQTT][134980] MQTT library successfully initialized.13 13498 [iot_thread] OTA demo version 0.9.2014 13498 [iot_thread] Creating MQTT Client...
步骤 5：配置 Android 应用程序下载 Android 低功耗蓝牙 SDK 和示例应用程序，请从Amazon FreeRTOS sdkGitHub 回购。
进行以下更改：
1. 修改文件app/src/main/res/raw/awsconfiguration.json：
使用以下示例 JSON 中的说明填写 “PooliID”、“区域”、“应用程序客户端密码” 和 “应用程序客户端密码”字段。
{ "UserAgent": "MobileHub/1.0", "Version": "1.0", "CredentialsProvider": { "CognitoIdentity": { "Default": { "PoolId": "Cognito->Manage Identity Pools->Federated Identities->mqtt_proxy_identity_pool->Edit Identity Pool->Identity Pool ID", "Region": "Your region (for example us-east-1)" } } },
"IdentityManager": { "Default": {} },
"CognitoUserPool": {
81
FreeRTOS 移植指南Setup
"Default": { "PoolId": "Cognito-> Manage User Pools -> mqtt_proxy_user_pool -> General Settings -> PoolId", "AppClientId": "Cognito-> Manage User Pools -> mqtt_proxy_user_pool -> General Settings -> App clients ->Show Details", "AppClientSecret": "Cognito-> Manage User Pools -> mqtt_proxy_user_pool -> General Settings -> App clients ->Show Details", "Region": "Your region (for example us-east-1)" } }}
2. 修改文件app/src/main/java/software/amazon/freertos/DemoConstants.java：
• 指定您之前创建的策略名称（例如，“mqtt_Proxy_iot_策略”）。• 设置区域（例如，“us-east-1”）。
3. 构建并安装演示应用程序：
a. 在 Android Studio 中，选择构建、制作模块应用程序。b. 选择运行、运行应用程序。您可以转到 Android Studio 中的 logcat 窗口窗格来监控日志消息。c. 在 Android 设备上，从登录屏幕创建一个帐户。d. 创建用户。如果用户已存在，请输入该用户的凭据。e. 允许 FreeRTOS 演示访问设备的位置。f. 扫描低功耗蓝牙设备。g. 将找到的设备的滑块移动到在 上。h. 按'y '串行端口调试控制台上。i. 选择配对和 Connect。
这些区域有：更多...链接在连接后变为活动状态。您应看到连接状态更改为已连接，当连接完成时，请执行以下操作：
2019-06-06 20:11:32.160 23484-23497/software.amazon.freertos.demo I/FRD: BLE connection state changed: 0; new state: BLE_CONNECTED
在传输消息之前，FreeRTOS 设备和 Android 设备必须协商 MTU。您应在 logcat 中看到以下打印输出：
2019-06-06 20:11:46.720 23484-23497/software.amazon.freertos.demo I/FRD: onMTUChanged : 512 status: Success
设备连接到应用程序并开始使用 MQTT 代理发送 MQTT 消息。若要确认设备可以通信，请确保您可以看到MQTT_CONTROL 特征数据值更改为 01：
2019-06-06 20:12:28.752 23484-23496/software.amazon.freertos.demo D/FRD: <-<-<- Writing to characteristic: MQTT_CONTROL with data: 012019-06-06 20:12:28.839 23484-23496/software.amazon.freertos.demo D/FRD: onCharacteristicWrite for:
微控制器控制台上的完整配对
当设备与 Android 设备配对时，系统将提示您按控制台上的 “y”。在执行此步骤之前，演示将无法正常工作。
82
FreeRTOS 移植指南Testing
E (135538) BT_GATT: GATT_INSUF_AUTHENTICATION: MITM RequiredW (135638) BT_L2CAP: l2cble_start_conn_update, the last connection update command still pending.E (135908) BT_SMP: Value for numeric comparison = 39184015 13588 [InputTask] Numeric comparison:39184016 13589 [InputTask] Press 'y' to confirm17 14078 [InputTask] Key acceptedW (146348) BT_SMP: FOR LE SC LTK IS USED INSTEAD OF STK18 16298 [iot_thread] Connecting to broker...19 16298 [iot_thread] [INFO ][MQTT][162980] Establishing new MQTT connection.20 16298 [iot_thread] [INFO ][MQTT][162980] (MQTT connection 0x3ffd5754, CONNECT operation 0x3ffd586c) Waiting for operation completion.21 16446 [iot_thread] [INFO ][MQTT][164450] (MQTT connection 0x3ffd5754, CONNECT operation 0x3ffd586c) Wait complete with result SUCCESS.22 16446 [iot_thread] [INFO ][MQTT][164460] New MQTT connection 0x3ffc0ccc established.23 16446 [iot_thread] Connected to broker.
Testing1. 要安装先决条件，请运行以下命令：
pip3 install boto3pip3 install pathlib
2. 下载python脚本。3. 提升 FreeRTOS 应用程序版本demos/include/aws_application_version.h并构建一个新的二
进制文件。4. 要获得帮助，请在终端窗口运行以下命令：
python3 start_ota.py -h
usage: start_ota.py [-h] --profile PROFILE [--region REGION] [--account ACCOUNT] [--devicetype DEVICETYPE] --name NAME --role ROLE --s3bucket S3BUCKET --otasigningprofile OTASIGNINGPROFILE --signingcertificateid SIGNINGCERTIFICATEID [--codelocation CODELOCATION]Script to start OTA updateoptional arguments:-h, --help show this help message and exit--profile PROFILE Profile name created using aws configure--region REGION Region--account ACCOUNT Account ID--devicetype DEVICETYPE thing|group--name NAME Name of thing/group--role ROLE Role for OTA updates--s3bucket S3BUCKET S3 bucket to store firmware updates--otasigningprofile OTASIGNINGPROFILE Signing profile to be created or used--signingcertificateid SIGNINGCERTIFICATEID certificate id (not arn) to be used--codelocation CODELOCATION base folder location (can be relative)
5. 如果您使用提供的 AWS CloudFormation 模板创建资源，请参阅以下示例运行：
python3 start_ota_stream.py --profile otausercf --name my_thing --role ota_ble_iot_role-sample --s3bucket afr-ble-ota-update-bucket-sample --otasigningprofile abcd --signingcertificateid certificateid
83
FreeRTOS 移植指南Validation
Validation1. 从控制台，日志显示 OTA 更新已开始，并且正在进行文件块下载：
38 2462 [OTA Task] [prvParseJobDoc] Job was accepted. Attempting to start transfer.---49 2867 [OTA Task] [prvIngestDataBlock] Received file block 1, size 102450 2867 [OTA Task] [prvIngestDataBlock] Remaining: 129051 2894 [OTA Task] [prvIngestDataBlock] Received file block 2, size 102452 2894 [OTA Task] [prvIngestDataBlock] Remaining: 128953 2921 [OTA Task] [prvIngestDataBlock] Received file block 3, size 102454 2921 [OTA Task] [prvIngestDataBlock] Remaining: 128855 2952 [OTA Task] [prvIngestDataBlock] Received file block 4, size 102456 2953 [OTA Task] [prvIngestDataBlock] Remaining: 128757 2959 [iot_thread] State: Active Received: 5 Queued: 5 Processed: 5 Dropped: 0
2. OTA 更新完成后，设备将使用更新的固件重新启动，再次连接到 Android 应用程序，然后执行自检。3. 如果自检成功，更新后的固件将被标记为活动状态，您应该在控制台中看到更新的版本：
13 13498 [iot_thread] OTA demo version 0.9.21
References1. 关于 OTA 的 AWS 博客更新低功耗蓝牙。
移植通用 I/O 库通常，设备驱动程序独立于基础操作系统，并且特定于给定的硬件配置。硬件抽象层 (HAL) 是一个包装程序，它提供驱动程序和更高级别的应用程序代码之间的通用接口。HAL 提取出特定驱动程序如何工作的详细信息，并提供一个统一的 API 来控制相似设备。这样一来，您可以使用相同的 API 跨多个基于微控制器(MCU) 的参考板来控制各种设备。
FreeRTOS 通用 I/O 将充当硬件抽象层。它提供了一组标准 API，用于跨受支持的参考板访问常用串行设备。这些 API 与一些常见的外围设备进行通信和交互，可让您的应用程序代码跨平台运行。如果没有通用 I/O，则使用低级设备所需的代码是特定于芯片供应商的。
支持的外围设备
• UART• SPI• I2C
支持的功能
• 同步读/写 — 直到传输了请求的数据量后才返回。• 异步读/写 — 函数立即返回，并且数据以异步方式传输。在函数执行完成后，将调用已注册用户回调。
外围设备特定的
• I2C — 将多个操作合并到一个事务中，通常会在一个事务中依次执行写入操作和读取操作。
84
FreeRTOS 移植指南Prerequisites
• SPI — 在主设备和辅助设备之间传输数据，这意味着写入操作和读取操作将同时进行。
移植
请参阅FreeRTOS 移植指南。
主题• Prerequisites (p. 85)• Testing (p. 85)• 移植 I2C 库 (p. 87)• 移植 UART 库 (p. 89)• 移植 SPI 库 (p. 91)
Prerequisites要移植常用 I/O 库，您需要：
• 一个包括供应商提供的 I/O 驱动程序的 IDE 项目或 CMakeLists.txt 列表文件。• FreeRTOS 内核的经验证配置。
Testing首先，请设置 IDE 项目或配置 CMake。
设置本地测试环境
无需对测试文件 freertos/libraries/abstractions/common_io/test/test_iot_peripheral.c 进行更改。
特定于设备的代码位于以下文件中
• freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h
• freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c
设置本地测试环境
1. 创建一个名为 freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h 的测试配置标头文件。有关该文件的内容，请参阅每个外围设备的“TestSetup”部分。
2. 创建一个名为 freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c 的测试设置文件。有关该文件的内容，请参阅每个外围设备的“测试设置”部分。
3. 要启用通用 I/O 测试，请打开文件freertos/vendors/vendor/boards/board/aws_tests/config_files/aws_test_runner_config.h。
4. 将 testrunnerFULL_COMMON_IO_ENABLED 设置为 1
设置 IDE 测试项目
如果使用 IDE 进行移植和测试，您必须先将源文件添加到 IDE 测试项目中，然后才能测试移植的代码。
85
FreeRTOS 移植指南Testing
Important
在以下步骤中，请确保您将源文件从当前的磁盘上位置添加到 IDE 项目中。请勿创建源文件的重复副本。
在 IDE 项目中设置通用 I/O 库
1. 将所有实施源文件 freertos/vendors/vendor/boards/board/ports/common_io/iot_peripheral.c 添加到 aws_tests IDE 项目中（每个外围设备一个文件）。
2. 将所有测试源文件 freertos/libraries/abstractions/common_io/test/test_iot_peripheral.c 添加到 aws_tests IDE 项目中（每个外围设备一个文件）。
3. 将测试配置文件 freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h 添加到 aws_tests IDE 项目中（对于所有外围设备，仅添加这一个文件）。
4. 将测试设置文件 freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c 添加到 aws_tests IDE 项目中（对于所有外围设备，仅添加这一个文件）。
配置 CMakeLists.txt 文件
如果使用 CMake 构建测试项目，您必须在 CMake 列表文件中为库定义一个可移植层目标。
freertos/vendors/vendor/boards/board/CMakeLists.txt 中的 CMakeLists.txt 模板列表文件包括可移植层目标定义示例。取消注释每个要移植的库的定义，并对其进行修改以适合您的平台。
Example
以下是通用 I/O 库的可移植层目标定义。
# Common I/Oafr_mcu_port(common_io)target_sources( AFR::common_io::mcu_port INTERFACE # peripheral implementations freertos/vendors/vendor/boards/board/ports/common_io/iot_peripheral_1.c freertos/vendors/vendor/boards/board/ports/common_io/iot_peripheral_2.c freertos/vendors/vendor/boards/board/ports/common_io/iot_peripheral_3.c ... # test configuration and pre-steps freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c)
# -------------------------------------------------------------------------------------------------# FreeRTOS demos and tests# -------------------------------------------------------------------------------------------------
...
if(AFR_IS_TESTING) set(exe_target aws_tests)else() set(exe_target aws_demos)endif()
...
# link common io library along with otherstarget_link_libraries(
86
FreeRTOS 移植指南移植 I2C 库
${exe_target} PRIVATE AFR::wifi AFR::utils AFR::common_io)
运行测试
执行通用 I/O 测试
1. 构建测试项目，然后将其刷写到您的设备以执行该项目。2. 在 UART 控制台中检查测试结果。
移植 I2C 库I2C 库与供应商提供的 I2C 驱动程序进行交互。如果设备没有 I2C 外围设备，则可以跳过移植 I2C 接口这一步。I2C 库只能将设备上的 I2C 外围设备用作主设备。
先决条件
要移植 I2C 库，您需要 I2C 辅助设备。它可以是下列项之一：
• 一个板载 I2C 传感器。• 一个外部设备，如 Raspberry PI。
移植
使用供应商提供的 I2C 驱动程序库实施 freertos/libraries/abstractions/common_io/include/iot_i2c.h 中的所有函数。标头文件提供了所需的 API 行为信息。应创建一个实施源文件并将其命名为freertos/vendors/vendor/boards/board/ports/common_io/iot_i2c.c。
如果任何 I2C 功能在目标设备上均不受支持，请让相应的函数返回IOT_I2C_FUNCTION_NOT_SUPPORTED。有关可返回 IOT_I2C_FUNCTION_NOT_SUPPORTED 的函数的列表，请参阅 freertos/libraries/abstractions/common_io/include/iot_i2c.h 中记录的API。
匿名句柄“struct IotI2CDescriptor”
这通常将封装驱动程序的句柄和各种状态。请参阅以下 示例。
/* Suppose the data type of driver handle for I2C is Driver_I2C_Handle */struct IotI2CDescriptor{ Driver_I2C_Handle xHandle; /* Driver Handle. */ IotI2CConfig_t xConfig; /* Bus Configuration. */ IotI2CCallback_t xCallback; /* Callback function. */ void * pvUserContext; /* User context passed in callback. */ uint16_t usSlaveAddr; /* Slave Address. */ uint16_t usTransmittedTxBytes; /* Number of Transmitted Bytes */ uint16_t usReceivedRxBytes; /* Number of Received Bytes */ SemaphoreHandle_t xSemphr; /* Optional, useful when there is a synchronization situation. */ /* State: if already opened. */ /* State: if send no stop. */};
87
FreeRTOS 移植指南移植 I2C 库
测试设置硬件设置
如果您使用板载传感器作为从属设备，则可跳过此步骤。
如果您使用外部设备，则需要连接两个设备的 SDA（数据）线和 SCL（时钟）线。
可以在以下目录中找到 I2C 测试文件：freertos/libraries/abstractions/common_io/test/test_iot_i2c.c
测试设置配置
1. 将 I2C 配置添加到 freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h。
IOT_TEST_COMMON_IO_I2C_SUPPORTED
如果此设备具有 I2C 外围设备，则设置为 1。否则，将它设置为 0。IOT_TEST_COMMON_IO_I2C_SUPPORTED_SEND_NO_STOP
如果 I2C 未明确支持发送停止条件，则设置为 1。否则，设置为 0。IOT_TEST_COMMON_IO_I2C_SUPPORTED_CANCEL
如果 I2C 支持通过中断或 DMA 取消异步事务，则设置为 1。否则，设置为 0。I2C_TEST_SET
指定要测试的 I2C 实例的数目。2. 在 freertos/vendors/vendor/boards/board/aws_tests/config_files/
test_iot_config.h 文件中定义测试数据。
i2cTestInstanceIdx
I2C 实例 ID。i2cTestInstanceNum
I2C 实例总数。i2cTestSlaveAddr
设备地址。i2cTestDeviceRegister
在测试设备上注册地址。i2cTestWriteVal
要写入测试设备的字节值。gIotI2cHandle
未使用。将它定义为要编译的 null 数组。
Example
/* I2C includes */#include "iot_i2c.h"
#define IOT_TEST_COMMON_IO_I2C_SUPPORTED 1
88
FreeRTOS 移植指南移植 UART 库
#if ( IOT_TEST_COMMON_IO_I2C_SUPPORTED == 1 ) #define IOT_TEST_COMMON_IO_I2C_SUPPORTED_SEND_NO_STOP 1 #define IOT_TEST_COMMON_IO_I2C_SUPPORTED_CANCEL 1#endif
#define I2C_TEST_SET 1
/* Slave address. */const uint8_t i2cTestSlaveAddr[ I2C_TEST_SET ] = { 0xD4 };/* Register address. */const uint8_t i2cTestDeviceRegister[ I2C_TEST_SET ] = { 0x73 };/* A value that is written to slave device during test. */const uint8_t i2cTestWriteVal[ I2C_TEST_SET ] = { 0b01101010 };/* I2C instance ID. */const uint8_t i2cTestInstanceIdx[ I2C_TEST_SET ] = { 1 };/* Total number of I2C instances. */const uint8_t i2cTestInstanceNum[ I2C_TEST_SET ] = { 3 };
/* Unused, but this needs to be defined. */IotI2CHandle_t gIotI2cHandle[ 4 ] = { NULL, NULL, NULL, NULL };
3. 将 I2C 测试设置代码添加到 freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c 文件中。
#include "test_iot_internal.h"
/* These global variables are defined in test_iot_i2c.c. */extern uint8_t uctestIotI2CSlaveAddr;extern uint8_t xtestIotI2CDeviceRegister;extern uint8_t uctestIotI2CWriteVal;extern uint8_t uctestIotI2CInstanceIdx;extern uint8_t uctestIotI2CInstanceNum;
void SET_TEST_IOT_I2C_CONFIG(int testSet){ uctestIotI2CSlaveAddr = i2cTestSlaveAddr[testSet]; xtestIotI2CDeviceRegister = i2cTestDeviceRegister[testSet]; uctestIotI2CWriteVal = i2cTestWriteVal[testSet]; uctestIotI2CInstanceIdx = i2cTestInstanceIdx[testSet]; uctestIotI2CInstanceNum = i2cTestInstanceNum[testSet];}
移植 UART 库UART 库与供应商提供的 UART 驱动程序进行交互。如果设备没有任何 UART 外围设备，则可以跳过移植UART 接口这一步。
Prerequisites
• 使用跳线连接 UART 的 RX 和 TX 以进行环回测试。
移植
使用供应商提供的 UART 驱动程序库实施 freertos/libraries/abstractions/common_io/include/iot_uart.h 中的所有函数。标头文件提供了有关所需的 API 行为的信息。应创建一个实施源文件并将其命名为 freertos/vendors/vendor/boards/board/ports/common_io/iot_uart.c。
如果目标设备不支持任何 UART 功能，请让相应的函数放回 IOT_UART_FUNCTION_NOT_SUPPORTED。有关可返回 IOT_UART_FUNCTION_NOT_SUPPORTED 的函数的列表，请参阅 freertos/libraries/abstractions/common_io/include/iot_uart.h 中记录的 API。
89
FreeRTOS 移植指南移植 UART 库
匿名句柄“struct IotUARTDescriptor”
这通常将封装驱动程序的句柄和各种状态。请参阅以下 示例。
/* Suppose the data type of the driver handle for UART is UART_Handle */struct IotUARTDescriptor{ IotUARTCallback_t xUartCallback; /* Application Specified callback. */ UART_Handle * pxUartContext; /* UART handle to be passed to driver functions. */ void * pvUserCallbackContext; / uint8_t sOpened;};
测试设置硬件设置
在要测试的 UART 端口上，使用跳线连接 TX 和 RX 来进行环回测试。
可以在以下目录中找到 UART 测试文件：freertos/libraries/abstractions/common_io/test/test_iot_uart.c
测试设置配置
1. 将 UART 配置添加到 freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h 文件中。
IOT_TEST_COMMON_IO_UART_SUPPORTED
如果此设备具有 UART 外围设备，则设置为 1。否则，设置为 0。UART_TEST_SET
要测试的 UART 实例的数目。2. 在 freertos/vendors/vendor/boards/board/aws_tests/config_files/
test_iot_config.h 文件中定义测试数据。
uartTestPort
UART 实例 ID。uartIotUartFlowControl
UART 流控制配置。uartIotUartParity
UART 奇偶校验位配置。uartIotUartWordLength
UART 字长配置。uartIotUartStopBits
UART 停止位配置。
Example
/* UART */#define UART_TEST_SET 1const uint8_t uartTestPort[ UART_TEST_SET ] = { 1 };const uint32_t uartIotUartFlowControl[ UART_TEST_SET ] = { UART_FLOW_CONTROL };
90
FreeRTOS 移植指南移植 SPI 库
const uint32_t uartIotUartParity[ UART_TEST_SET ] = { UART_PARITY };const uint32_t uartIotUartWordLength[ UART_TEST_SET ] = { UART_WORD_LENGTH };const uint32_t uartIotUartStopBits[ UART_TEST_SET ] = { UART_STOP_BITS };
3. 将 UART 测试设置代码添加到 freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c 文件中。
#include "test_iot_internal.h"
/* UART */extern uint8_t ustestIotUartPort;extern uint32_t ultestIotUartFlowControl;extern uint32_t ultestIotUartParity;extern uint32_t ultestIotUartWordLength;extern uint32_t ultestIotUartStopBits;
void SET_TEST_IOT_UART_CONFIG( int testSet ){ ustestIotUartPort = uartTestPort[ testSet ]; ultestIotUartFlowControl = uartIotUartFlowControl[ testSet ]; ultestIotUartParity = uartIotUartParity[ testSet ]; ultestIotUartWordLength = uartIotUartWordLength[ testSet ]; ultestIotUartStopBits = uartIotUartStopBits[ testSet ];}
移植 SPI 库SPI 库与供应商提供的 SPI 驱动程序进行交互。如果设备没有 SPI 外围设备，则可以跳过移植 SPI 接口这一步。SPI 库只能将设备上的 SPI 外围设备用作控制器。
移植
使用供应商提供的 SPI 驱动程序库实施 freertos/libraries/abstractions/common_io/include/iot_spi.h 中的所有函数。标头文件提供了所需的 API 行为信息。应将实施源文件创建为 freertos/vendors/vendor/boards/board/ports/common_io/iot_spi.c。
目标设备可能不支持一些 SPI 功能。在此情况下，让相应的函数返回IOT_SPI_FUNCTION_NOT_SUPPORTED。有关可返回 IOT_SPI_FUNCTION_NOT_SUPPORTED 的函数的列表，请参阅 freertos/libraries/abstractions/common_io/include/iot_spi.h 中记录的API。
匿名句柄“struct IotSPIDescriptor”
这通常将封装驱动程序的句柄和各种状态。请参阅以下 示例。
/* Suppose the data type of driver handle for SPI is Driver_SPI_Handle */struct IotSPIDescriptor{ Driver_SPI_Handle xHandle; /* Driver Handle. */ IotSPIConfig_t xConfig; /* Bus Configuration. */ IotSPICallback_t xCallback; /* Callback function. */ void * pvUserContext; /* User context passed in callback. */ /* State: if already opened. */};
测试设置可以在以下目录中找到 SPI 测试文件：freertos/libraries/abstractions/common_io/test/test_iot_spi.c
91
FreeRTOS 移植指南移植 SPI 库
测试设置配置
1. 将 SPI 配置添加到 freertos/vendors/vendor/boards/board/aws_tests/config_files/test_iot_config.h 文件中。
IOT_TEST_COMMON_IO_SPI_SUPPORTED
如果设备具有 SPI 外围设备，则将它设置为 1。否则，设置为 0。SPI_TEST_SET
要测试的 SPI 实例的数目。2. 在 freertos/vendors/vendor/boards/board/aws_tests/config_files/
test_iot_config.h 文件中定义测试数据。
spiTestPort
SPI 实例 ID。spiIotMode
SPI 模式。spiIotSpitBitOrder
SPI 位顺序。spiIotFrequency
SPI 频率。spiIotDummyValue
虚拟值。
Example
/* SPI includes */#include "iot_spi.h"
#define IOT_TEST_COMMON_IO_SPI_SUPPORTED 1#define I2C_TEST_SET 1
const uint8_t spiTestPort[ SPI_TEST_SET ] = { 1 };const uint32_t spiIotMode[ SPI_TEST_SET ] = { eSPIMode0 };const uint32_t spiIotSpitBitOrder[ SPI_TEST_SET ] = { eSPIMSBFirst };const uint32_t spiIotFrequency[ SPI_TEST_SET ] = { 500000U };const uint32_t spiIotDummyValue[ SPI_TEST_SET ] = { 0 };
3. 在 freertos/vendors/vendor/boards/board/ports/common_io/test_iot_internal.c文件中添加 SPI 测试设置代码。
#include "test_iot_internal.h"
/* SPI */extern uint8_t ultestIotSpiInstance;extern IotSPIMode_t xtestIotSPIDefaultConfigMode;extern IotSPIBitOrder_t xtestIotSPIDefaultconfigBitOrder;extern uint32_t ultestIotSPIFrequency;extern uint32_t ultestIotSPIDummyValue;
void SET_TEST_IOT_SPI_CONFIG(int testSet){ ultestIotSpiInstance = spiTestPort[ testSet ] ;
92
FreeRTOS 移植指南蜂窝
xtestIotSPIDefaultConfigMode = spiIotMode[ testSet ]; xtestIotSPIDefaultconfigBitOrder = spiIotSpitBitOrder[ testSet ]; ultestIotSPIFrequency = spiIotFrequency[ testSet ]; ultestIotSPIDummyValue = spiIotDummyValue[ testSet ];}
移植移植移植移植库FreerTOS 实验室现在支持 AT 命令，TCP 卸载蜂窝抽象层。有关更多信息，请参阅 。免费实验室-蜂窝图书馆和移植指南，了解更多信息。
Note
蜂窝图书馆位于 FreerTOS 实验室中。FreerTOS 实验室下载的库功能齐全，但正在对其实施、文档和编码风格进行改进。
Prerequisites蜂窝库没有直接依赖关系，但是，在 FreerTOS 网络堆栈中，以太网、Wi-Fi 和蜂窝网络无法共存，因此开发人员必须选择其中一个来与安全套接字库。
Note
如果蜂窝模块能够支持 TLS 卸载，或者不支持 AT 命令，开发人员可以实现自己的蜂窝抽象，以便与安全套接字库。
93
FreeRTOS 移植指南迁移应用程序
从版本 1.4.x 迁移到版本201906.00（和更高版本）
有关 FreeRTOS 版本的列表，请参阅https://github.com/aws/amazon-freertos/releases。
迁移应用程序FreeRTOS 版本 201906.00 对 FreeRTOS 目录结构进行了一些更改，从而拆分在以前版本的上构建的FreeRTOS 文件。要使在以前版本的上构建的文件能够用于 FreeRTOS 版本 201906.00 或更高版本，您必须将应用程序代码移动到新项目中，并在应用程序中包含 201906.00 标头文件。
版本 201906.00 为 MQTT、Device Shadow 和 Device Defender 库引入了新的 API。这些库的早期版本 API可通过这些库的 201906.00 实施的标头文件访问，使得版本 201906.00 实现向后兼容。
Note
如果从以前版本迁移到 201906.00 或更高版本，您可能需要重新配置 iot_config.h 和FreeRTOSConfig.h 文件以适合新的库实施。有关全局配置设置的信息，请参阅全局配置文件参考。
迁移移植项如果移植了在 201906.00 版本之前发布的版本，则需要迁移移植的代码，以便与 201906.00 和更高版本保持兼容。有关移植的信息，请参阅FreeRTOS 移植指南。
FreeRTOS 代码目录结构在 201906.00 之前发布的版本中，freertos/lib/third_party/mcu_vendor/vendor 文件夹保留供应商移植的代码。相同 vendor 文件夹编译了代码。在 201906.00 和更高版本中，供应商代码位于freertos/vendors/vendor 文件夹中，项目文件位于 freertos/projects/vendor 文件夹中。
Note
不会在版本 201906.00 中更改移植代码，而仅更改代码的位置。将现有移植项移动到新文件夹结构。
CMake 构建系统版本 201906.00 引入了对使用 CMake 生成项目文件的支持。有关将 CMake 与 FreeRTOS 结合使用的信息，请参阅使用 CMake 构建 FreeRTOS (p. 17)。
资格认证需要 CMake 列表文件。有关创建 CMake 列表文件的信息，请参阅创建 CMake 列表文件 (p. 10)。
迁移 Wi-Fi 库移植项FreeRTOS Wi-Fi 库具有四个新的 API 用于添加、删除和检索 Wi-Fi 网络，以及接收 Wi-Fi 网络状态更改的通知。所有这些新 API 是可选的，其目的是支持通过低功耗蓝牙的 Wi-Fi 凭证预置。如果您的设备不支持低功耗蓝牙，则无需实施这些 API。
94
FreeRTOS 移植指南迁移 Wi-Fi 库移植项
• WIFI_NetworkAdd
WIFIReturnCode_t WIFI_NetworkAdd( const WIFINetworkProfile_t * const pxNetworkProfile, uint16_t * pusIndex );
• WIFI_NetworkGet
WIFIReturnCode_t WIFI_NetworkGet( WIFINetworkProfile_t * pxNetworkProfile, uint16_t usIndex );
• WIFI_NetworkDelete
WIFIReturnCode_t WIFI_NetworkDelete( uint16_t usIndex );
• WIFI_RegisterNetworkStateChangeEventCallback
WIFIReturnCode_t WIFI_RegisterNetworkStateChangeEventCallback( IotNetworkStateChangeEventCallback_t xCallback );
使用以下 typedef 语句：
typedef void ( *IotNetworkStateChangeEventCallback_t ) ( uint32_t ulNetworkType, AwsIotNetworkState_t xState );
typedef enum AwsIotNetworkState{ eNetworkStateUnknown = 0, eNetworkStateDisabled, eNetworkStateEnabled} AwsIotNetworkState_t;
有关移植 Wi-Fi 库的信息，请参阅移植 Wi-Fi 库，请参阅 FreeRTOS 移植指南。
95
FreeRTOS 移植指南
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
xcvi
![Ⅲ 動物･植物の移植･移設 植物50 キンランの移植 › lab › bcg › siryou › tnn › tnn0721pdf › ks072116.pdfⅢ 動物･植物の移植･移設 [植物50]](https://img.pdfslide.tips/doc/110x75/5f20d7626a9ce60d0f75979a/a-ciccice-c50-fffc-a-lab-a.jpg)
