本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS IoT 無線 (OTA) 程式庫 **注意** 此頁面上的內容可能不是up-to-date。如需最新更新，請參閱 [FreeRTOS.org 程式庫頁面](https://www.freertos.org/Documentation/03-Libraries/01-Library-overview/01-All-libraries)。 ## 簡介 [AWS IoT Over-the-air(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) 程式庫 OTA AWS IoT 程式庫可讓您管理新可用更新的通知、下載更新，以及執行韌體更新的密碼編譯驗證。您可以使用over-the-air(OTA) 用戶端程式庫，以邏輯方式將韌體更新機制與裝置上執行的應用程式分開。over-the-air(OTA) 用戶端程式庫可與應用程式共用網路連線，以節省資源受限裝置的記憶體。此外，over-the-air(OTA) 用戶端程式庫可讓您定義應用程式特定的邏輯，以測試、遞交或復原韌體更新。程式庫支援不同的應用程式通訊協定，例如訊息佇列遙測傳輸 (MQTT) 和超文字傳輸通訊協定 (HTTP)，並提供各種組態選項，您可以根據網路類型和條件進行微調。 此程式庫的 APIs提供下列主要函數： + 註冊通知或輪詢可用的新更新請求。 + 接收、剖析和驗證更新請求。 + 根據更新請求中的資訊下載和驗證檔案。 + 在啟用收到的更新之前執行自我測試，以確保更新的功能有效性。 + 更新裝置的狀態。 此程式庫使用 AWS 服務來管理各種雲端相關功能，例如傳送韌體更新、監控多個區域的大量裝置、降低故障部署的爆量半徑，以及驗證更新的安全性。此程式庫可與任何 MQTT 或 HTTP 程式庫搭配使用。 此程式庫的示範示範如何使用 FreeRTOS 裝置上的 coreMQTT 程式庫和服務 AWS 進行完整的over-the-air更新。 ## 功能 以下是完整的 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 作業系統狀態的狀態碼轉換為字串。 ## API 參考 如需詳細資訊，請參閱[AWS IoT Over-the-air更新：函數](https://aws.github.io/ota-for-aws-iot-embedded-sdk/v3.4.0/ota_functions.html)。 ## 範例使用方式 典型的具 OTA 功能裝置應用程式會使用以下一系列 API 呼叫，使用 MQTT 通訊協定驅動程式。 1. 連線至 AWS IoT coreMQTT Agent。如需詳細資訊，請參閱[coreMQTT Agent 程式庫](coremqtt-agent.md)。 1. 透過呼叫 初始化 OTA 代理程式`OTA_Init`，包括緩衝區、所需的 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)。 ## 記憶體使用 **** | OTA AWS IoT 的程式碼大小 （使用 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 |