OTA アプリケーションのバージョン 1 からバージョン 3 への移行 - FreeRTOS

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

OTA アプリケーションのバージョン 1 からバージョン 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_AgentInit

OTA_Init

OTA v3 での実装の変更により、入力パラメータに加え、関数から返される値も変更されました。詳細については、下記の OTA_Init のセクションを参照してください。

OTA_AgentShutdown

OTA_Shutdown

MQTT トピックのサブスクライブを解除するオプションの追加パラメータを含む、入力パラメータが変更されました。詳細については、下記の OTA_Shutdown のセクションを参照してください。

OTA_GetAgentState

OTA_GetState

API 名が変更されましたが、入力パラメータに変更はありません。戻り値は同じですが、列挙型とメンバーの名前が変更されました。詳細については、下記の OTA_GetState のセクションを参照してください。

該当なし

OTA_GetStatistics

OTA_GetPacketsReceived、OTA_GetPacketsQueued、OTA_GetPacketsProcessed、OTA_GetPacketsDropped に代わる、新しく追加された API です。詳細については、下記の OTA_GetStatistics のセクションを参照してください。

OTA_GetPacketsReceived

該当なし

バージョン 3 からは、この API が削除され、OTA_GetStatistics に置き換えられました。

OTA_GetPacketsQueued

該当なし

バージョン 3 からは、この API が削除され、OTA_GetStatistics に置き換えられました。

OTA_GetPacketsProcessed

該当なし

バージョン 3 からは、この API が削除され、OTA_GetStatistics に置き換えられました。

OTA_GetPacketsDropped

該当なし

バージョン 3 からは、この API が削除され、OTA_GetStatistics に置き換えられました。

OTA_ActivateNewImage

OTA_ActivateNewImage

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。詳細については、OTA_ActivateNewImage のセクションを参照してください。

OTA_SetImageState

OTA_SetImageState

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、パラメータの名前が変更されました。また、返される OTA エラーコードの名前も変更され、新しいエラーコードが追加されました。詳細については、OTA_SetImageState のセクションを参照してください。

OTA_GetImageState

OTA_GetImageState

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、列挙型の戻り値の名前が変更されました。詳細については、OTA_GetImageState のセクションを参照してください。

OTA_Suspend

OTA_Suspend

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。詳細については、OTA_Suspend のセクションを参照してください。

OTA_Resume

OTA_Resume

OTA ライブラリのバージョン 3 では、接続の処理が OTA デモ/アプリケーション内で実行されるため、接続用の入力パラメータは削除されました。また、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。詳細については、OTA_Resume のセクションを参照してください。

OTA_CheckForUpdate

OTA_CheckForUpdate

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。詳細については、OTA_CheckForUpdate のセクションを参照してください。

該当なし

OTA_EventProcessingTask

新しく追加された API で、メインイベントループによって OTA 更新のイベントが処理されます。呼び出しは、アプリケーションタスクで実行する必要があります。詳細については、OTA_EventProcessingTask のセクションを参照してください。

該当なし

OTA_SignalEvent

新しく追加された API で、発生したイベントは OTA イベントキューの最後尾に追加されます。エージェントタスクを通知する際に、内部 OTA モジュールによって使用される API です。詳細については、OTA_SignalEvent のセクションを参照してください。

該当なし

OTA_Err_strerror

OTA エラーをエラーコードから文字列に変換する、新しい API です。

該当なし

OTA_JobParse_strerror

ジョブの解析エラーをエラーコードから文字列に変換する、新しい API です。

該当なし

OTA_OsStatus_strerror

OTA OS 移植のステータスをエラーコードから文字列に変換する、新しい API です。

該当なし

OTA_PalStatus_strerror

OTA PAL 移植のステータスをエラーコードから文字列に変換する、新しい API です。

必要な変更の説明

OTA_Init

バージョン 1 の OTA エージェントを初期化する際、接続コンテキスト、モノの名前、完全なコールバック、タイムアウトのパラメータを入力として受け取る OTA_AgentInit API が使用されます。

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

