WebUSB 用デバイスの作成

WebUSB API を最大限に活用するためのデバイスを構築します。

Reilly Grant

この記事では、WebUSB API を最大限に活用できるデバイスを構築する方法について説明します。API 自体の概要については、ウェブで USB デバイスにアクセスするをご覧ください。

背景

ユニバーサル シリアル バス（USB）は、周辺機器をデスクトップ コンピューティング デバイスやモバイル コンピューティング デバイスに接続するための最も一般的な物理インターフェースになっています。USB 仕様には、バスの電気特性とデバイスとの通信の一般的なモデルの定義に加えて、デバイスクラスの仕様が含まれています。これらは、デバイス メーカーが実装できる特定のデバイスクラス（ストレージ、オーディオ、ビデオ、ネットワーキングなど）の一般的なモデルです。これらのデバイスクラス仕様の利点は、オペレーティング システム ベンダーがクラス仕様に基づいて単一のドライバを実装できること（「クラスドライバ」）と、そのクラスを実装するすべてのデバイスがサポートされることです。これは、各メーカーが独自のデバイス ドライバを記述する必要があった場合と比べて大きな改善でした。

ただし、一部のデバイスは、これらの標準化されたデバイスクラスのいずれにも該当しません。メーカーは、代わりにベンダー固有のクラスを実装しているものとしてデバイスにラベルを付けることもできます。この場合、オペレーティング システムは、ベンダーのドライバ パッケージに提供されている情報に基づいて、読み込むデバイス ドライバを選択します。通常は、特定のベンダー固有のプロトコルを実装することが知られているベンダー ID とプロダクト ID のセットです。

USB のもう 1 つの特徴は、デバイスが接続先のホストに複数のインターフェースを提供できることです。各インターフェースは、標準化されたクラスを実装することも、ベンダー固有のクラスを実装することもできます。オペレーティング システムがデバイスを処理する適切なドライバを選択すると、各インターフェースは異なるドライバによって要求できます。たとえば、USB ウェブカメラは通常、2 つのインターフェースを提供します。1 つは USB ビデオクラスを実装し（カメラ用）、もう 1 つは USB 音声クラスを実装します（マイク用）。オペレーティング システムは、単一の「ウェブカメラ ドライバ」を読み込むのではなく、デバイスの個別の機能を担当する独立したビデオ クラス ドライバとオーディオ クラス ドライバを読み込みます。このインターフェース クラスの構成により、柔軟性が向上します。

API の基本

標準の USB クラスの多くには、対応するウェブ API があります。たとえば、ページは getUserMedia() を使用して動画クラスのデバイスから動画をキャプチャしたり、KeyboardEvents または PointerEvents をリッスンするか、Gamepad または WebHID API を使用して、ヒューマン インターフェース（HID）クラスのデバイスから入力イベントを受信したりできます。すべてのデバイスが標準化されたクラス定義を実装しているわけではないように、すべてのデバイスが既存のウェブ プラットフォーム API に対応する機能を実装しているわけではありません。このような場合、WebUSB API は、サイトがベンダー固有のインターフェースを宣言し、そのインターフェースのサポートをページ内から直接実装する方法を提供することで、このギャップを埋めることができます。

WebUSB 経由でデバイスにアクセスするための具体的な要件は、オペレーティング システムが USB デバイスを管理する方法の違いにより、プラットフォームによって若干異なります。ただし、基本的な要件として、ページが制御するインターフェースをデバイスがすでに宣言していないことが挙げられます。これは、OS ベンダーが提供する汎用クラスドライバか、ベンダーが提供するデバイス ドライバのいずれかです。USB デバイスは、それぞれに独自のドライバを持つ複数のインターフェースを提供できるため、一部のインターフェースはドライバによって要求され、その他のインターフェースはブラウザからアクセスできるデバイスを構築できます。

たとえば、ハイエンドの USB キーボードは、オペレーティング システムの入力サブシステムによって要求される HID クラス インターフェースと、WebUSB で使用可能で、構成ツールで使用できるベンダー固有のインターフェースを提供できます。このツールはメーカーのウェブサイトで提供され、ユーザーはプラットフォーム固有のソフトウェアをインストールしなくても、マクロキーや照明効果など、デバイスの動作の一部を変更できます。この場合、デバイスの設定記述子は次のようになります。

構成記述子は、複数の記述子が連結されたものです。各フィールドは、識別できるように bLength フィールドと bDescriptorType フィールドで始まります。1 つ目のインターフェースは、関連付けられた HID 記述子と、オペレーティング システムに入力イベントを配信するために使用される単一のエンドポイントを持つ HID インターフェースです。2 つ目のインターフェースは、デバイスにコマンドを送信し、レスポンスを受信するために使用できる 2 つのエンドポイントを持つベンダー固有のインターフェースです。

WebUSB 記述子

WebUSB はファームウェアを変更しなくても多くのデバイスで動作しますが、追加機能を有効にするには、WebUSB のサポートを示す特定の記述子でデバイスをマークする必要があります。たとえば、デバイスが電源に接続されているときにブラウザがユーザーを誘導するランディング ページの URL を指定できます。

