OTAアップデートコマンド(ベータ)



OTAアップデートコマンド(ベータ)

このページでは、ガジェットのファームウェアをOTA(ワイヤレス)でアップデートするためにEchoデバイスからガジェットに送信されるコマンドについて説明します。Bluetooth経由でOTAアップデートを実行する手順については、OTAアップデートの概要を参照してください。

コマンドとは、Echoデバイスがガジェットに送信するリクエストです。その後、ガジェットはEchoデバイスに応答を送信します。まず、リクエストや応答を含むパケットの形式について説明します。次に、リクエストと応答に関連する特定のコマンドとフィールドの一覧を示します。

パケットの形式

このセクションでは、OTAアップデートのプロセス中にEchoデバイスとガジェットの間で通信を行う際のパケットの形式について説明します。

ディレクティブやイベントと同様に、Echoデバイスとガジェットは、Bluetooth経由でシリアルポートプロトコル(SPP)を使用してOTAアップデートのパケット交換を行います。ただし、OTAアップデートで使用されるパケット形式は、ディレクティブやイベントの交換の際に使用されるパケット形式とは若干異なります。OTAアップデートでは、別のRFCOMM接続も使用されます(OTAアップデートで使用されるRFCOMM UUIDは0x1101ですが、ディレクティブとイベントで使用されるRFCOMM UUIDは0x1201です)。

OTAアップデートに使用されるパケットには、次のルールが適用されます。

  • パケットレベルの同期では、次の特殊なバイト値が定義されます。
    • Start of frame(SOF)= 0xF0
    • End of frame(EOF)= 0xF1
    • Escape(ESC)= 0xF2
  • パケットは常にSOFバイトで始まり、EOFバイトで終わります。
  • パケット内のデータにSOF、EOF、またはESC値が含まれる場合、ESCバイトに続いてESCでXOR(排他的論理和)が行われた元の値を挿入することにより、値は「エスケープ」されます。
  • エスケープ文字を含まないパケットの最大サイズは264バイトです。

リクエストの形式

Echoデバイスからガジェットへのリクエストの形式は次のとおりです。

ガジェットのOTAアップデートのリクエスト

応答の形式

ガジェットは、Echoデバイスから送信されるすべてのコマンドに応答する必要があります。ガジェットからの応答の形式は次のとおりです。

ガジェットのOTAアップデートの応答

エラーコード

応答のErrorフィールドで想定される値は次のとおりです。

エラーコード エラータイプ 説明

0x00

ERR_NONE

コマンドは正常に実行されました。

0x01

ERR_UNKNOWN

コマンドがサポートされていません。

0x02

ERR_INVALID

ファームウェアイメージが無効です。

0x03

ERR_CKSUM

コマンドパケットのチェックサムが無効です。

データ検証

OTAアップデート時には、次の2種類のデータ検証が行われます。

  • 個々のリクエストと応答のチェックサム - このチェックサムで、ガジェットとEchoデバイスは、個々のリクエストと応答が破損していないかどうかを確認します。このチェックサムは、Echoデバイスからの各リクエストのChecksumフィールドにあり、ガジェットは応答時にChecksumを提供する必要があります。
  • バイナリーイメージ全体のCRC値 - Echoデバイスは、CMD_WRITE_METADATAコマンドのCRC32フィールドでバイナリーイメージ全体のCRC値を送信します。ガジェットがこのCRC値を使用する方法は複数あります。たとえば、ガジェットはこのCRC値を、すべてのCMD_WRITEコマンドから受信したデータを使用して算出されたCRC値と比較して、Echoデバイスからイメージを正常に受信したかどうかを確認できます。また、ガジェットはCRCを使用して、イメージが正常にフラッシュできるようにダウンロードされたかどうかを確認することもできます。バイナリーイメージ全体のCRC値を計算する際に含めるデータは、1)CMD_WRITE_SIGNATUREのペイロード(予約済み4バイト+OTAVersion 4バイト+署名の残りの部分)と、2)最後のCMD_WRITEの末尾のゼロを除くすべてのCMD_WRITEデータです。

