BLE・USB機器プロトコル設計ノート

要点: 機器プロトコルは、どちら側の実装も始める前に文書化します。トランスポートへの対応付け、フレーム形式、メッセージ種別、バージョン管理、エラーコード、タイムアウトです。アプリケーション層のプロトコルはBLEやUSBから独立させ、シリアルケーブルでもテストできるようにします。共通の仕様書とホスト側のテストハーネスがあれば、ファームウェアとアプリのチームが並行して作業でき、食い違いを早く見つけられます。

機器プロトコルの階層図:スマートフォンやPCのアプリケーションがプロトコルライブラリを介してBLE GATTまたはUSB CDC/HIDのトランスポートアダプタと通信し、機器側のトランスポートドライバ、フレームパーサ、コマンドディスパッチャ、機器アプリケーションへ届く。ホスト側のテストハーネスはフレーム層に接続する。
図1. プロトコルの階層。トランスポートは変わっても、フレーム層とメッセージ層は変わらない。

1.0 機器プロトコルがこじれる原因

プロトコルの問題の多くは、BLEやUSBそのものが原因ではありません。インタフェースが一度も文書化されていないことが原因です。ファームウェア担当がバイト配置を決め、アプリ担当がそれをログから読み取り、両者が少しずつずれていきます。2回目のファームウェアリリースの頃には、どちらが正しいのか誰にも分からなくなり、更新によってストアに出ているアプリが動かなくなり、修正には両側の足並みをそろえたリリースが必要になります。

仕様書の対象は、トランスポート、フレーム、メッセージ表、エラー表、タイムアウトです。最初のスニファ取得より前に書いてください。後からではありません。

2.0 階層化

各層を単独でテストできるよう、プロトコルを層に分けます。

層役割変更が生じるとき
トランスポートバイトの転送:BLE GATTキャラクタリスティック、USB CDC-ACM、USB HIDレポート、UARTハードウェアやOSが変わったとき
フレーミングメッセージ境界、長さ、整合性チェック、シーケンス番号まれ
メッセージコマンドとレスポンスの種別、ペイロードのエンコード、エラーコード新機能の追加時
アプリケーション機器がコマンドを受けて何をするか製品の動作が変わったとき

フレーミング層とメッセージ層は、下にどのトランスポートがあるかを知らないようにします。そうすれば同じプロトコルを、評価時はUART、量産検査ではUSBシリアル変換器、製品ではBLEで動かせます。

3.0 トランスポートの選択

要件BLEUSB CDC-ACM(仮想シリアル)USB HID
スマートフォンとの無線接続本来の用途対象外対象外
デスクトップOSでドライバ不要OSのBluetoothスタックが必要Windows 10以降、macOS、Linuxは標準ドライバで動作ドライバ不要
ブラウザからのアクセス対応環境ではWeb Bluetooth対応環境ではWeb Serial対応環境ではWebHID
スループット接続間隔とMTUで制限高いレポートサイズとポーリングで制限
消費電力低消費電力向けに設計接続中はバスから給電できるCDCと同じ

Web Bluetooth、Web Serial、WebHIDの対応状況はブラウザとプラットフォームによって異なります。前提にする前に、ユーザーが使うブラウザでの現状を確認してください。両方を使う製品も多く、スマートフォンアプリにはBLE、設定・工場検査・復旧にはUSBという分け方をします。

3.1 BLE GATTへの対応付け

よく使われる方法は2つあります。

  • 値ごとに属性を割り当てる。 設定値や測定値ごとに個別のキャラクタリスティックにします。汎用のBLEツールで中身を確認しやすい反面、機能追加のたびにGATTテーブルが変わり、複数フィールドの更新はアトミックになりません。
  • メッセージパイプ。 ホストから機器への書き込み用に1つ、機器からホストへの通知用に1つのキャラクタリスティックを用意し、フレーム化したメッセージを流します。全機能を1つのプロトコルで扱え、GATTテーブルは変わりません。

機器が公開する値が数個を超えたらメッセージパイプを使い、標準サービス(Device Information、Battery)は汎用ツールが使えるよう属性のまま残します。カスタムサービスには128ビットUUIDが必要です。標準のUUIDはBluetooth SIGのAssigned Numbersに載っています。

スループットとレイテンシは接続パラメータとネゴシエーションされたATT MTUで決まり、これを主に決めるのは機器ではなくスマートフォン側です。1つのメッセージが複数の通知にまたがっても再構成できるようにプロトコルを設計し、特定のMTUを前提にしないでください。

3.2 USBへの対応付け

CDC-ACMはホストからシリアルポートに見え、フレーミング付きのバイトストリーム型プロトコルに向きます。HIDは固定長のレポートを使い、ドライバなしで動くため、制限の厳しい社内PCで役立ちます。この場合はフレーミング層がメッセージを複数のレポートに分割します。どちらのクラス仕様もUSB-IFが公開しています。

4.0 フレーム

出発点にしているフレーム形式です。

