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

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

从 OTA Pal 端口迁移到版本 3

无线更新库对文件夹结构以及库和演示应用程序所需配置的位置进行了一些更改。对于旨在使用 v1.2.0 迁移到库的 v3.0.0 的 OTA 应用程序,您必须更新 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_ 平台 _ 接口 .h获取已翻译的返回代码。辅助标记宏也可以将OtaPalMainStatusOtaPalSubStatus代码和抽取OtaMainStatusfromOtaPalStatus和相似的。

  • 登录 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.

Functions

函数签名在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 测试的更改

  • 已删除 “完整 OTA_Agent” 测试组以及所有相关文件。此测试组之前是资格认证所必需的。这些测试适用于 OTA 库,而不是特定于 OTA PAL 端口。OTA 库现在具有托管在 OTA 存储库中的完整测试覆盖范围,因此不再需要此测试组。

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

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

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

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

Checklist

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

  • 更新 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.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 函数的签名。

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

    • 更新OTA_FileContext_t结构和所有相关变量。

    • 更新cOTA_JSON_FileSignatureKeyOTA_JsonFileSignatureKey.

    • 更新OTA_PAL_ImageState_tOta_ImageState_t类型。

    • 更新错误类型和值。

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

    • 更新signingcredentialSIGNING_CERTIFICATE_PEM要成为otapalconfigCODE_SIGNING_CERTIFICATE.

    • 更新otaPal_CheckFileSignatureotaPal_ReadAndAssumeCertificate函数注释。

  • 更新 CMakeLists.txt文件。

  • 更新 IDE 项目。