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

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

将 OTA 应用程序从版本 1 迁移到版本 3

本指南将帮助您将应用程序从 OTA 库版本 1 迁移到版本 3。

注意

OTA 版本 2 API 与 OTA v3 API 相同,因此,如果您的应用程序使用的是版本 2 的 API,那么 API 调用不需要进行更改,但我们建议您集成该库的版本 3。

OTA 版本 3 的演示可在这里获得:

API 更改摘要

OTA 库版本 1 和版本 3 之间的 API 更改摘要

版本 1 的 API

版本 3 的 API

更改描述

Ota_AGENTINIT

Ota_init

由于 OTA v3 中的实现发生了变化,输入参数以及函数返回的值也会更改。有关详细信息,请参阅下面的 Ota_Init 部分。

Ota_AGENT 关闭

Ota_shutdown

更改输入参数,包括可选取消订阅 MQTT 主题的附加参数。有关详细信息,请参阅下面的 Ota_shutdown 部分。

Ota_getAgentState

Ota_getState

API 名称在没有更改输入参数的情况下更改。返回值是相同的,但是枚举和成员被重命名。有关详细信息,请参阅下面的 Ota_getState 部分。

不适用

Ota_getStatus

添加了新的 API,它取代了接收的 API Ota_getPackets、Ota_getPackets 已处理、Ota_getPackets 已处理、Ota_getPackets 丢弃。有关详细信息,请参阅下面的 Ota_getStatus 部分。

Ota_getPackets 已收到

不适用

此 API 已从版本 3 中删除,并由 Ota_getStatistics 取代。

Ota_getPackets 队列

不适用

此 API 已从版本 3 中删除,并由 Ota_getStatistics 取代。

Ota_getPackets 已处理

不适用

此 API 已从版本 3 中删除,并由 Ota_getStatistics 取代。

Ota_getPackets 丢弃

不适用

此 API 已从版本 3 中删除,并由 Ota_getStatistics 取代。

Ota_ActivateNew Image

Ota_ActivateNew Image

输入参数相同,但返回的 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。有关详细信息,请参阅 Ota_activateNewImage 部分。

Ota_setImagate

Ota_setImagate

输入参数相同并重命名,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。有关详细信息,请参阅 Ota_setImagState 部分。

Ota_getImagestate

Ota_getImagestate

输入参数相同,返回枚举在 OTA 库的版本 3 中重命名。有关详细信息,请参阅 Ota_getImagState 部分。

Ota_ 暂停

Ota_ 暂停

输入参数相同,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。有关详细信息,请参阅 Ota_Spend 部分。

Ota_ 简历

Ota_ 简历

随着在 OTA 演示/应用程序中处理连接,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码,连接的输入参数将被删除。有关详细信息,请参阅 Ota_Resume 部分。

Ota_CheckFore 更新

Ota_CheckFore 更新

输入参数相同,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。有关详细信息,请参阅 Ota_checkforUpdate 部分。

不适用

Ota_事件处理任务

添加了新的 API,它是处理 OTA 更新事件的主要事件循环,必须由应用程序任务调用。有关详细信息,请参阅 Ota_eventProcessingTask 部分。

不适用

Ota_signalEvent

添加了新的 API,它将事件添加到 OTA 事件队列的后面,内部 OTA 模块用于向代理任务发出信号。有关详细信息,请参阅 Ota_signalEvent 部分。

不适用

Ota_ERR_STRERRRR

用于 OTA 错误的错误代码到字符串转换的新 API。

不适用

Ota_jobparse_Strerror

用于 Job 业解析错误的错误代码到字符串转换的新 API。

不适用

Ota_osStatus _trerror

用于 OTA OS 端口状态的状态代码到字符串转换的新 API。

不适用

Ota_palStatus _trerror

用于 OTA PAL 端口状态的状态代码到字符串转换的新 API。

所需更改的说明

Ota_init

在 v1 中初始化 OTA 代理时OTA_AgentInit使用 API,它将连接上下文、事物名称、完整回调和超时的参数作为输入。