この API は、OTA、OTA インターフェイス、モノの名前、およびアプリケーションコールバックに必要なバッファのパラメータを有する OTA_Init に変更されました。

OtaErr_t OTA_Init( OtaAppBuffer_t * pOtaBuffer, OtaInterfaces_t * pOtaInterfaces, const uint8_t * pThingName, OtaAppCallback OtaAppCallback );
削除された入力パラメータ:
pvConnectionContext:

OTA ライブラリバージョン 3 では、接続コンテキストをパラメータに渡す必要がなく、MQTT/HTTP オペレーションは OTA デモ/アプリケーションの各インターフェイスによって処理されるため、接続コンテキストのパラメータは削除されました。

xTicksToWait:

OTA_Init を呼び出す前に、OTA デモ/アプリケーションでタスクが作成されるため、ティックのパラメータは削除されました。

名前が変更された入力パラメータ:
xFunc:

パラメータの名前が OtaAppCallback に変更され、パラメータタイプは OtaAppCallback_t に変更されました。

新しい入力パラメータ:
pOtaBuffer

初期化時に 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.
pOtaInterfaces

OTA_Init の 2 つ目の入力パラメータは、OtaInterfaces_t タイプの OTA インターフェースへの参照です。この一連のインターフェイスは、オペレーティングシステムインターフェイス、MQTT インターフェイス、HTTP インターフェイス、およびプラットフォーム抽象化レイヤーインターフェイス内にある OTA ライブラリおよびインクルードに渡す必要があります。

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 インターフェイスは、OTA ライブラリがストリーミングサービスからファイルブロックをダウンロードできるようにするために、ライブラリに実装する必要がある API 群です。

MQTT を介した OTA のデモの coreMQTT エージェント API の使用例は、次のとおりです。

OtaInterfaces_t otaInterfaces; otaInterfaces.mqtt.subscribe = prvMqttSubscribe; otaInterfaces.mqtt.publish = prvMqttPublish; otaInterfaces.mqtt.unsubscribe = prvMqttUnSubscribe;
HTTP インターフェイス

OTA HTTP インターフェイスは、OTA ライブラリが署名付き URL に接続してデータブロックを取得することで、ファイルブロックをダウンロードできるようにするために、ライブラリに実装する必要のある API 群です。ストリーミングサービスを使わず、署名付き URL からダウンロードするように OTA ライブラリを設定しない限り、このインターフェイスの実行は任意です。

HTPP を介した OTA のデモの coreHTTP API の使用例は、次のとおりです。

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 エラーコードに変更されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: otaErr_T

OTA_Shutdown

OTA エージェントを停止させる際に使用する API は、OTA ライブラリバージョン 1 では OTA_AgentShutdown でしたが、バージョン 3 からは OTA_Shutdown になり、入力パラメータも変更されました。

OTA エージェントのシャットダウン (バージョン 1)
OTA_State_t OTA_AgentShutdown( TickType_t xTicksToWait );
OTA エージェントのシャットダウン (バージョン 3)
OtaState_t OTA_Shutdown( uint32_t ticksToWait, uint8_t unsubscribeFlag );
ticksToWait:

OTA エージェントがシャットダウンプロセスを完了するまでの待機時間をティック数で示します。これをゼロに設定すると、待機時間なしで機能がすぐに戻ります。実際の状態は、呼び出し元に返されます。この間、エージェントはスリープ状態にはならず、ビジーループに使用されます。

新しい入力パラメータ:

unsubscribeFlag:

シャットダウンが呼び出されたときに、ジョブトピックからサブスクライブを解除するオペレーションを実行する必要があるかどうかを示すフラグです。フラグが 0 の場合、ジョブトピックのサブスクライブ解除のオペレーションは呼び出されません。ジョブトピックからアプリケーションをサブスクライブ解除する必要がある場合、OTA_Shutdown を呼び出す際には、このフラグを 1 に設定する必要があります。

戻り値の変更点:

