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

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

适用于 OTA 应用程序的迁移版本 3

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

注意

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

OTA 版本 3 的演示可以在这里找到:

API 更改摘要

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

OTA 版本 1 的 API

OTA 版本 3 的 API

更改的描述

OTA_ 代理

OTA_ 初始化

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

OTA_ 代理关闭

OTA 关闭

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

OTA_ 地址州

奥塔州

API 名称不会更改输入参数。返回值相同,但枚举和成员被重命名。有关详细信息,请参阅下面的 “OTA_GetState” 部分。

不适用

OTA_ 获取统计

新增 API,用于替换接收的接口 OTA_获取数据包、OTA_ 获取数据包已处理、OTA_ 获取数据包已丢弃的 API。有关详细信息,请参阅下面的 OTA_Get统计信息部分。

OTA_ 获取数据包已收到

不适用

此 API 已从版本 3 中删除,并由 OTA_get统计数据取代。

OTA_ 获取数据包压缩

不适用

此 API 已从版本 3 中删除,并由 OTA_get统计数据取代。

OTA_ 获取数据包已处理

不适用

此 API 已从版本 3 中删除,并由 OTA_get统计数据取代。

OTA_ 获取数据包已丢弃

不适用

此 API 已从版本 3 中删除,并由 OTA_get统计数据取代。

OTA_ 激活新图像

OTA_ 激活新图像

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

奥塔-塞蒂玛房地产

奥塔-塞蒂玛房地产

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

Ota_GETIMAGE 地产

Ota_GETIMAGE 地产

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

OTA_ 暂停

OTA_ 暂停

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

OTA_ 恢复

OTA_ 恢复

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

OTA_ 检查更新

OTA_ 检查更新

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

不适用

OTA_ 事件处理任务

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

不适用

OTA_ 信号事件

添加了新的 API,并将事件添加到 OTA 事件队列的背面,并由内部 OTA 模块用于向代理任务发出信号。请参阅 OTA_ 信号活动部分了解详细信息。

不适用

OTA_ 错误 _ 街头

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

不适用

OTA_ 工作分析 _ 街头

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

不适用

OTA_ 奥斯塔斯 _ 街头

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

不适用

OTA_ 手掌 _ 街头

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

所需更改的说明

OTA_ 初始化

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

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 );
移除输入参数-
PVN 连接上下文-

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

XTickTaT-

在调用 OTA_init 之前,在 OTA 演示/应用程序中创建任务时,也会删除等待刻度参数。

重命名输入参数-
XFUNC-

该参数被重命名为 OtaAppback 回调,其类型将更改为 OtaApp回调_t。

新输入参数-
扑克器

应用程序必须分配缓冲区,并在初始化过程中使用 OTAppBuffer_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 的第二个输入参数是对 OTA 接口 _T 类型的 OTA 接口的引用。这组接口必须传递给 OTA 库,并在操作系统接口中包含 MQTT 接口、HTTP 接口和平台抽象层接口。

OTA 操作系统接口

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

使用提供的 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 演示-

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 接口是一组 API,必须实现设备才能使用 OTA 库。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无线更新版本 3.0.0:OTAER_T.

OTA 关闭

在 OTA 库版本 1 中,用于关闭 OTA 代理的 API 为 OTA_Agent 关闭,现在随着输入参数的更改而更改为 OTA_ 关闭。

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

等待 OTA 代理完成关闭过程的报价次数。如果设置为零,函数将立即返回,而无需等待。实际状态将返回给调用者。代理在此过程中不会睡眠,但用于繁忙循环。

新输入参数-

取消订阅标志-

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

作为回报的变化-

外贸国家-

OTA 代理状态及其成员的枚举将被重命名。请参阅 Amazon IoT无线更新版本 3.0.0.

奥塔州

API 名称将从 OTA_ 座席状态更改为 OTA_ 地址状态。

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

外贸国家-

OTA 代理状态及其成员的枚举将被重命名。请参阅 Amazon IoT无线更新版本 3.0.0.

OTA_ 获取统计

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

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

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

输出参数-

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_ 激活新图像

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

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

返回 OTA 错误代码枚举被更改,并添加新的错误代码。请参阅 Amazon IoT无线更新版本 3.0.0:OTAER_T.

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

奥塔-塞蒂玛房地产

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

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

输入参数被重命名为 OtaImageState _t。请参阅 Amazon IoT无线更新版本 3.0.0.

返回 OTA 错误代码枚举被更改,并添加新的错误代码。请参阅 Amazon IoT无线更新版本 3.0.0/OTAER_T.

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

Ota_GETIMAGE 地产

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

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

返回枚举将重命名为 OtaImageState _t。请参阅 Amazon IoT无线更新版本 3.0.0:语音图像状态 _t.

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

OTA_ 暂停

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

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

返回 OTA 错误代码枚举被更改,并添加新的错误代码。请参阅 Amazon IoT无线更新版本 3.0.0:OTAER_T.

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

OTA_ 恢复

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

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

返回 OTA 错误代码枚举被更改,并添加新的错误代码。请参阅 Amazon IoT无线更新版本 3.0.0:OTAER_T.

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

OTA_ 检查更新

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

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

返回 OTA 错误代码枚举被更改,并添加新的错误代码。请参阅 Amazon IoT无线更新版本 3.0.0:OTAER_T.

OTA_ 事件处理任务

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

OTA 库版本 3
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_ 信号事件

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

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

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

如果你想将 OTA 库集成到你自己的应用程序中,你可以使用 git 子模块命令。Git 子模块允许您将 Git 存储库保存为另一个 Git 存储库的子目录。OTA 库版本 3 在Ota 对于 Amazon 物联网嵌入式 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 用户指南.

References