フィールドサイズ備考
開始マーカーまたは長さプレフィックス1〜2バイトBLE/HIDでは長さプレフィックス、バイトストリームではCOBSやSLIP方式の区切り
プロトコルバージョン1バイトフレーム形式のメジャーバージョン
シーケンス番号1〜2バイトレスポンスとリクエストを対応付け、欠落を検出
メッセージ種別1〜2バイトコマンド、レスポンス、イベント、エラー
ペイロード長2バイトトランスポート側に長さ情報があっても明示する
ペイロード可変エンコードは案件ごとに選択(固定構造体、TLV、CBOR、protobuf)
整合性チェック2〜4バイトバイトストリームではCRC。トランスポートがチェック済みなら省略可

ペイロードのエンコードは、機器側のコードサイズと柔軟性のトレードオフです。リトルエンディアンの固定構造体は最も小さい反面、拡張が最も難しくなります。TLVやCBORなら、古い読み手を壊さずに任意フィールドを追加できます。

5.0 バージョン管理と互換性

互換性のルールを文書にします。私たちのルールは次のとおりです。

  1. 機器は、形が決して変わらない「hello」または「get info」コマンドへの応答で、プロトコルバージョンと機能フラグを返す。
  2. 新しいフィールドは任意項目として追加する。読み手は理解できないフィールドを無視する。
  3. フィールドの削除や意味の変更にはメジャーバージョンの変更が必要で、アプリは文書化した期間、直前のメジャーバージョンもサポートし続ける。
  4. ファームウェアとアプリのリリースノートに、対応するプロトコルバージョンを記載する。

6.0 エラー、タイムアウト、状態

どのコマンドにもレスポンスは必ず1つです。データ付きの成功か、文書化したエラー表のエラーコードかのどちらかです。代表的なエラー分類は、不正なフレーム、未知のコマンド、無効なパラメータ、ビジー、現在の状態では許可されない操作、内部エラーです。エラー表はコードの中だけでなく仕様書に載せます。

タイムアウトもプロトコルの一部です。コマンド分類ごとの最大応答時間、タイムアウト時のホストの動作(同じシーケンス番号で再送するか、諦めるか)、分割メッセージの残りを機器が破棄するまでに待つ時間を定めます。

ファームウェア更新やキャリブレーションのような時間のかかる処理は、レスポンスをブロックせず、すぐに「受理」を返して進捗をイベントで通知します。

7.0 セキュリティ上の考慮

BLEのペアリングとボンディングはリンクを保護しますが、認証済みの相手に何を許可するかまでは決めません。状態を変えるコマンド、認可されたセッションが必要なコマンド、接続中のどのホストに公開しても安全なコマンドを一覧にします。工場用とデバッグ用のコマンドは量産ファームウェアで無効化またはロックし、その方法を仕様書に書きます。

8.0 テストハーネス

シリアルポート経由でプロトコルを話す小さなホスト側ツールを、案件上の指定がなければPythonで書きます。役割は3つです。アプリがまだない段階でファームウェア担当がコマンドを試せること、作業台の基板に対してCIでスクリプト化した回帰テストを回せること、アプリチームが比較に使える参照実装になることです。同じツールで不正な入力をフレームパーサに与えるファジングを行うと、通常の使い方では起きない種類のクラッシュが見つかります。

9.0 引き渡し物

  • プロトコル仕様書:トランスポート、フレーム、メッセージ表、エラー表、タイムアウト、バージョン規則。
  • GATTテーブルまたはUSBディスクリプタ。
  • ホスト側テストツールとそのスクリプト。
  • コマンドごとに取得した通信例。

この作業の機器側は組込みファームウェアのページで、機器と通信するアプリとバックエンドはWeb・クラウド・デバイス管理で扱っています。既存プロトコルのレビューをご希望の場合は、プロジェクトのご相談フォームからどうぞ。

参考資料

よくあるご質問

BLEは標準プロファイルとカスタムサービスのどちらを使うべきですか?

BatteryやDevice Informationのように、データに合う標準サービスがあればそれを使います。汎用ツールやOSがそのまま解釈できるからです。製品固有の機能にはカスタムサービスが必要です。メッセージパイプ型のサービスを1つにしておけば、機能を追加してもカスタム部分は変わりません。

ペイロードのエンコード方式はどう選べばよいですか?

機器のフラッシュとRAMの余裕、そしてプロトコルが変わる頻度の見込みで決めます。固定構造体は小さく安定したコマンドセットに向きます。TLVやCBORはコードが増えますが、古いアプリを壊さずにフィールドを追加できます。

ファームウェア更新後も古いアプリを動かし続けるには?

バージョン問い合わせコマンドは永久に変えない、フィールドは任意項目として追加する、読み手は未知のフィールドを無視する、の3点です。互換性を壊す変更は新しいメジャーバージョンにまとめ、旧バージョンのサポート期間を双方のリリースノートに明記します。

同じプロトコルをBLEとUSBの両方で使えますか?

フレーミングとメッセージをトランスポートから切り離しておくのは、まさにそのためです。変わるのはトランスポートアダプタだけです。製品アプリがBLEを使う一方で、工場検査や復旧用のツールはケーブル経由で使えます。

プロトコル仕様はいつ書くべきですか?

ファームウェアとアプリの開発が本格的に始まる前です。初版は短くて構いません。トランスポート、フレーム、5〜6個のコマンド、エラー表があれば十分です。以降はデバッグではなくレビューを通じて変えていきます。