本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为 OTA PAL 移植从版本 1 迁移到版本 3 空中下载更新库对文件夹结构以及库和演示应用程序所需的配置位置进行了一些更改。对于设计用于与 v1.2.0 配合使用的 OTA 应用程序，要迁移到该库的 v3.0.0，您必须更新 PAL 移植功能签名并包含本迁移指南中所述的其他配置文件。 ## OTA PAL 的更改 + OTA PAL 移植目录名称已从 `ota` 更新为 `ota_pal_for_aws`。此文件夹必须包含 2 个文件：`ota_pal.c` 和 `ota_pal.h`。已从 OTA 库中删除 PAL 头文件 `libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h`，并且必须在移植内定义。 + 将返回代码 (`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` 代码，并从 `OtaPalStatus` 中提取 `OtaMainStatus` 以及类似的宏。 + 登录 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_` 的 include 保护。 + 文件 `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 演示所需的配置，例如，代码签名证书和应用程序版本。 + 在 `demos/include/aws_ota_codesigner_certificate.h` 中定义的 `signingcredentialSIGNING_CERTIFICATE_PEM` 已作为 `otapalconfigCODE_SIGNING_CERTIFICATE` 移至 `ota_demo_config.h` 中，并且可通过以下方式从 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： ``` #include "ota_demo_config.h" ``` + 将上述文件复制到 `aws_test config` 文件夹，并将 `ota_demo_config.h` 所有 Include 文件替换为 `aws_test_ota_config.h`。 + 添加 `ota_demo_config.h` 文件。 + 添加 `aws_test_ota_config.h` 文件。 + 对 `ota_pal.c` 进行以下更改： + 使用最新的 OTA 库文件名更新 Include 文件。 + 删除 `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 项目。