BLE・USB機器プロトコル設計ノート
要点: 機器プロトコルは、どちら側の実装も始める前に文書化します。トランスポートへの対応付け、フレーム形式、メッセージ種別、バージョン管理、エラーコード、タイムアウトです。アプリケーション層のプロトコルはBLEやUSBから独立させ、シリアルケーブルでもテストできるようにします。共通の仕様書とホスト側のテストハーネスがあれば、ファームウェアとアプリのチームが並行して作業でき、食い違いを早く見つけられます。
1.0 機器プロトコルがこじれる原因
プロトコルの問題の多くは、BLEやUSBそのものが原因ではありません。インタフェースが一度も文書化されていないことが原因です。ファームウェア担当がバイト配置を決め、アプリ担当がそれをログから読み取り、両者が少しずつずれていきます。2回目のファームウェアリリースの頃には、どちらが正しいのか誰にも分からなくなり、更新によってストアに出ているアプリが動かなくなり、修正には両側の足並みをそろえたリリースが必要になります。
仕様書の対象は、トランスポート、フレーム、メッセージ表、エラー表、タイムアウトです。最初のスニファ取得より前に書いてください。後からではありません。
2.0 階層化
各層を単独でテストできるよう、プロトコルを層に分けます。
| 層 | 役割 | 変更が生じるとき |
|---|---|---|
| トランスポート | バイトの転送:BLE GATTキャラクタリスティック、USB CDC-ACM、USB HIDレポート、UART | ハードウェアやOSが変わったとき |
| フレーミング | メッセージ境界、長さ、整合性チェック、シーケンス番号 | まれ |
| メッセージ | コマンドとレスポンスの種別、ペイロードのエンコード、エラーコード | 新機能の追加時 |
| アプリケーション | 機器がコマンドを受けて何をするか | 製品の動作が変わったとき |
フレーミング層とメッセージ層は、下にどのトランスポートがあるかを知らないようにします。そうすれば同じプロトコルを、評価時はUART、量産検査ではUSBシリアル変換器、製品ではBLEで動かせます。
3.0 トランスポートの選択
| 要件 | BLE | USB 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 バージョン管理と互換性
互換性のルールを文書にします。私たちのルールは次のとおりです。
- 機器は、形が決して変わらない「hello」または「get info」コマンドへの応答で、プロトコルバージョンと機能フラグを返す。
- 新しいフィールドは任意項目として追加する。読み手は理解できないフィールドを無視する。
- フィールドの削除や意味の変更にはメジャーバージョンの変更が必要で、アプリは文書化した期間、直前のメジャーバージョンもサポートし続ける。
- ファームウェアとアプリのリリースノートに、対応するプロトコルバージョンを記載する。
6.0 エラー、タイムアウト、状態
どのコマンドにもレスポンスは必ず1つです。データ付きの成功か、文書化したエラー表のエラーコードかのどちらかです。代表的なエラー分類は、不正なフレーム、未知のコマンド、無効なパラメータ、ビジー、現在の状態では許可されない操作、内部エラーです。エラー表はコードの中だけでなく仕様書に載せます。
タイムアウトもプロトコルの一部です。コマンド分類ごとの最大応答時間、タイムアウト時のホストの動作(同じシーケンス番号で再送するか、諦めるか)、分割メッセージの残りを機器が破棄するまでに待つ時間を定めます。
ファームウェア更新やキャリブレーションのような時間のかかる処理は、レスポンスをブロックせず、すぐに「受理」を返して進捗をイベントで通知します。
7.0 セキュリティ上の考慮
BLEのペアリングとボンディングはリンクを保護しますが、認証済みの相手に何を許可するかまでは決めません。状態を変えるコマンド、認可されたセッションが必要なコマンド、接続中のどのホストに公開しても安全なコマンドを一覧にします。工場用とデバッグ用のコマンドは量産ファームウェアで無効化またはロックし、その方法を仕様書に書きます。
8.0 テストハーネス
シリアルポート経由でプロトコルを話す小さなホスト側ツールを、案件上の指定がなければPythonで書きます。役割は3つです。アプリがまだない段階でファームウェア担当がコマンドを試せること、作業台の基板に対してCIでスクリプト化した回帰テストを回せること、アプリチームが比較に使える参照実装になることです。同じツールで不正な入力をフレームパーサに与えるファジングを行うと、通常の使い方では起きない種類のクラッシュが見つかります。
9.0 引き渡し物
- プロトコル仕様書:トランスポート、フレーム、メッセージ表、エラー表、タイムアウト、バージョン規則。
- GATTテーブルまたはUSBディスクリプタ。
- ホスト側テストツールとそのスクリプト。
- コマンドごとに取得した通信例。
この作業の機器側は組込みファームウェアのページで、機器と通信するアプリとバックエンドはWeb・クラウド・デバイス管理で扱っています。既存プロトコルのレビューをご希望の場合は、プロジェクトのご相談フォームからどうぞ。
参考資料
- Bluetooth Core Specification: https://www.bluetooth.com/specifications/specs/core-specification/
- Bluetooth Assigned Numbers: https://www.bluetooth.com/specifications/assigned-numbers/
- USB Class Definitions for Communication Devices 1.2: https://www.usb.org/document-library/class-definitions-communication-devices-12
- USB Device Class Definition for HID: https://www.usb.org/hid
よくあるご質問
BLEは標準プロファイルとカスタムサービスのどちらを使うべきですか?
BatteryやDevice Informationのように、データに合う標準サービスがあればそれを使います。汎用ツールやOSがそのまま解釈できるからです。製品固有の機能にはカスタムサービスが必要です。メッセージパイプ型のサービスを1つにしておけば、機能を追加してもカスタム部分は変わりません。
ペイロードのエンコード方式はどう選べばよいですか?
機器のフラッシュとRAMの余裕、そしてプロトコルが変わる頻度の見込みで決めます。固定構造体は小さく安定したコマンドセットに向きます。TLVやCBORはコードが増えますが、古いアプリを壊さずにフィールドを追加できます。
ファームウェア更新後も古いアプリを動かし続けるには?
バージョン問い合わせコマンドは永久に変えない、フィールドは任意項目として追加する、読み手は未知のフィールドを無視する、の3点です。互換性を壊す変更は新しいメジャーバージョンにまとめ、旧バージョンのサポート期間を双方のリリースノートに明記します。
同じプロトコルをBLEとUSBの両方で使えますか?
フレーミングとメッセージをトランスポートから切り離しておくのは、まさにそのためです。変わるのはトランスポートアダプタだけです。製品アプリがBLEを使う一方で、工場検査や復旧用のツールはケーブル経由で使えます。
プロトコル仕様はいつ書くべきですか?
ファームウェアとアプリの開発が本格的に始まる前です。初版は短くて構いません。トランスポート、フレーム、5〜6個のコマンド、エラー表があれば十分です。以降はデバッグではなくレビューを通じて変えていきます。