从 OTA PAL 端口的版本 1 迁移到版本 3 - FreeRTOS
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

从 OTA PAL 端口的版本 1 迁移到版本 3

无线更新库对文件夹结构以及库和演示应用程序所需的配置位置进行了一些更改。对于旨在与 v1.2.0 配合使用的 OTA 应用程序迁移到库的 v3.0.0,您必须更新 PAL 端口函数签名并包含本迁移指南中所述的其他配置文件。

对 OTA PAL 的更改

  • OTA PAL 端口目录名称已从otaota_pal_for_aws. 此文件夹必须包含 2 个文件:ota_pal.cota_pal.h. PAL 头文件libraries/freertos_plus/aws/ota/src/aws_iot_ota_pal.h已从 OTA 库中删除,必须在端口内定义。

  • 退货代码 (OTA_Err_t) 被翻译成枚举OTAMainStatus_t. 请参阅ota_platform _Interface.h用于翻译后的退货代码。辅助器宏还提供了组合OtaPalMainStatusOtaPalSubStatus编码和提取OtaMainStatusOtaPalStatus和类似的。

  • 登录 PAL

    • 已删除DEFINE_OTA_METHOD_NAME宏。

    • 早期:OTA_LOG_L1( "[%s] Receive file created.\r\n", OTA_METHOD_NAME );.

    • Updated: LogInfo(( "Receive file created.")); 使用LogDebugLogWarnLogError以获取适当的日志。

  • 变量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.hota_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已重命名为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 )

New File: 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_BUILDAPP_VERSION_MINORAPP_VERSION_MAJOR已添加到ota_demo_config.h. 例如,包含版本信息的旧文件已被删除tests/include/aws_application_version.hlibraries/c_sdk/standard/common/include/iot_appversion32.hdemos/demo_runner/aws_demo_version.c.

OTA PAL 测试的更改

  • 删除了 “full_Ota_Agent” 测试组以及所有相关文件。此测试组之前是资格认证所必需的。这些测试是针对 OTA 库的,而不是专门针对 OTA PAL 端口。OTA 库现在拥有托管在 OTA 存储库中的完整测试覆盖范围,因此不再需要此测试组。

  • 删除了 “full_Ota_CBOR” 和 “隔离 _Ota_CBOR” 测试组以及所有相关文件。这些测试不是资格考试的一部分。这些测试涵盖的功能现在正在 OTA 存储库中进行测试。

  • 已将测试文件从库目录移动到tests/integration_tests/ota_pal目录。

  • 更新了 OTA PAL 资格测试,以使用 OTA 库 API 的 v3.0.0。

  • 更新了 OTA PAL 测试如何访问代码签名证书进行测试。以前有一个用于代码签名凭据的专用头文件。新版本的图书馆已不再是这种情况。测试代码希望此变量在ota_pal.c. 该值将分配给在平台特定 OTA 配置文件中定义的宏。

清单

使用此清单确保您遵循迁移所需的步骤:

  • 更新 ota pal 端口文件夹的名称otaota_pal_for_aws.

  • 添加文件ota_pal.h具有上面提到的功能。例如ota_pal.h文件,请参阅GitHub.

  • 添加配置文件:

    • 将文件名更改为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.haws_test_ota_config.h.

    • 添加ota_demo_config.h文件。

    • 添加aws_test_ota_config.h文件。

  • ota_pal.c 进行以下更改:

    • 使用最新的 OTA 库文件名更新包含内容。

    • 删除DEFINE_OTA_METHOD_NAME宏。

    • 更新 OTA PAL 函数的签名。

    • 从中更新文件上下文变量的名称CpFileContext.

    • 更新OTA_FileContext_tstruct 和所有相关变量。

    • 更新cOTA_JSON_FileSignatureKeyOTA_JsonFileSignatureKey.

    • 更新OTA_PAL_ImageState_tOta_ImageState_t类型。

    • 更新错误类型和值。

    • 更新打印宏以使用日志记录堆栈。

    • 更新signingcredentialSIGNING_CERTIFICATE_PEM要成为otapalconfigCODE_SIGNING_CERTIFICATE.

    • 更新otaPal_CheckFileSignatureotaPal_ReadAndAssumeCertificate函数注释。

  • 更新CMakeLists.txt文件。

  • 更新 IDE 项目。