本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從版本 1 遷移至版本 3 以進行 OTA PAL 連接埠 Over-the-air更新程式庫在資料夾結構中引入了一些變更，以及程式庫和示範應用程式所需的組態置放。對於旨在使用 v1.2.0 遷移至程式庫 v3.0.0 的 OTA 應用程式，您必須更新 PAL 連接埠函數簽章，並包含本遷移指南中所述的其他組態檔案。 ## OTA PAL 的變更 + OTA PAL 連接埠目錄名稱已從更新`ota`為 `ota_pal_for_aws`。此資料夾必須包含 2 個檔案： `ota_pal.c`和 `ota_pal.h`。PAL 標頭檔案`libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h`已從 OTA 程式庫中刪除，且必須在連接埠內定義。 + 傳回碼 (`OTA_Err_t`) 會轉譯為列舉 `OTAMainStatus_t`。請參閱 [ ota\$1platform\$1interface.h](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/v3.0.0/source/include/ota_platform_interface.h#L68-L90) 以取得翻譯的傳回碼。 [也提供協助程式巨集](https://github.com/aws/ota-for-aws-iot-embedded-sdk/blob/666241d0f643b07d5146a3715b649d80f8135e0b/source/include/ota_platform_interface.h#L105-L111)來結合 `OtaPalMainStatus` 和 `OtaPalSubStatus`程式碼，以及`OtaMainStatus`從 `OtaPalStatus` 和類似擷取。 + 登入 PAL + 已移除`DEFINE_OTA_METHOD_NAME`巨集。 + 先前版本：`OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );`。 + 已更新：`LogInfo(( "Receive file created."));`使用 `LogDebug`和 `LogWarn``LogError`來取得適當的日誌。 + 變數`cOTA_JSON_FileSignatureKey`已變更為 `OTA_JsonFileSignatureKey`。 ### 函數函數簽章是在中定義`ota_pal.h`，並以字首開頭，`otaPal`而不是 `prvPAL`。 **注意** PAL 的確切名稱在技術上是開放式的，但為了與資格測試相容，該名稱應符合以下指定的名稱。 **** | 第 1 版 | 第 3 版 | 備註 | | --- | --- | --- | | `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` | 為資料區塊在傳入時建立新的接收檔案。 | | `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );` | `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );` | 在指定的位移下，將資料區塊寫入指定的檔案。 | | `OTA_Err_t prvPAL_ActivateNewImage( void );` | `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` | 啟用透過 OTA 接收的最新 MCU 映像。 | | `OTA_Err_t prvPAL_ResetDevice( void );` | `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` | 重設裝置。 | | `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` | 在指定的 OTA 內容中驗證和關閉基礎接收檔案。 | | `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` | `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` | 停止 OTA 傳輸。 | | `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` | `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` | 嘗試設定 OTA 更新映像的狀態。 | | `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` | `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` | 取得 OTA 更新映像的狀態。 | + 第 1 版： `OTA_Err_t prvPAL_CreateFileForRx( OTA_FileContext_t * const *C* );` 第 3 版： `OtaPalStatus_t otaPal_CreateFileForRx( OtaFileContext_t * const *pFileContext* );` 注意：在資料區塊進入時，為它們建立新的接收檔案。 + 第 1 版： `int16_t prvPAL_WriteBlock( OTA_FileContext_t * const C, uint32_t ulOffset, uint8_t * const pcData, uint32_t ulBlockSize );` 第 3 版： `int16_t otaPal_WriteBlock( OtaFileContext_t * const pFileContext, uint32_t ulOffset, uint8_t * const pData, uint32_t ulBlockSize );` 注意：在指定的位移下，將資料區塊寫入指定的檔案。 + 第 1 版： `OTA_Err_t prvPAL_ActivateNewImage( void );` 第 3 版： `OtaPalStatus_t otaPal_ActivateNewImage( OtaFileContext_t * const *pFileContext* );` 注意：啟用透過 OTA 接收的最新 MCU 映像。 + 第 1 版： `OTA_Err_t prvPAL_ResetDevice( void );` 第 3 版： `OtaPalStatus_t otaPal_ResetDevice( OtaFileContext_t * const *pFileContext* );` 注意：重設裝置。 + 第 1 版： `OTA_Err_t prvPAL_CloseFile( OTA_FileContext_t * const *C* );` 第 3 版： `OtaPalStatus_t otaPal_CloseFile( OtaFileContext_t * const *pFileContext* );` 注意：在指定的 OTA 內容中驗證和關閉基礎接收檔案。 + 第 1 版： `OTA_Err_t prvPAL_Abort( OTA_FileContext_t * const *C* );` 第 3 版： `OtaPalStatus_t otaPal_Abort( OtaFileContext_t * const *pFileContext* );` 注意：停止 OTA 傳輸。 + 第 1 版： `OTA_Err_t prvPAL_SetPlatformImageState( OTA_ImageState_t *eState* );` 第 3 版： `OtaPalStatus_t otaPal_SetPlatformImageState( OtaFileContext_t * const pFileContext, OtaImageState_t eState );` 注意：嘗試設定 OTA 更新映像的狀態。 + 第 1 版： `OTA_PAL_ImageState_t prvPAL_GetPlatformImageState( void );` 第 3 版： `OtaPalImageState_t otaPal_GetPlatformImageState( OtaFileContext_t * const *pFileContext* );` 注意：取得 OTA 更新映像的狀態。 ### 資料類型 **** | 第 1 版 | 檔案 | 第 3 版 | 檔案 | 備註 | | --- | --- | --- | --- | --- | | `OTA_PAL_ImageState_t` | `aws_iot_ota_agent.h` | `OtaPalImageState_t` | `ota_private.h` | *平台實作所設定的映像狀態。* | | `OTA_Err_t` | `aws_iot_ota_agent.h` | `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)` | `ota.h`, `ota_platform_interface.h` | v1：這些是定義 32 個未簽署整數的巨集。 v3：代表錯誤類型並與錯誤代碼相關聯的專用列舉。 | | `OTA_FileContext_t` | `aws_iot_ota_agent.h` | `OtaFileContext_t` | `ota_private.h` | v1：包含資料的列舉和緩衝區。 v3：包含其他資料長度變數。 | | `OTA_ImageState_t` | `aws_iot_ota_agent.h` | `OtaImageState_t` | `ota_private.h` | *OTA 映像狀態* | + 第 1 版： `OTA_PAL_ImageState_t` 檔案： `aws_iot_ota_agent.h` 第 3 版： `OtaPalImageState_t` 檔案： `ota_private.h` 注意：*平台實作所設定的影像狀態。* + 第 1 版： `OTA_Err_t` 檔案： `aws_iot_ota_agent.h` 第 3 版： `OtaErr_t OtaPalStatus_t (combination of OtaPalMainStatus_t and OtaPalSubStatus_t)` 檔案：`ota.h`、 `ota_platform_interface.h` 注意：v1：這些是定義 32 個未簽署整數的巨集。v3：專用列舉，代表錯誤類型並與錯誤碼相關聯。 + 第 1 版： `OTA_FileContext_t` 檔案： `aws_iot_ota_agent.h` 第 3 版： `OtaFileContext_t` 檔案： `ota_private.h` 注意：v1：包含資料的列舉和緩衝區。v3：包含額外的資料長度變數。 + 第 1 版： `OTA_ImageState_t` 檔案： `aws_iot_ota_agent.h` 第 3 版： `OtaImageState_t` 檔案： `ota_private.h` 注意：*OTA 映像狀態* ### 組態變更檔案`aws_ota_agent_config.h`已重新命名為 [https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_config.h)，而會將包含的防護從 `_AWS_OTA_AGENT_CONFIG_H_`變更為 `OTA_CONFIG_H_`。 + 檔案`aws_ota_codesigner_certificate.h`已刪除。 + 包含要列印偵錯訊息的新記錄堆疊： ``` /**************************************************/ /******* DO NOT CHANGE the following order ********/ /**************************************************/ /* Logging related header files are required to be included in the following order: * 1. Include the header file "logging_levels.h". * 2. Define LIBRARY_LOG_NAME and LIBRARY_LOG_LEVEL. * 3. Include the header file "logging_stack.h". */ /* Include header that defines log levels. */ #include "logging_levels.h" /* Configure name and log level for the OTA library. */ #ifndef LIBRARY_LOG_NAME #define LIBRARY_LOG_NAME "OTA" #endif #ifndef LIBRARY_LOG_LEVEL #define LIBRARY_LOG_LEVEL LOG_INFO #endif #include "logging_stack.h" /************ End of logging configuration ****************/ ``` + 新增常數組態： ``` /** * @brief Size of the file data block message (excluding the header). */ #define otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE ) ``` **新檔案：**[https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_demo_config.h](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/aws_demos/config_files/ota_demo_config.h)包含 OTA 示範所需的組態，例如程式碼簽署憑證和應用程式版本。 + `signingcredentialSIGNING_CERTIFICATE_PEM` 在中定義的 `demos/include/aws_ota_codesigner_certificate.h` 已移至 `ota_demo_config.h` ，`otapalconfigCODE_SIGNING_CERTIFICATE`並且可以從 PAL 檔案存取為： ``` static const char codeSigningCertificatePEM[] = otapalconfigCODE_SIGNING_CERTIFICATE; ``` 檔案`aws_ota_codesigner_certificate.h`已刪除。 + 巨集 `APP_VERSION_BUILD`、 `APP_VERSION_MINOR``APP_VERSION_MAJOR`已新增至 `ota_demo_config.h`。包含版本資訊的舊檔案已移除，例如 `tests/include/aws_application_version.h`、`libraries/c_sdk/standard/common/include/iot_appversion32.h`、`demos/demo_runner/aws_demo_version.c`。 ## OTA PAL 測試的變更 + 已移除「Full\$1OTA\$1AGENT」測試群組以及所有相關檔案。此測試群組先前為資格所需。這些測試適用於 OTA 程式庫，而非特定於 OTA PAL 連接埠。OTA 程式庫現在具有 OTA 儲存庫中託管的完整測試涵蓋範圍，因此不再需要此測試群組。 + 已移除「Full\$1OTA\$1CBOR」和「Quarantine\$1OTA\$1CBOR」測試群組，以及所有相關檔案。這些測試不屬於資格測試的一部分。這些測試涵蓋的功能現在正在 OTA 儲存庫中進行測試。 + 將測試檔案從程式庫目錄移至`tests/integration_tests/ota_pal`目錄。 + 更新 OTA PAL 資格測試，以使用 OTA 程式庫 API 的 v3.0.0。 + 更新 OTA PAL 測試如何存取程式碼簽署憑證以進行測試。先前有程式碼簽署登入資料的專用標頭檔案。新版本的程式庫不再如此。測試程式碼預期此變數會在中定義`ota_pal.c`。此值會指派給平台特定 OTA 組態檔案中定義的巨集。 ## 檢查清單使用此檢查清單來確保您遵循遷移所需的步驟： + 將 ota pal 連接埠資料夾的名稱從更新`ota`為 `ota_pal_for_aws`。 + `ota_pal.h` 使用上述函數新增檔案。如需範例`ota_pal.h`檔案，請參閱 [ GitHub](https://github.com/aws/amazon-freertos/blob/main/vendors/pc/boards/windows/ports/ota_pal_for_aws/ota_pal.h)。 + 新增組態檔案： + 將檔案名稱從 `aws_ota_agent_config.h`變更為（或建立） `ota_config.h`。 + 新增： ``` otaconfigFILE_BLOCK_SIZE ( 1UL << otaconfigLOG2_FILE_BLOCK_SIZE ) ``` + 包括： ``` #include "ota_demo_config.h" ``` + 將上述檔案複製到 `aws_test config` 資料夾，並以 `ota_demo_config.h` 取代的任何。 `aws_test_ota_config.h` + 新增 `ota_demo_config.h` 檔案。 + 新增 `aws_test_ota_config.h` 檔案。 + 對 `ota_pal.c` 進行下列變更： + 使用最新的 OTA 程式庫檔案名稱更新包含。 + 移除 `DEFINE_OTA_METHOD_NAME` 巨集。 + 更新 OTA PAL 函數的簽章。 + 將檔案內容變數的名稱從更新`C`為 `pFileContext`。 + 更新`OTA_FileContext_t`結構和所有相關變數。 + 更新`cOTA_JSON_FileSignatureKey`至 `OTA_JsonFileSignatureKey`。 + 更新 `OTA_PAL_ImageState_t`和 `Ota_ImageState_t`類型。 + 更新錯誤類型和值。 + 更新列印巨集以使用記錄堆疊。 + 將更新`signingcredentialSIGNING_CERTIFICATE_PEM`為 `otapalconfigCODE_SIGNING_CERTIFICATE`。 + 更新 `otaPal_CheckFileSignature` 和 `otaPal_ReadAndAssumeCertificate` 函數註解。 + 更新 [https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a](https://github.com/aws/amazon-freertos/pull/3208/commits/432e13fcb8dfbfeb6de25110a3d2ea14ccaf1b9a) 檔案。 + 更新 IDE 專案。