USB HIDフィーチャーレポートのデバッグ：GET_REPORT、SET_REPORT、ベンダーコマンド、デバイス設定の欠落

HIDデバイスはキーボードやマウスだけではありません。セキュリティキー、センサ、操作パネル、ベンダーツール、産業機器、ゲームコントローラ、UPSデバイス、独自コンフィギュレーションインターフェースなど、多種多様です。こうしたデバイスの多くはコンフィギュレーションとステータスにHIDフィーチャーレポートを使います。フィーチャーレポートが失敗すると、「HID Feature Report not working」「GET_REPORT failed」「SET_REPORT failed」「HID report ID mismatch」「USB HID vendor command timeout」で検索されることになります。通常の入力は動くのにコンフィギュレーションだけが動かない、というケースです。

Bus Scopeが効くのは、フィーチャーレポートがエンドポイントゼロを「コントロール転送」として流れることが多いからです。実際のSetupパケット、レポート種別、Report ID、長さ、応答ステータスがすべて鍵になります。

フィーチャーレポートとは

HIDにはいくつかのレポート種別があります。

• Inputレポート
• Outputレポート
• Featureレポート

InputレポートはInterrupt INエンドポイントで来ることが多いです。Featureレポートはコントロール転送で GET_REPORT や SET_REPORT を使って要求されるのが一般的です。

「ボタンは動くが設定パネルが失敗する」場合、フィーチャーレポート処理が疑わしい。

Report IDと長さの不一致

多くのHIDデバイスはReport IDを使います。ホストがReport ID 3を含めて送っているのに、ファームウェアがReport ID 0を期待していると、リクエストが失敗したり誤データを返したりします。

よくあるバグ：

• ファームウェアがReport IDバイトを省いてしまう
• ホストが誤ったレポート長を送る
• ディスクリプタが長さAと宣言しているのにファームウェアが長さBを返す
• フィーチャーレポートはファームウェア上存在するがディスクリプタにない
• ディスクリプタがファームウェアに存在しないレポートを宣言している

HIDレポートディスクリプタとコントロール転送を突き合わせる必要があります。

GET_REPORTとSET_REPORTの証拠

確認ポイント：

• Setupパケットのリクエスト種別
• HID GET_REPORT または SET_REPORT
• レポート種別 Feature
• Report ID
• wLength
• データステージのバイト
• STALL／タイムアウト

ディスクリプタが掲示しているフィーチャーレポートをデバイスがストールするなら、ファームウェアかディスクリプタの一貫性が疑わしい。

HID経由のベンダーコンフィギュレーション

多くの製品が「独自カーネルドライバを避けたい」理由でHIDを採用しています。ベンダー設定はフィーチャーレポートとして実装されることがあります。

例：

• サンプリングレートの変更
• ファームウェアバージョンの読み取り
• LEDモードの設定
• センサレンジのコンフィギュレーション
• ブートローダーの有効化
• キャリブレーションデータの読み取り

こうしたコマンドが失敗しても、デバイスはHIDデバイスとして正常に見えることがあります。

デバッグチェックリスト

次の流れで作業すると、原因に早くたどり着けます。

1. 列挙とHIDディスクリプタをキャプチャする
2. HIDレポートディスクリプタを保全する
3. フィーチャーレポート定義を特定する
4. 失敗する GET_REPORT／SET_REPORT をキャプチャする
5. Report IDを確認する
6. 要求長を確認する
7. ディスクリプタの宣言長と転送長を比較する
8. STALL／タイムアウト／短縮応答を探す
9. 動くInputレポートと失敗するFeatureレポートを比較する
10. ディスクリプタとコントロール転送を一緒に保全する

最終的な診断

HIDフィーチャーレポートの失敗は、多くの場合「ディスクリプタ／Report ID／長さ／ファームウェア状態／コントロール転送処理」の問題です。入力は動くのにコンフィギュレーションだけが落ちます。

Bus Scopeは、HIDレポートの契約と失敗した正確なコントロール転送をそのまま可視化するので、「謎のベンダーツールエラー」ではなく診断可能な問題にしてくれます。