OTA_State_t OTA_AgentInit( void * pvConnectionContext, const uint8_t * pucThingName, pxOTACompleteCallback_t xFunc, TickType_t xTicksToWait );

此 API 现在已更改为OTA_Init包含 ota、ota 接口、事物名称和应用程序回调所需缓冲区的参数。

OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer, OtaInterfaces_t * pOtaInterfaces, const uint8_t * pThingName, OtaAppCallback OtaAppCallback );
移除输入参数-
PVConnection 上下文-

删除连接上下文是因为 OTA 库版本 3 不要求将连接上下文传递给它,并且 MQT/HTTP 操作由 OTA 演示/应用程序中各自的接口处理。

XTickToWay-

随着任务是在调用 OTA_Init 之前在 OTA 演示/应用程序中创建的,因此也会删除待等待的报价参数。

重命名输入参数-
xFunc-

该参数重命名为 OtaAppCallCallCall_T,其类型更改为 OtaappCallback_T。

新输入参数-
pota缓冲区

应用程序必须分配缓冲区,然后在初始化期间使用 Otaappbuffer_T 结构将其传递给 OTA 库。根据用于下载文件的协议,所需的缓冲区略有不同。对于 MQTT 协议,需要用于流名称的缓冲区,对于 HTTP 协议,需要预签名 URL 和授权方案的缓冲区。

使用 MQTT 进行文件下载时所需的缓冲区-

static OtaAppBuffer_t otaBuffer = { .pUpdateFilePath = updateFilePath, .updateFilePathsize = otaexampleMAX_FILE_PATH_SIZE, .pCertFilePath = certFilePath, .certFilePathSize = otaexampleMAX_FILE_PATH_SIZE, .pStreamName = streamName, .streamNameSize = otaexampleMAX_STREAM_NAME_SIZE, .pDecodeMemory = decodeMem, .decodeMemorySize = ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ), .pFileBitmap = bitmap, .fileBitmapSize = OTA_MAX_BLOCK_BITMAP_SIZE };

使用 HTTP 进行文件下载时所需的缓冲区-

static OtaAppBuffer_t otaBuffer = { .pUpdateFilePath = updateFilePath, .updateFilePathsize = otaexampleMAX_FILE_PATH_SIZE, .pCertFilePath = certFilePath, .certFilePathSize = otaexampleMAX_FILE_PATH_SIZE, .pDecodeMemory = decodeMem, .decodeMemorySize = ( 1U << otaconfigLOG2_FILE_BLOCK_SIZE ), .pFileBitmap = bitmap, .fileBitmapSize = OTA_MAX_BLOCK_BITMAP_SIZE, .pUrl = updateUrl, .urlSize = OTA_MAX_URL_SIZE, .pAuthScheme = authScheme, .authSchemeSize = OTA_MAX_AUTH_SCHEME_SIZE };

哪里-

pUpdateFilePath Path to store the files. updateFilePathsize Maximum size of the file path. pCertFilePath Path to certificate file. certFilePathSize Maximum size of the certificate file path. pStreamName Name of stream to download the files. streamNameSize Maximum size of the stream name. pDecodeMemory Place to store the decoded files. decodeMemorySize Maximum size of the decoded files buffer. pFileBitmap Bitmap of the parameters received. fileBitmapSize Maximum size of the bitmap. pUrl Presigned url to download files from S3. urlSize Maximum size of the URL. pAuthScheme Authentication scheme used to validate download. authSchemeSize Maximum size of the auth scheme.
pota接口

Ota_init 的第二个输入参数是对 OtaInterfaces_T 类型的 OTA 接口的引用。这组接口必须传递给 OTA 库,并在操作系统界面中包括 MQTT 接口、HTTP 接口和平台抽象层接口。

OTA OS 界面

OTA OS 功能接口是设备使用 OTA 库必须实施的一组 API。此接口的函数实现将提供给用户应用程序中的 OTA 库。OTA 库调用函数实现来执行通常由操作系统提供的功能。这包括管理事件、计时器和内存分配。FreeRTOS 和 POSIX 的实现与 OTA 库一起提供。