バイナリ デバイス オブジェクト ストア（BOS）は USB 3.0 で導入されたコンセプトですが、バージョン 2.1 の一環として USB 2.0 デバイスにもバックポートされています。WebUSB のサポートを宣言するには、まず BOS 記述子に次のプラットフォーム機能記述子を追加します。

プラットフォーム機能 UUID は、デバイスに関する基本情報を提供する WebUSB プラットフォーム機能記述子としてこれを識別します。ブラウザはデバイスに関する詳細情報を取得するために、bVendorCode 値を使用してデバイスに追加のリクエストを発行します。現在指定されているリクエストは、URL 記述子を返す GET_URL のみです。これらは文字列記述子に似ていますが、URL を最小のバイト数でエンコードするように設計されています。"https://google.com" の URL 記述子は次のようになります。

デバイスを初めて接続したときに、ブラウザは次の標準の GET_DESCRIPTOR コントロール転送を実行して BOS 記述子を読み取ります。

このリクエストは通常 2 回行われます。1 回目は、ホストが大きな転送を commit せずに wTotalLength フィールドの値を検出できるように十分な大きさの wLength で、2 回目は完全な記述子の長さが判明したときに行われます。

WebUSB プラットフォーム キャパビティ記述子の iLandingPage フィールドがゼロ以外の値に設定されている場合、ブラウザは、bRequest をプラットフォーム キャパビティ記述子の bVendorCode 値に設定し、wValue を iLandingPage 値に設定してコントロール転送を発行することで、WebUSB 固有の GET_URL リクエストを実行します。GET_URL のリクエスト コード（0x02）は wIndex に格納します。

このリクエストは、最初に読み取られる記述子の長さをプローブするために、2 回発行される場合があります。

プラットフォーム固有の考慮事項

WebUSB API は USB デバイスにアクセスするための一貫したインターフェースを提供しようとしていますが、デベロッパーは、デバイスにアクセスするためのウェブブラウザの要件など、アプリに課される要件に注意する必要があります。

macOS

macOS では特別な設定は必要ありません。WebUSB を使用するウェブサイトは、デバイスに接続し、カーネル ドライバまたは別のアプリケーションによって要求されていないインターフェースを要求できます。

Linux

Linux は macOS に似ていますが、ほとんどのディストリビューションでは、デフォルトで USB デバイスを開く権限を持つユーザー アカウントが設定されていません。udev というシステム デーモンが、デバイスにアクセスできるユーザーとグループを割り当てる役割を担っています。このようなルールでは、指定されたベンダー ID と製品 ID に一致するデバイスの所有権が、周辺機器にアクセスできるユーザーの共通グループである plugdev グループに割り当てられます。

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

XXXX は、デバイスのベンダー ID とプロダクト ID の 16 進数で置き換えます。たとえば、ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" は Nexus One スマートフォンに対応します。正しく認識されるようにするには、通常の「0x」接頭辞を付けて、すべて小文字で記述する必要があります。デバイスの ID を確認するには、コマンドライン ツール lsusb を実行します。

このルールは /etc/udev/rules.d ディレクトリのファイルに配置し、デバイスが接続されるとすぐに有効になります。udev を再起動する必要はありません。

Android

Android プラットフォームは Linux をベースとしていますが、システム構成を変更する必要はありません。デフォルトでは、オペレーティング システムにドライバが組み込まれていないデバイスは、ブラウザで使用できます。ただし、ユーザーがデバイスに接続すると追加の手順が表示されることに注意する必要があります。ユーザーが requestDevice() の呼び出しに応答してデバイスを選択すると、Chrome にデバイスへのアクセスを許可するかどうかを尋ねるメッセージが Android に表示されます。デバイスへの接続権限がすでに付与されているウェブサイトにユーザーが戻り、そのウェブサイトで open() が呼び出された場合も、このメッセージが再表示されます。

また、デフォルトで含まれるドライバが少ないため、デスクトップ Linux よりも Android でアクセスできるデバイスが増えます。たとえば、Android SDK にはシリアル デバイスと通信するための API がないため、USB-シリアル アダプタで一般的に実装されている USB CDC-ACM クラスが含まれていません。

ChromeOS

ChromeOS も Linux をベースとしており、システム構成の変更も必要ありません。permission_broker サービスは USB デバイスへのアクセスを制御し、未使用のインターフェースが 1 つ以上ある限り、ブラウザが USB デバイスにアクセスできるようにします。

Windows

Windows ドライバモデルには追加の要件があります。上記のプラットフォームとは異なり、ドライバが読み込まれていない場合でも、ユーザー アプリケーションから USB デバイスを開く機能はデフォルトではありません。代わりに、アプリケーションがデバイスにアクセスするために使用するインターフェースを提供するために、特別なドライバ（WinUSB）を読み込む必要があります。これは、システムにインストールされているカスタム ドライバ情報ファイル（INF）を使用するか、デバイス ファームウェアを変更して、列挙中に Microsoft OS 互換性記述子を提供する方法で行うことができます。