コマンドリファレンス

このセクションでは、次のコマンドで使用されるリクエストと応答について説明します。

CMD_BATTERY(0x09)

このコマンドの目的は、ガジェットがOTAアップデートを実行するのに適した状態であるかどうかを確認することです。バッテリーレベルは、この判断に影響を与え得る要因の一例であるため、このコマンドは現時点ではCMD_BATTERYと呼びますが、変更される可能性があります。

影響を与える要因にかかわらず、ガジェットが0x0A以上の値を返した場合は更新が可能な状態であることを示し、0x0A未満の値の場合は更新の準備が整っていないことを示します。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x09

Reserved

1

予約済みです。

0x00

Checksum

2

このリクエストのチェックサムです。

CommandおよびReservedフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x09

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Battery level

1

更新を実行するガジェットの準備状況のインジケーターです。

範囲: 0100

0x0A以上=ガジェットで更新を実行できる状態

0x0A以下=ガジェットで更新を実行できる準備が整っていない

Checksum

2

この応答のチェックサムです。

CommandErrorBattery levelフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_ERASE(0x03)

このコマンドは、ガジェットにフラッシュバッファーの消去をリクエストします。

消去が完了するまでに数秒かかる場合があります。したがって、CMD_ERASEを送信した後、ガジェットが0x00を返して消去が完了したことを示すまで、EchoデバイスはガジェットにCMD_STATUSコマンドを繰り返し送信します。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x03

Reserved

1

予約済みです。

0x00

Checksum

2

このリクエストのチェックサムです。

CommandおよびReservedフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x03

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Checksum

2

この応答のチェックサムです。

CommandおよびErrorフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_STATUS(0x02)

このコマンドは、ガジェットにフラッシュバッファーのステータスをリクエストします。目的は、フラッシュバッファーの書き込みと消去の完了を確認することです。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x02

Reserved

1

予約済みです。

0x00

Checksum

2

このリクエストのチェックサムです。

CommandおよびReservedフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x02

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Flash status

1

フラッシュバッファーが消去またはコピーされているかどうかを示します。

0x00=フラッシュバッファーは読み取りまたは書き込みが可能な状態です。

0x01=フラッシュバッファーの消去を実行中です。

0x03=フラッシュバッファーのコピーを実行中です。

Checksum

2

この応答のチェックサムです。

CommandErrorFlash statusフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_VERSION(0x08)

このコマンドは、ガジェットに現在インストールされているファームウェアイメージのOTAバージョンを返すようリクエストします。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x08

Reserved

1

予約済みです。

0x00

Checksum

2

このリクエストのチェックサムです。

CommandおよびReservedフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x08

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Version

4

ガジェットに現在インストールされているファームウェアのOTAバージョンを示す32ビットの符号なし整数(ビッグエンディアン)です。

ガジェットが最初のファームウェアアップデートを受信するまで、OTAバージョンは0である必要があります。その後、ガジェットはアップデートプロセス中にCMD_WRITE_SIGNATUREからOTAバージョンを取得します。

Checksum

2

この応答のチェックサムです。

CommandErrorVersionフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_WRITE(0x05)

このコマンドは、Echoデバイスからガジェットにバイナリーイメージをダウンロードします。これは、Echoデバイスから繰り返し送信されます。Echoデバイスは、CMD_WRITE_METADATAおよびCMD_WRITE_SIGNATUREを送信した後にこのコマンドを送信します。