例如 FreeRTOS 使用提供的 FreeRTOS 端口-

OtaInterfaces_t otaInterfaces; otaInterfaces.os.event.init = OtaInitEvent_FreeRTOS; otaInterfaces.os.event.send = OtaSendEvent_FreeRTOS; otaInterfaces.os.event.recv = OtaReceiveEvent_FreeRTOS; otaInterfaces.os.event.deinit = OtaDeinitEvent_FreeRTOS; otaInterfaces.os.timer.start = OtaStartTimer_FreeRTOS; otaInterfaces.os.timer.stop = OtaStopTimer_FreeRTOS; otaInterfaces.os.timer.delete = OtaDeleteTimer_FreeRTOS; otaInterfaces.os.mem.malloc = Malloc_FreeRTOS; otaInterfaces.os.mem.free = Free_FreeRTOS;

使用提供的 POSIX 端口的 Linux 示例-

OtaInterfaces_t otaInterfaces; otaInterfaces.os.event.init = Posix_OtaInitEvent; otaInterfaces.os.event.send = Posix_OtaSendEvent; otaInterfaces.os.event.recv = Posix_OtaReceiveEvent; otaInterfaces.os.event.deinit = Posix_OtaDeinitEvent; otaInterfaces.os.timer.start = Posix_OtaStartTimer; otaInterfaces.os.timer.stop = Posix_OtaStopTimer; otaInterfaces.os.timer.delete = Posix_OtaDeleteTimer; otaInterfaces.os.mem.malloc = STDC_Malloc; otaInterfaces.os.mem.free = STDC_Free;
MQTT 接口

OTA MQTT 接口是一组 API,必须在库中实现,才能使 OTA 库从流媒体服务下载文件块。

示例使用来自MQTT 演示 OTA-

OtaInterfaces_t otaInterfaces; otaInterfaces.mqtt.subscribe = prvMqttSubscribe; otaInterfaces.mqtt.publish = prvMqttPublish; otaInterfaces.mqtt.unsubscribe = prvMqttUnSubscribe;
HTTP 接口

OTA HTTP 接口是一组 API,必须在库中实现,才能使 OTA 库通过连接到预签名 URL 并获取数据块来下载文件块。除非您将 OTA 库配置为从预签名 URL 而不是流媒体服务下载,否则它是可选的。

示例使用来自通过 HTTP 演示的 OTA-

OtaInterfaces_t otaInterfaces; otaInterfaces.http.init = httpInit; otaInterfaces.http.request = httpRequest; otaInterfaces.http.deinit = httpDeinit;
OTA PAL 界面

OTA PAL 接口是设备使用 OTA 库必须实施的一组 API。OTA PAL 的设备特定实现将提供给用户应用程序中的库。库使用这些函数来存储、管理和验证下载内容。

OtaInterfaces_t otaInterfaces; otaInterfaces.pal.getPlatformImageState = otaPal_GetPlatformImageState; otaInterfaces.pal.setPlatformImageState = otaPal_SetPlatformImageState; otaInterfaces.pal.writeBlock = otaPal_WriteBlock; otaInterfaces.pal.activate = otaPal_ActivateNewImage; otaInterfaces.pal.closeFile = otaPal_CloseFile; otaInterfaces.pal.reset = otaPal_ResetDevice; otaInterfaces.pal.abort = otaPal_Abort; otaInterfaces.pal.createFile = otaPal_CreateFileForRx;
回报的变化-

返回从 OTA 座席状态更改为 OTA 错误代码。请参阅Amazon IoT无线更新 v3.0.0:Otaerr_T.

Ota_shutdown

在 OTA 库版本 1 中,用于关闭 OTA 代理的 API 是 Ota_Agent 关闭,随着输入参数的更改,现在已更改为 Ota_shutdown。