OtaState_t:

OTA エージェントの状態の列挙型とそのメンバーの名前が変更されました。「」を参照してください。AWS 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 エージェントの状態の列挙型とそのメンバーの名前が変更されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0

OTA_GetStatistics

統計用に新しく追加された、単一の API です。この API は、OTA_GetPacketsReceived、OTA_GetPacketsQueued、OTA_GetPacketsProcessed、OTA_GetPacketsDropped に取って代わるものです。また、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 );
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_ActivateNewImage

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。

OTA ライブラリバージョン 1
OTA_Err_t OTA_ActivateNewImage( void );
OTA ライブラリバージョン 3
OtaErr_t OTA_ActivateNewImage( void );

返される OTA エラーコードの列挙型が変更され、新しいエラーコードが追加されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: otaErr_T

使用例:
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_ActivateNewImage(); /* Handle error */

OTA_SetImageState

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、パラメータの名前が変更されました。また、返される OTA エラーコードの名前も変更され、新しいエラーコードが追加されました。

OTA ライブラリバージョン 1
OTA_Err_t OTA_SetImageState( OTA_ImageState_t eState );
OTA ライブラリバージョン 3
OtaErr_t OTA_SetImageState( OtaImageState_t state );

入力パラメータの名前が OtaImageState_t に変更されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0

返される OTA エラーコードの列挙型が変更され、新しいエラーコードが追加されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0/OtaErr_t

使用例:
OtaErr_t otaErr = OtaErrNone; otaErr = OTA_SetImageState( OtaImageStateAccepted ); /* Handle error */

OTA_GetImageState

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、列挙型の戻り値の名前が変更されました。

OTA ライブラリバージョン 1
OTA_ImageState_t OTA_GetImageState( void );
OTA ライブラリバージョン 3
OtaImageState_t OTA_GetImageState( void );

列挙型の戻り値の名前は OtaImageState_t に変更されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: OtaImageState_T

使用例:
OtaImageState_t imageState; imageState = OTA_GetImageState();

OTA_Suspend

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。

OTA ライブラリバージョン 1
OTA_Err_t OTA_Suspend( void );
OTA ライブラリバージョン 3
OtaErr_t OTA_Suspend( void );

返される OTA エラーコードの列挙型が変更され、新しいエラーコードが追加されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: otaErr_T

使用例:
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Suspend(); /* Handle error */

OTA_Resume

OTA ライブラリのバージョン 3 では、接続の処理が OTA デモ/アプリケーション内で実行されるため、接続用の入力パラメータは削除されました。また、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。

OTA ライブラリバージョン 1
OTA_Err_t OTA_Resume( void * pxConnection );
OTA ライブラリバージョン 3
OtaErr_t OTA_Resume( void );

返される OTA エラーコードの列挙型が変更され、新しいエラーコードが追加されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: otaErr_T

使用例:
OtaErr_t xOtaError = OtaErrUninitialized; xOtaError = OTA_Resume(); /* Handle error */

OTA_CheckForUpdate

入力パラメータは同じですが、OTA ライブラリのバージョン 3 では、返される OTA エラーコードの名前が変更され、新しいエラーコードが追加されました。

OTA ライブラリバージョン 1
OTA_Err_t OTA_CheckForUpdate( void );
OTA ライブラリバージョン 3
OtaErr_t OTA_CheckForUpdate( void )

返される OTA エラーコードの列挙型が変更され、新しいエラーコードが追加されました。「」を参照してください。AWS IoT無線経由の更新 v3.0.0: otaErr_T

OTA_EventProcessingTask

新しく追加された 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_SignalEvent

発生したイベントを 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 submodule コマンドを使用します。git submodule コマンドを使用すると、Git リポジトリを別の Git リポジトリのサブディレクトリとして保存できます。OTA ライブラリバージョン 3 は、ota-for-aws-iot-embedded-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

詳細については、FreeRTOS ユーザーガイドアプリケーションへの OTA エージェントの統合を参照してください。

参照