CMD_WRITEのCRC値の計算については、次の点に注意してください。

  • ガジェットは、各CMD_WRITEを受信するごとに、CRC値を増分で計算できます。ガジェットが最後のCMD_WRITEを受信する際に得られるイメージ全体のCRC値は、CMD_WRITE_METADATAから受信したCRC32値と比較することができます。
  • 最後のCMD_WRITEパケットには、データサイズを水増しして256バイトにするために末尾のゼロが含まれている場合があります。CRC値の計算では、これらの末尾のゼロを書き込んだり、算入したりしないでください。CMD_WRITEで受信したデータの合計サイズを追跡し、それをCMD_WRITE_METADATAで受信したデータのサイズと比較することで、末尾のゼロを削除できます。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x05

Reserved

1

予約済みです。

0x00

Address

4

OTAイメージの現在のセクションを書き込むアドレス(リトルエンディアン)です。

この値は0x00 0x02 0x00 0x00から始まり、毎回256ずつ増分されます。たとえば、次のセクターは0x00 0x03 0x00 0x00になります。

Data

256

Addressフィールドで指定された場所に書き込まれる最大256バイトのデータです。

任意の値

Checksum

2

このリクエストのチェックサムです。

CommandReservedAddressDataフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x05

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Checksum

2

この応答のチェックサムです。

CommandおよびErrorフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_WRITE_METADATA(0x10)

このコマンドは、イメージのメタデータをガジェットのフラッシュに書き込みます。これは、OTAアップデートの書き込みフェーズ中にEchoデバイスがガジェットに送信する最初の「書き込み」コマンドです。次にCMD_WRITE_SIGNATUREを送信し、その後CMD_WRITEを繰り返し送信します。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x10

Reserved

1

予約済みです。

0x00

Address

4

ファイル記述子セクターです。

常に0x00 0x00 0x00 0x00 0x00

Size

4

ビッグエンディアン表記のファイルサイズです。

たとえば、164,136(0x02 0x81 0x28)バイトのファイルサイズは、0x00 0x02 0x81 0x28と表されます。

CRC32

4

バイナリーイメージファイル全体のCRC32値(パディングやエスケープ文字は含まない)です。

たとえば、0xA4 0xA2 0xA7 0xD6のCRC32値は、0xA4 0xA2 0xA2 0xA7 0xD6と表されます。

Padding

パケットの残りの部分

未定義のパディングです。

通常、すべてのバイトは0xFFです。

Checksum

2

このリクエストのチェックサムです。

CommandReservedAddressSizeCRC32Paddingフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x10

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Checksum

2

この応答のチェックサムです。

CommandおよびErrorフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

CMD_WRITE_SIGNATURE(0x11)

このコマンドは、署名データをガジェットのフラッシュに書き込みます。これは、CMD_WRITEの前、CMD_WRITE_METADATAの後にEchoデバイスから送信されます。次の点に注意してください。

  • このコマンドのペイロードはOTAイメージの最初のセクターと見なされるため、CMD_WRITE_METADATAのCRC値の計算に含まれます。
  • ガジェットは、OTAVersionを新しいOTAバージョンとして不揮発性メモリに格納し、コマンドを受信したことを示すエラーコード0x00で、このコマンドに応答する必要があります。

リクエストのフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

コマンドIDです。

0x11

Reserved

1

ヘッダーの予約済みバイトです。

0x00

Address

4

ファイル記述子セクターです。

常に0x00 0x01 0x00 0x00

Reserved

4

ペイロードの予約済みバイトです。

なし

OTAVersion

4

OTAアップデートのバージョンです。

なし

Signature

パケットの残りの部分

署名データです(省略可能)。

なし

Checksum

2

このリクエストのチェックサムです。

CommandReservedSignatureフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1

応答のフィールド

フィールド バイト数 説明

Start of frame

1

フレーム開始インジケーターです。

0xF0

Command

1

この応答で適用されるコマンドのIDです。

0x11

Error

1

ガジェットから報告されたコマンドのエラーステータスです。

エラーコード0x00は正常に実行されたことを示します)

Checksum

2

この応答のチェックサムです。

CommandおよびErrorフィールド内の全文字のバイト数の合計(エスケープ文字は含まない)

End of frame

1

フレーム終了インジケーターです。

0xF1