OTA 代理关闭(版本 1)
OTA_State_t OTA_AgentShutdown( TickType_t xTicksToWait );
OTA 代理关闭(版本 3)
OtaState_t OTA_Shutdown( uint32_t ticksToWait, uint8_t unsubscribeFlag );
Tickto WaTick-

等待 OTA 代理完成关闭过程的报价数。如果设置为零,函数将立即返回而不等待。实际状态将返回给调用者。代理程序在这段时间没睡觉,但用于忙碌循环。

新的输入参数-

取消订阅标志-

用于指示调用关闭时是否应从作业主题中执行取消订阅操作的标记。如果标志为 0,则不会为工作主题调用取消订阅操作。如果必须取消订阅作业主题的应用程序,那么在调用 Ota_shutdown 时必须将此标志设置为 1。

回报的变化-

Otastate _T-

OTA Agent 状态及其成员的枚举已重命名。请参阅Amazon IoT无线更新 v3.0.0.

Ota_getState

API 名称从 Ota_AGENTGETState 更改为 Ota_getState。

OTA 代理关闭(版本 1)
OTA_State_t OTA_GetAgentState( void );
OTA 代理关闭(版本 3)
OtaState_t OTA_GetState( void );
回报的变化-

Otastate _T-

OTA Agent 状态及其成员的枚举已重命名。请参阅Amazon IoT无线更新 v3.0.0.

Ota_getStatus

为统计信息添加了新的单个 API。它取代了接收的 API Ota_getPackets、Ota_getPackets 已处理、Ota_getPackets 已处理、Ota_getPackets 丢弃。此外,在 OTA 库版本 3 中,统计数字仅与当前作业有关。

版本 1 OTA 库
uint32_t OTA_GetPacketsReceived( void ); uint32_t OTA_GetPacketsQueued( void ); uint32_t OTA_GetPacketsProcessed( void ); uint32_t OTA_GetPacketsDropped( void );
版本 3 OTA 库
OtaErr_t OTA_GetStatistics( OtaAgentStatistics_t * pStatistics );
pStatus-

输入/输出参数,用于为当前作业接收、丢弃、排队和处理的数据包等统计数据。

输出参数-

OTA 错误代码。

示例用法-
OtaAgentStatistics_t otaStatistics = { 0 }; OTA_GetStatistics( &otaStatistics ); LogInfo( ( " Received: %u Queued: %u Processed: %u Dropped: %u", otaStatistics.otaPacketsReceived, otaStatistics.otaPacketsQueued, otaStatistics.otaPacketsProcessed, otaStatistics.otaPacketsDropped ) );

Ota_ActivateNew Image

输入参数相同,但返回的 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。

版本 1 OTA 库
OTA_Err_t OTA_ActivateNewImage( void );
版本 3 OTA 库
OtaErr_t OTA_ActivateNewImage( void );

返回的 OTA 错误代码枚举已更改,并添加了新的错误代码。请参阅Amazon IoT无线更新 v3.0.0:Otaerr_T.

示例用法-
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_ActivateNewImage(); /* Handle error */

Ota_setImagate

输入参数相同并重命名,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。

版本 1 OTA 库
OTA_Err_t OTA_SetImageState( OTA_ImageState_t eState );
版本 3 OTA 库
OtaErr_t OTA_SetImageState( OtaImageState_t state );

输入参数重命名为 Otaimagestate_T。请参阅Amazon IoT无线更新 v3.0.0.

返回的 OTA 错误代码枚举已更改,并添加了新的错误代码。请参阅Amazon IoT移植空中更新 v3.0.0/OtaERR_T.

示例用法-
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_SetImageState( OtaImageStateAccepted ); /* Handle error */

Ota_getImagestate

输入参数相同,返回枚举在 OTA 库的版本 3 中重命名。

版本 1 OTA 库
OTA_ImageState_t OTA_GetImageState( void );
版本 3 OTA 库
OtaImageState_t OTA_GetImageState( void );

返回枚举重命名为 Otaimagestate_T。请参阅Amazon IoT无线更新 v3.0.0:Otaimagestate_T.

