本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # AWS IoT 空中下载 (OTA) 库 **注意** 此页面上的内容可能不是最新的。有关最新更新，请参阅 [FreeRTOS.org 库页面](https://www.freertos.org/Documentation/03-Libraries/01-Library-overview/01-All-libraries)。 ## 简介 利用 [AWS IoT 空中下载 (OTA) 更新库](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/index.html)，您可以使用 HTTP 或 MQTT 作为协议来管理 FreeRTOS 设备固件更新的通知、下载和验证。通过使用 OTA 代理库，可以从逻辑上将固件更新与设备上运行的应用程序进行隔离。OTA 代理可以与应用程序共享网络连接。通过共享网络连接，有可能节省大量的 RAM。此外，可使用 OTA 代理库来定义特定于应用程序的逻辑，以测试、提交或回滚固件更新。 物联网 (IoT) 将互联网连接扩展到传统上未连接的嵌入式设备。您可以对这些设备进行编程，使其通过互联网传输可用数据，并且可以进行远程监控和控制。随着技术的进步，这些传统嵌入式设备正在快速获得消费者、工业和企业领域的互联网功能。 IoT 设备的部署规模通常很大，并且通常部署在操作人员难以接近或根本无法接近的位置。想象一下发现可能暴露数据的安全漏洞的场景。在这种情况下，使用安全修复程序快速可靠地更新受影响的设备非常重要。如果无法执行 OTA 更新，那么更新在地理位置上分散的设备也可能很困难。让技术人员更新这些设备既昂贵又耗时，而且往往不切实际。更新这些设备所需的时间会使它们在更长的时间内面临安全漏洞。召回这些设备进行更新也需要付出高昂的代价，并可能因停机而对消费者造成严重干扰。 空中下载 (OTA) 更新使设备固件更新成为了可能，无需进行昂贵的召回或技术人员拜访。该方法增加了以下好处： + **安全** – 能够快速响应在现场部署设备后发现的安全漏洞和软件错误。 + **创新** – 随着新功能的开发，产品可以经常更新，从而推动创新周期。与传统更新方法相比，这种更新不仅可以快速生效，而且停机时间最短。 + **成本** – 与传统上用于更新这些设备的方法相比，OTA 更新可以显著降低维护成本。 提供 OTA 功能需要考虑以下设计注意事项： + **安全通信** – 更新必须使用加密的通信渠道，以防止下载内容在传输过程中被篡改。 + **恢复** – 由于网络连接中断或收到无效更新等原因，更新可能会失败。在这些情况下，设备需要能够恢复到稳定状态和避免变砖。 + **作者验证** – 必须验证更新是否来自可信来源，同时还要进行其他验证，例如检查版本和兼容性。 有关使用 FreeRTOS 设置 OTA 更新的更多信息，请参阅 [FreeRTOS 更新 Over-the-Air](freertos-ota-dev.md)。 ### AWS IoT 空中下载 (OTA) 库 凭借 AWS IoT OTA 库，您可以管理有关新更新的通知、下载更新并对固件更新进行加密验证。使用空中下载 (OTA) 客户端库，您可以在逻辑上将固件更新机制与设备上运行的应用程序分开。空中下载 (OTA) 客户端库可以与应用程序共享网络连接，从而在资源有限的设备中节省内存。此外，使用空中下载 (OTA) 客户端库可定义特定于应用程序的逻辑，从而测试、提交或回滚固件更新。该库支持不同的应用程序协议，例如消息队列遥测传输 (MQTT) 和超文本传输协议 (HTTP)，并提供各种配置选项，您可以根据自己的网络类型和条件进行微调。 该库的 API 提供以下主要功能： + 注册接收通知或投票以获取可用的新更新请求。 + 接收、解析和验证更新请求。 + 根据更新请求中的信息下载并验证文件。 + 在激活收到的更新之前进行自测，以确保更新的功能有效性。 + 更新设备的状态。 该库使用 AWS 服务来管理各种与云相关的功能，例如发送固件更新、监控多个区域的大量设备、缩小错误部署的影响范围以及验证更新的安全性。该库可以与任何 MQTT 或 HTTP 库一起使用。 该库的演示介绍了在 FreeRTOS 设备上使用 coreMQTT 库和 AWS 服务进行完整的空中下载更新。 ## 特征 下面是完整的 OTA 代理接口： **`[ OTA\$1Init](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#ae5cc1dcc13fbcb32230f552f48b24f03)`** 通过在系统中启动 OTA 代理（“OTA 任务”）来初始化 OTA 引擎。只能存在一个 OTA 代理。 **`[ OTA\$1Shutdown](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#ac779291eb93f4e0e6459816e60e13b09)`** 向 OTA 代理发出关闭信号。OTA 代理可以选择取消订阅所有 MQTT 作业通知主题，停止正在进行的 OTA 作业（如果有），并清除所有资源。 **`[ OTA\$1GetState](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a6db3f9cb417cb135cb0e68f5b5f2b11f)`** 获取 OTA 代理的当前状态。 **`[ OTA\$1ActivateNewImage](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a5169ba09148e7f5668a90e776e712f8b)`** 激活通过 OTA 收到的最新的微控制器固件映像。（详细的作业状态现在应当为“自检”。） **`[ OTA\$1SetImageState](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#ab68cdf65934474e1f3d2cd1046314bea)`** 设置当前运行的微控制器固件映像的验证状态（正在测试、已接受或已拒绝）。 **`[ OTA\$1GetImageState](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a9c5b25f9a7eff3ded8cdf088c2011742)`** 获取当前运行的微控制器固件映像的状态（正在测试、已接受或已拒绝）。 **`[ OTA\$1CheckForUpdate](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a1178e8009eb05e6f55f6506b625c9fc2)`** 从 OTA 更新服务请求下一个可用的 OTA 更新。 **`[ OTA\$1Suspend](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a65b61ae5dd477e8b2e6c88ea0473c62b)`** 暂停所有 OTA 代理操作。 **`[ OTA\$1Resume](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#ae9d40388ac87e4ac93288de37c98a138)`** 恢复 OTA 代理操作。 **`[ OTA\$1SignalEvent](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a2564144f284db077b8947ba58a6a72bb)`** 向 OTA 代理任务发出事件信号。 **`[ OTA\$1EventProcessingTask](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#ab3a0cfdc8694a606a1d736b2f54fb113)`** OTA 代理事件处理循环。 **`[ OTA\$1GetStatistics](https://docs.aws.amazon.com/freertos/latest/lib-ref/embedded-csdk/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a63182243ef3c18d5f36cd427b83a1a22)`** 获取 OTA 消息包的统计信息，包括接收、排队、处理和丢弃的数据包数量。 **`[ OTA\$1Err\$1strerror](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a6f72911b8fe80f27bce42c3a36dca4b3)`** OTA 错误的字符串转换错误代码。 **`[ OTA\$1JobParse\$1strerror ](https://docs.aws.amazon.com/embedded-csdk/latest/lib-ref/libraries/aws/ota-for-aws-iot-embedded-sdk/docs/doxygen/output/html/ota_8c.html#a1d42efa1af7fa0ed92060a3b7e869648)`** 将 OTA 作业解析错误代码转换为字符串。 **`[ OTA\$1PalStatus\$1strerror](https://aws.github.io/ota-for-aws-iot-embedded-sdk/v3.4.0/ota_8c.html#a5a58be1ac41b7d619eeeb4861be37c89)`** OTA PAL 状态的状态代码转换为字符串。 **`[ OTA\$1OsStatus\$1strerror](https://aws.github.io/ota-for-aws-iot-embedded-sdk/v3.4.0/ota_8c.html#a4951f4bb1bfbb7312850454ca2b282a4)`** OTA OS 状态的状态代码转换为字符串。 ## API 参考 有关更多信息，请参阅 [AWS IoT 空中下载更新：函数](https://aws.github.io/ota-for-aws-iot-embedded-sdk/v3.4.0/ota_functions.html)。 ## 示例用法 使用 MQTT 协议的典型的支持 OTA 的设备应用程序采用以下 API 调用顺序来驱动 OTA 代理。 1. 连接到 AWS IoT coreMQTT 代理。有关更多信息，请参阅 [coreMQTT 代理库](coremqtt-agent.md)。 1. 通过调用 `OTA_Init` 来初始化 OTA 代理（包括缓冲区、所需的 OTA 接口、事物名称和应用程序回调）。回调实施特定于应用程序的逻辑，于 OTA 更新作业完成后执行。 1. OTA 更新完成后，FreeRTOS 调用具有以下事件之一的作业完成回调：`accepted`、`rejected` 或 `self test`。 1. 如果新的固件映像已遭拒绝（例如，由于验证错误），应用程序通常可以忽略通知并等待下一次更新。 1. 如果更新有效且标记为“已接受”，可调用 `OTA_ActivateNewImage` 重置设备并启动新的固件映像。 ## 移植 有关将 OTA 功能移植到您的平台的信息，请参阅《FreeRTOS 移植指南》中的[移植 OTA 库](https://docs.aws.amazon.com/freertos/latest/portingguide/afr-porting-ota.html)。 ## 内存使用 **** | AWS IoT OTA 的代码大小（使用 GCC for ARM Cortex-M 生成的示例） | 文件 | 使用 -O1 优化 | 使用 -Os 优化 | | --- | --- | --- | --- | | ota.c | 8.3K | 7.5K | | ota\$1interface.c | 0.1K | 0.1K | | ota\$1base64.c | 0.6K | 0.6K | | ota\$1mqtt.c | 2.4K | 2.2K | | ota\$1cbor.c | 0.8K | 0.6K | | ota\$1http.c | 0.3K | 0.3K | | 估计总数 | 12.5K | 11.3K |