ドライバ情報ファイル（INF）

ドライバ情報ファイルは、デバイスに初めて遭遇したときの処理を Windows に指示します。ユーザーのシステムには WinUSB ドライバがすでに含まれているため、必要なことは INF ファイルでベンダー ID とプロダクト ID をこの新しいインストール ルールに関連付けることだけです。以下のファイルは基本的な例です。.inf 拡張子のファイルに保存し、「X」でマークされたセクションを変更してから、右クリックしてコンテキスト メニューから [インストール] を選択します。

[Version]
Signature   = "$Windows NT$"
Class       = USBDevice
ClassGUID   = {88BAE032-5A81-49f0-BC3D-A4FF138216D6}
Provider    = %ManufacturerName%
CatalogFile = WinUSBInstallation.cat
DriverVer   = 09/04/2012,13.54.20.543

; ========== Manufacturer/Models sections ===========

[Manufacturer]
%ManufacturerName% = Standard,NTx86,NTia64,NTamd64

[Standard.NTx86]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTia64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

[Standard.NTamd64]
%USB\MyCustomDevice.DeviceDesc% = USB_Install,USB\VID_XXXX&PID_XXXX

; ========== Class definition ===========

[ClassInstall32]
AddReg = ClassInstall_AddReg

[ClassInstall_AddReg]
HKR,,,,%ClassName%
HKR,,NoInstallClass,,1
HKR,,IconPath,%REG_MULTI_SZ%,"%systemroot%\system32\setupapi.dll,-20"
HKR,,LowerLogoVersion,,5.2

; =================== Installation ===================

[USB_Install]
Include = winusb.inf
Needs   = WINUSB.NT

[USB_Install.Services]
Include = winusb.inf
Needs   = WINUSB.NT.Services

[USB_Install.HW]
AddReg = Dev_AddReg

[Dev_AddReg]
HKR,,DeviceInterfaceGUIDs,0x10000,"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"

; =================== Strings ===================

[Strings]
ManufacturerName              = "Your Company Name Here"
ClassName                     = "Your Company Devices"
USB\MyCustomDevice.DeviceDesc = "Your Device Name Here"

[Dev_AddReg] セクションでは、デバイスの DeviceInterfaceGUID のセットを構成します。アプリケーションが Windows API を介してデバイス インターフェースを見つけて接続するには、すべてのデバイス インターフェースに GUID が必要です。New-Guid PowerShell コマンドレットまたはオンライン ツールを使用して、ランダムな GUID を生成します。

開発目的では、Zadig ツールを使用して、USB インターフェース用に読み込まれたドライバを WinUSB ドライバに簡単に置き換えることができます。

Microsoft OS 互換性記述子

上記の INF ファイル方式は、すべてのユーザーのマシンを事前に構成する必要があるため、煩雑です。Windows 8.1 以降では、カスタム USB 記述子を使用する方法も用意されています。これらの記述子は、デバイスが最初に接続されたときに Windows オペレーティング システムに情報を提供します。通常、この情報は INF ファイルに含まれます。

WebUSB 記述子を設定すると、Microsoft の OS 互換性記述子も簡単に追加できます。まず、この追加のプラットフォーム機能記述子を使用して BOS 記述子を拡張します。これを考慮して、wTotalLength と bNumDeviceCaps を更新してください。

WebUSB デスクリプタと同様に、これらのデスクリプタに関連する制御転送で使用される bRequest 値を選択する必要があります。この例では 0x02 を選択しました。wIndex に配置される 0x07 は、デバイスから Microsoft OS 2.0 記述子セットを取得するコマンドです。

USB デバイスには複数の機能があるため、記述子セットの最初の部分には、続くプロパティが関連付けられている機能を記述します。次の例では、複合デバイスのインターフェース 1 を構成します。記述子には、このインターフェースに関する 2 つの重要な情報が OS に提供されます。互換 ID 記述子は、このデバイスが WinUSB ドライバと互換性があることを Windows に伝えます。レジストリ プロパティ記述子は、上記の INF の例の [Dev_AddReg] セクションと同様に機能し、この関数にデバイス インターフェース GUID を割り当てるようにレジストリ プロパティを設定します。

Windows がこの情報をデバイスに照会するのは 1 回だけです。デバイスが有効な記述子で応答しなかった場合、次回デバイスが接続されたときに再度確認されることはありません。Microsoft は、デバイスの列挙時に作成されるレジストリ エントリを説明するUSB デバイス レジストリ エントリのリストを提供しています。テストでは、デバイス用に作成されたエントリを削除して、Windows が記述子の再読み取りを試行するようにします。

これらの記述子の使用方法について詳しくは、Microsoft のブログ投稿をご覧ください。

例

WebUSB 記述子と Microsoft OS 記述子の両方を含む WebUSB 対応デバイスを実装するコードサンプルは、次のプロジェクトにあります。

• WebLight
• WebUSB Arduino ライブラリ