仕組み
USB デバイスが接続された直後に自分自身について申告する内容を表示します。デバイスディスクリプタには、USB-IF が割り当てたベンダー ID、メーカーが選んだ製品 ID、準拠すると称する USB 仕様のバージョン、製品自体のバージョン、そしてデバイスが公開していればメーカー・製品・シリアル番号の文字列が含まれます。
その下には完全なツリーが表示されます。各構成とそのインターフェイス、各インターフェイスのクラス・サブクラス・プロトコルの 3 要素を USB-IF の公式名称に変換したもの、そして各エンドポイントのアドレス、方向、転送タイプ、最大パケットサイズです。代替設定を複数持つインターフェイス —カメラやオーディオボードでよく見られます— は別に一覧表示されます。
このツールはディスクリプタを読み取るだけです。デバイスとのセッションを開くことも、インターフェイスを要求することも、1 バイトでも送信することもないため、そのデバイスを使っているドライバーの邪魔をしません。ツリー全体は JSON でエクスポートでき、レポートに添付したり別のコンピューターの結果と比較したりできます。
例
046D:C52B0x00 / 0x00 / 0x00 → 3 × HID (0x03)キーボードとマウスのワイヤレスレシーバーはデバイスレベルでクラス 0x00 を申告するため、実際の種類はインターフェイスごとに決まります。ここでは 3 つの HID インターフェイスがあり、それぞれにインタラプト入力エンドポイントが 1 つあります。0x08 / 0x06 / 0x50Mass Storage · SCSI transparent command set · Bulk-Only TransportUSB メモリーや外付けディスクの典型的な 3 要素です。入力と出力の 2 つのバルクエンドポイントがあり、その上を SCSI コマンドが流れます。0x02 / 0x02 / 0x01Communications and CDC Control · Abstract Control Model · AT Commands (ITU-T V.250)開発ボードやモデムの仮想シリアルポートです。インタラプトエンドポイントを 1 つ持つ制御インターフェイスと、データを運ぶ 2 つのバルクエンドポイントを持つ CDC-Data インターフェイスで構成されます。ユースケース
- ドライバーを探したり Linux で udev ルールを書いたりするために、デバイスの正確なベンダー ID と製品 ID を調べる。
- オペレーティングシステムがすぐには表示しない USB メモリー、リーダー、アダプターのシリアル番号を確認する。
- ファームウェア開発中に、デバイスが期待どおりのインターフェイス、代替設定、エンドポイントを正しいクラスで公開しているか確認する。
- デバイス向けに開発を始める前に、どのエンドポイントにどの転送タイプで話しかければよいかを把握する。
- 一見同じに見える 2 台のデバイスを、バージョン、インターフェイス、パケットサイズで見分ける。
- ツリー全体を JSON でエクスポートして、コンピューターの USB 構成を文書化する。
よくある質問
iPhone や Firefox で動かないのはなぜですか？
WebUSB API は Chromium ベースのブラウザー —Chrome、Edge、Opera— の Windows、macOS、Linux、ChromeOS、Android 版で実装されています。Firefox と Safari は実装しておらず、iOS ではすべてのブラウザーがシステムのエンジンを使うため、そちらでも利用できません。さらに HTTPS であることと、ページが他のサイトの中に埋め込まれていないことが必要です。
デバイスを接続しているのに選択画面に出てきません。
選んだフィルターが狭すぎるのかもしれません。すべてのデバイスを表示するオプションを試してください。それでも出てこない場合は、ブラウザーのブロックリストに載っている可能性が高いです。このリストは、どの Web ページも触れられないように、FIDO セキュリティキーなど一部の製品を安全上の理由で除外します。Linux ではデバイスノードに対するシステムの権限が不足していることもあります。
デバイスのクラスが 0x00 と表示されるのはなぜですか？
デバイスディスクリプタのクラス 0x00 は「インターフェイスを見てください」という意味です。1 本のケーブルで異なる機能をまとめる複合デバイスのほとんどがこれを使います。ハブ内蔵のキーボード、マイクも備えるカメラ、複合機のプリンターなどです。この場合、各機能の実際の種類はデバイスのクラスではなく、各インターフェイスのクラスにあります。
エンドポイントとは何ですか。0x81 のようなアドレスは何を意味しますか？
エンドポイントは、インターフェイスにデータが出入りするためのポストのようなものです。アドレスの下位 7 ビットがエンドポイント番号で、最上位ビットが方向を示します。つまり 0x81 は入力の エンドポイント 1 —デバイスからコンピューターへ— であり、0x01 なら出力のエンドポイント 1 になります。転送タイプは扱われ方を決めます。期限のない大量データにはバルク、キー入力のような小さく頻繁なイベントにはインタラプト、遅れて届くよりパケットを落とすほうがよい音声と映像にはアイソクロナスが使われます。
このツールでデバイスの設定が変わったり壊れたりしませんか？
いいえ。ブラウザーがデバイスを列挙した時点で取得済みのディスクリプタを読むだけで、セッションを開くことも、インターフェイスを要求することも、書き込むこともありません。だからこそ、Web ページが通信を許可されていないキーボードや USB メモリーであっても、オペレーティングシステムが使用中のまま調べられます。
メーカーや製品が空欄になるのはなぜですか？
これらの文字列は省略可能なディスクリプタです。安価なデバイスには書き込まれていないことが多く、一部のオペレーティングシステムはブラウザーに渡しません。そうした場合、このツールは Linux USB プロジェクトの usb.ids カタログでベンダー ID と製品 ID を検索します。このカタログにはメーカーの公式名が、多くの場合は製品名も登録されています。
デバイスのデータは自分のコンピューターの外に出ますか？
ディスクリプタはブラウザー内で読み取られ、どのサーバーにも送信されません。唯一の例外は usb.ids カタログの検索で、ベンダー ID と製品 ID —あなたのコンピューターや個体ではなく、機種を表す 2 つの数値— を問い合わせます。これはデバイスを選ぶ前に無効にできます。シリアル番号は決して送信されません。
インターフェイスの代替設定とは何ですか？
同じインターフェイスが複数のエンドポイントの組を申告し、そのうち 1 つだけを有効にできます。カメラやオーディオボードは、解像度や品質の組み合わせを変えるためにこれを使います。各代替設定はバス上で異なる帯域を確保し、オペレーティングシステムは転送を開始するときに適したものを選びます。デバイスが待機している間は代替設定 0 が有効なままです。