示例用法-
OtaImageState_t imageState; imageState = OTA_GetImageState();

Ota_ 暂停

输入参数相同,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。

版本 1 OTA 库
OTA_Err_t OTA_Suspend( void );
版本 3 OTA 库
OtaErr_t OTA_Suspend( void );

返回的 OTA 错误代码枚举已更改,并添加了新的错误代码。请参阅Amazon IoT无线更新 v3.0.0:Otaerr_T.

示例用法-
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Suspend(); /* Handle error */

Ota_ 简历

随着在 OTA 演示/应用程序中处理连接,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码,连接的输入参数将被删除。

版本 1 OTA 库
OTA_Err_t OTA_Resume( void * pxConnection );
版本 3 OTA 库
OtaErr_t OTA_Resume( void );

返回的 OTA 错误代码枚举已更改,并添加了新的错误代码。请参阅Amazon IoT无线更新 v3.0.0:Otaerr_T.

示例用法-
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Resume(); /* Handle error */

Ota_CheckFore 更新

输入参数相同,返回 OTA 错误代码被重命名,并在 OTA 库的版本 3 中添加了新的错误代码。

版本 1 OTA 库
OTA_Err_t OTA_CheckForUpdate( void );
版本 3 OTA 库
OtaErr_t OTA_CheckForUpdate( void )

返回的 OTA 错误代码枚举已更改,并添加了新的错误代码。请参阅Amazon IoT无线更新 v3.0.0:Otaerr_T.

Ota_事件处理任务

这是一个新的 API,是处理 OTA 更新事件的主要事件循环。它必须由应用程序任务调用。此循环将继续处理和执行为 OTA Update 收到的事件,直到应用程序终止此任务。

版本 3 OTA 库
void OTA_EventProcessingTask( void * pUnused );
示例 FreeRTOS-
/* Create FreeRTOS task*/ xTaskCreate( prvOTAAgentTask, "OTA Agent Task", otaexampleAGENT_TASK_STACK_SIZE, NULL, otaexampleAGENT_TASK_PRIORITY, NULL ); /* Call OTA_EventProcessingTask from the task */ static void prvOTAAgentTask( void * pParam ) { /* Calling OTA agent task. */ OTA_EventProcessingTask( pParam ); LogInfo( ( "OTA Agent stopped." ) ); /* Delete the task as it is no longer required. */ vTaskDelete( NULL ); }
POSIX 的例子-
/* Create posix thread.*/ if( pthread_create( &threadHandle, NULL, otaThread, NULL ) != 0 ) { LogError( ( "Failed to create OTA thread: " ",errno=%s", strerror( errno ) ) ); /* Handle error. */ } /* Call OTA_EventProcessingTask from the thread.*/ static void * otaThread( void * pParam ) { /* Calling OTA agent task. */ OTA_EventProcessingTask( pParam ); LogInfo( ( "OTA Agent stopped." ) ); return NULL; }

Ota_signalEvent

这是一个新的 API,它将事件添加到事件队列的后面,内部 OTA 模块也用于向代理任务发出信号。

版本 3 OTA 库
bool OTA_SignalEvent( const OtaEventMsg_t * const pEventMsg );
示例用法-
OtaEventMsg_t xEventMsg = { 0 }; xEventMsg.eventId = OtaAgentEventStart; ( void ) OTA_SignalEvent( &xEventMsg );

将 OTA 库作为子模块集成到应用程序中

如果你想在自己的应用程序中集成 OTA 库,你可以使用 git submodule 命令。Git 子模块允许你保留一个 Git 仓库作为另一个 Git 仓库的子目录。OTA 库版本 3 维护在ota for aws-iot 嵌入式 SDK存储库。

git submodule add https://github.com/aws/ota-for-aws-iot-embedded-sdk.git destination_folder
git commit -m "Added the OTA Library as submodule to the project."
git push

有关更多信息,请参阅 。将 OTA 代理集成到应用程序中中的FreeRTOS 用户指南.

参考