OTA エージェントをアプリケーションに統合する - 無料RTOS

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

OTA エージェントをアプリケーションに統合する

( over-the-airOTA) エージェントは、製品にOTA更新機能を追加するために書き込む必要があるコードの量を簡素化するように設計されています。この統合の負担は、主にOTAエージェントの初期化とOTA、エージェントイベントメッセージに応答するためのカスタムコールバック関数の作成で構成されます。初期化 OS 中に、MQTT、 HTTP (ファイルのダウンロードHTTPに使用される場合) およびプラットフォーム固有の実装 (PAL) インターフェイスが OTA エージェントに渡されます。バッファを初期化して OTA エージェントに渡すこともできます。

注記

OTA 更新機能のアプリケーションへの統合はかなり簡単ですが、OTA更新システムにはデバイスコードの統合以上の理解が必要です。モノ、認証情報、コード署名証明書、プロビジョニングデバイス、およびOTA更新ジョブで AWS AWS IoT アカウントを設定する方法を理解するには、「無料RTOS前提条件」を参照してください。

接続管理

OTA エージェントは、 AWS IoT サービスを含むすべてのコントロール通信オペレーションにMQTTプロトコルを使用しますが、MQTT接続は管理しません。OTA エージェントがアプリケーションの接続管理ポリシーに干渉しないようにするには、MQTT接続 (切断や再接続機能を含む) をメインユーザーアプリケーションで処理する必要があります。ファイルは、 MQTTまたは HTTPプロトコル経由でダウンロードできます。OTA ジョブを作成するときに、どのプロトコルを選択できます。を選択した場合MQTT、OTAエージェントはコントロールオペレーションとファイルのダウンロードに同じ接続を使用します。

シンプルなOTAデモ

以下は、エージェントがMQTTブローカーに接続し、OTAエージェントを初期化する方法を示す簡単なOTAデモの抜粋です。この例では、デフォルトのOTAアプリケーションコールバックを使用し、1 秒に 1 回一部の統計を返すようにデモを設定します。簡潔にするために、このデモから一部の詳細を省略します。

このOTAデモでは、切断コールバックをモニタリングし、MQTT接続を再確立することで、接続管理も示します。切断が発生すると、デモはまずOTAエージェントオペレーションを停止し、MQTT接続の再確立を試みます。MQTT 再接続の試行は、指数関数的に最大値まで増加し、ジッターも追加される時間だけ遅延します。接続が再確立された場合、OTAエージェントはオペレーションを続行します。

ブローカーを使用する AWS IoT MQTT作業例については、 demos/ota ディレクトリのOTAデモコードを参照してください。

OTA エージェントは独自のタスクであるため、この例の意図的な 1 秒の遅延は、このアプリケーションにのみ影響します。エージェントのパフォーマンスに影響はありません。

static BaseType_t prvRunOTADemo( void ) { /* Status indicating a successful demo or not. */ BaseType_t xStatus = pdFAIL; /* OTA library return status. */ OtaErr_t xOtaError = OtaErrUninitialized; /* OTA event message used for sending event to OTA Agent.*/ OtaEventMsg_t xEventMsg = { 0 }; /* OTA interface context required for library interface functions.*/ OtaInterfaces_t xOtaInterfaces; /* OTA library packet statistics per job.*/ OtaAgentStatistics_t xOtaStatistics = { 0 }; /* OTA Agent state returned from calling OTA_GetState.*/ OtaState_t xOtaState = OtaAgentStateStopped; /* Set OTA Library interfaces.*/ prvSetOtaInterfaces( &xOtaInterfaces ); /*************************** Init OTA Library. ***************************/ if( ( xOtaError = OTA_Init( &xOtaBuffer, &xOtaInterfaces, ( const uint8_t * ) ( democonfigCLIENT_IDENTIFIER ), prvOtaAppCallback ) ) != OtaErrNone ) { LogError( ( "Failed to initialize OTA Agent, exiting = %u.", xOtaError ) ); } else { xStatus = pdPASS; } /************************ Create OTA Agent Task. ************************/ if( xStatus == pdPASS ) { xStatus = xTaskCreate( prvOTAAgentTask, "OTA Agent Task", otaexampleAGENT_TASK_STACK_SIZE, NULL, otaexampleAGENT_TASK_PRIORITY, NULL ); if( xStatus != pdPASS ) { LogError( ( "Failed to create OTA agent task:" ) ); } } /****************************** Start OTA ******************************/ if( xStatus == pdPASS ) { /* Send start event to OTA Agent.*/ xEventMsg.eventId = OtaAgentEventStart; OTA_SignalEvent( &xEventMsg ); } /******************** Loop and display OTA statistics ********************/ if( xStatus == pdPASS ) { while( ( xOtaState = OTA_GetState() ) != OtaAgentStateStopped ) { /* Get OTA statistics for currently executing job. */ if( xOtaState != OtaAgentStateSuspended ) { OTA_GetStatistics( &xOtaStatistics ); LogInfo( ( " Received: %u Queued: %u Processed: %u Dropped: %u", xOtaStatistics.otaPacketsReceived, xOtaStatistics.otaPacketsQueued, xOtaStatistics.otaPacketsProcessed, xOtaStatistics.otaPacketsDropped ) ); } vTaskDelay( pdMS_TO_TICKS( otaexampleEXAMPLE_TASK_DELAY_MS ) ); } } return xStatus; }

このデモアプリケーションのハイレベルな流れは次のとおりです。

  • MQTT エージェントコンテキストを作成します。

  • AWS IoT エンドポイントに接続します。

  • OTA エージェントを初期化します。

  • OTA 更新ジョブを許可し、統計を 1 秒に 1 回出力するループ。

  • がMQTT切断された場合は、OTAエージェントオペレーションを停止します。

  • 指数関数的に増える時間間隔とジッターを使用して再度接続を試みます。

  • 再接続した場合は、OTAエージェントオペレーションを再開します。

  • エージェントが停止した場合は、1 秒遅らせて再接続を試みます。

OTA エージェントイベントのアプリケーションコールバックの使用

OTA エージェントイベントのコールバックハンドラーprvOtaAppCallbackとして使用された前の例。(OTA_InitAPI呼び出しの 4 番目のパラメータを参照してください)。完了イベントのカスタム処理を実装する場合は、OTAデモ/アプリケーションでデフォルトの処理を変更する必要があります。OTA プロセス中、OTAエージェントは次のいずれかのイベント列挙をコールバックハンドラーに送信できます。これらのイベントをどのように処理するかは、アプリケーション開発者が決定します。

/** * @ingroup ota_enum_types * @brief OTA Job callback events. * * After an OTA update image is received and authenticated, the agent calls the user * callback (set with the @ref OTA_Init API) with the value OtaJobEventActivate to * signal that the device must be rebooted to activate the new image. When the device * boots, if the OTA job status is in self test mode, the agent calls the user callback * with the value OtaJobEventStartTest, signaling that any additional self tests * should be performed. * * If the OTA receive fails for any reason, the agent calls the user callback with * the value OtaJobEventFail instead to allow the user to log the failure and take * any action deemed appropriate by the user code. * * See the OtaImageState_t type for more information. */ typedef enum OtaJobEvent { OtaJobEventActivate = 0, /*!< @brief OTA receive is authenticated and ready to activate. */ OtaJobEventFail = 1, /*!< @brief OTA receive failed. Unable to use this update. */ OtaJobEventStartTest = 2, /*!< @brief OTA job is now in self test, perform user tests. */ OtaJobEventProcessed = 3, /*!< @brief OTA event queued by OTA_SignalEvent is processed. */ OtaJobEventSelfTestFailed = 4, /*!< @brief OTA self-test failed for current job. */ OtaJobEventParseCustomJob = 5, /*!< @brief OTA event for parsing custom job document. */ OtaJobEventReceivedJob = 6, /*!< @brief OTA event when a new valid AFT-OTA job is received. */ OtaJobEventUpdateComplete = 7, /*!< @brief OTA event when the update is completed. */ OtaLastJobEvent = OtaJobEventStartTest } OtaJobEvent_t;

OTA エージェントは、メインアプリケーションのアクティブな処理中にバックグラウンドで更新を受け取ることができます。これらのイベントを配信する目的は、アクションを即時に実行できるかどうか、または他のアプリケーション固有の処理が完了するまで遅延する必要があるかどうかをアプリケーションが判断できるようにすることです。これによって、ファームウェアの更新後のリセットなどによるアクティブな処理中 (バキューム処理など) に、予期しないデバイスの中断を防ぐことができます。これらは、コールバックハンドラーによって受信されたたジョブイベントです。

OtaJobEventActivate

このイベントがコールバックハンドラーによって受信された場合、すぐにデバイスをリセットするか、後でデバイスをリセットするようコールをスケジュールすることができます。これにより、必要に応じてデバイスのリセットとセルフテストフェーズを延期できます。

OtaJobEventFail

このイベントがコールバックハンドラーによって受信されると、更新は失敗します。この場合、何もする必要はありません。ログメッセージを出力するか、アプリケーション固有の処理を行うことができます。

OtaJobEventStartTest

セルフテストフェーズは、新しく更新されたファームウェアが正常に機能しているかどうかを判断する前に、実行およびテストを行い、更新されたファームウェアを最新の永続的なアプリケーションイメージにコミットするように意図されています。新しい更新を受信して認証し、デバイスがリセットされると、OTAエージェントはテストの準備ができたらOtaJobEventStartTest、イベントをコールバック関数に送信します。開発者は、更新後にデバイスファームウェアが正しく機能しているかどうかを判断するために必要なテストを追加できます。デバイスファームウェアが自己テストによって信頼できると見なされた場合、コードは OTA_SetImageState( OtaImageStateAccepted ) 関数を呼び出すことで、ファームウェアを新しい永続イメージとしてコミットする必要があります。

OtaJobEventProcessed

によってキューに入れられたOTAイベントOTA_SignalEventが処理されるため、OTAバッファの解放などのクリーンアップ操作を実行できます。

OtaJobEventSelfTestFailed

現在のジョブのOTAセルフテストに失敗しました。このイベントのデフォルトの処理は、OTAエージェントがシャットダウンされ、デバイスが前のイメージにロールバックされるように再起動することです。

OtaJobEventUpdateComplete

OTA ジョブ更新完了の通知イベント。