Gerät für WebUSB erstellen

Erstellen Sie ein Gerät, um die WebUSB API optimal zu nutzen.

Reilly Grant

In diesem Artikel wird beschrieben, wie Sie ein Gerät erstellen, das die WebUSB API optimal nutzt. Eine kurze Einführung in die API selbst finden Sie unter Im Web auf USB-Geräte zugreifen.

Hintergrund

Der Universal Serial Bus (USB) ist die gängigste physische Schnittstelle für die Verbindung von Peripheriegeräten mit Desktop- und Mobilgeräten. Neben den elektrischen Eigenschaften des Busses und einem allgemeinen Modell für die Kommunikation mit einem Gerät enthalten die USB-Spezifikationen eine Reihe von Geräteklassenspezifikationen. Dies sind allgemeine Modelle für bestimmte Geräteklassen wie Speicher, Audio, Video, Netzwerk usw., die von Geräteherstellern implementiert werden können. Der Vorteil dieser Geräteklassenspezifikationen besteht darin, dass ein Betriebssystemanbieter anhand der Klassenspezifikation einen einzelnen Treiber implementieren kann (einen „Klassentreiber“). Alle Geräte, die diese Klasse implementieren, werden unterstützt. Das war eine große Verbesserung gegenüber der Situation, in der jeder Hersteller seine eigenen Gerätetreiber schreiben musste.

Einige Geräte passen jedoch nicht in eine dieser standardisierten Geräteklassen. Ein Hersteller kann sein Gerät stattdessen als Implementierung der anbieterspezifischen Klasse kennzeichnen. In diesem Fall wählt das Betriebssystem anhand der Informationen im Treiberpaket des Anbieters aus, welcher Gerätetreiber geladen werden soll. In der Regel handelt es sich dabei um eine Reihe von Anbieter- und Produkt-IDs, die ein bestimmtes anbieterspezifisches Protokoll implementieren.

Ein weiteres Merkmal von USB besteht darin, dass Geräte mehrere Schnittstellen zu dem Host bieten können, mit dem sie verbunden sind. Jede Schnittstelle kann entweder eine standardisierte Klasse implementieren oder anbieterspezifisch sein. Wenn ein Betriebssystem die richtigen Treiber für die Verarbeitung des Geräts auswählt, kann jede Schnittstelle von einem anderen Treiber beansprucht werden. Eine USB-Webcam bietet beispielsweise in der Regel zwei Schnittstellen, eine für die USB-Videoklasse (für die Kamera) und eine für die USB-Audioklasse (für das Mikrofon). Das Betriebssystem lädt keinen einzelnen "Webcam-Treiber", sondern stattdessen unabhängige Treiber für die Video- und Audioklasse, die die Verantwortung für die separaten Funktionen des Geräts übernehmen. Diese Zusammensetzung der Schnittstellenklassen sorgt für mehr Flexibilität.

API-Grundlagen

Viele Standard-USB-Klassen haben entsprechende Web-APIs. So kann eine Seite beispielsweise mit getUserMedia() Video von einem Gerät der Videoklasse erfassen oder Eingabeereignisse von einem Gerät der HID-Klasse (Human Interface Device) empfangen, indem auf KeyboardEvents oder PointerEvents gewartet oder das Gamepad oder die WebHID API verwendet wird. Genauso wie nicht alle Geräte eine standardisierte Klassendefinition implementieren, implementieren nicht alle Geräte Funktionen, die den APIs der vorhandenen Webplattformen entsprechen. In diesem Fall kann die WebUSB API diese Lücke schließen, indem Websites eine anbieterspezifische Schnittstelle anfordern und die Unterstützung dafür direkt auf ihrer Seite implementieren können.

Die spezifischen Anforderungen, damit ein Gerät über WebUSB zugänglich ist, variieren aufgrund von Unterschieden bei der Verwaltung von USB-Geräten durch Betriebssysteme leicht von Plattform zu Plattform. Die grundlegende Anforderung besteht jedoch darin, dass ein Gerät keinen Treiber für die Schnittstelle haben sollte, die die Seite steuern soll. Dies kann entweder ein generischer Klassentreiber sein, der vom Betriebssystemanbieter bereitgestellt wird, oder ein Gerätetreiber, der vom Anbieter bereitgestellt wird. Da USB-Geräte mehrere Schnittstellen haben können, von denen jede einen eigenen Treiber haben kann, ist es möglich, ein Gerät zu bauen, für das einige Schnittstellen von einem Treiber beansprucht und andere für den Browser zugänglich gemacht werden.

So kann eine High-End-USB-Tastatur beispielsweise eine HID-Klassenschnittstelle bereitstellen, die vom Eingabesubsystem des Betriebssystems beansprucht wird, und eine anbieterspezifische Schnittstelle, die für WebUSB zur Verwendung durch ein Konfigurationstool verfügbar bleibt. Dieses Tool kann auf der Website des Herstellers bereitgestellt werden, sodass Nutzer Aspekte des Geräteverhaltens wie Makroschaltflächen und Beleuchtungseffekte ändern können, ohne platformspezifische Software installieren zu müssen. Der Konfigurationsdeskriptor eines solchen Geräts würde in etwa so aussehen:

Der Konfigurationsdeskriptor besteht aus mehreren zusammenhängenden Deskriptoren. Jede beginnt mit den Feldern bLength und bDescriptorType, damit sie identifiziert werden können. Die erste Schnittstelle ist eine HID-Schnittstelle mit einem zugehörigen HID-Beschreibungselement und einem einzelnen Endpunkt, über den Eingabeereignisse an das Betriebssystem gesendet werden. Die zweite Schnittstelle ist eine anbieterspezifische Schnittstelle mit zwei Endpunkten, über die Befehle an das Gerät gesendet und Antworten empfangen werden können.

WebUSB-Deskriptoren

WebUSB kann zwar mit vielen Geräten ohne Firmware-Änderungen funktionieren, zusätzliche Funktionen werden jedoch aktiviert, wenn das Gerät mit bestimmten Descriptors gekennzeichnet ist, die die Unterstützung von WebUSB anzeigen. Sie können beispielsweise eine Landingpage-URL angeben, auf die der Browser den Nutzer weiterleiten kann, wenn Ihr Gerät angeschlossen ist.

Der Binary Device Object Store (BOS) ist ein Konzept, das mit USB 3.0 eingeführt wurde, aber auch als Teil von Version 2.1 auf USB 2.0-Geräte zurückportiert wurde. Die Deklaration der Unterstützung für WebUSB beginnt damit, dass der folgende Plattformfunktionsdeskriptor in den BOS-Deskriptor aufgenommen wird:

Die UUID der Plattformfunktion identifiziert dies als WebUSB-Plattformfunktions-Descriptor, der grundlegende Informationen zum Gerät enthält. Damit der Browser weitere Informationen zum Gerät abrufen kann, verwendet er den Wert bVendorCode, um zusätzliche Anfragen an das Gerät zu senden. Die einzige derzeit angegebene Anfrage ist GET_URL. Sie gibt einen URL-Deskriptor zurück. Sie ähneln Stringdeskriptoren, sind jedoch dafür vorgesehen, URLs mit wenigen Byte zu codieren. Ein URL-Beschreibungselement für "https://google.com" würde so aussehen:

Wenn Ihr Gerät zum ersten Mal angeschlossen wird, liest der Browser den BOS-Beschreibungsblock, indem er diese standardmäßige GET_DESCRIPTOR-Steuerungsübertragung ausgibt:

Diese Anfrage wird normalerweise zweimal gesendet. Das erste Mal mit einem ausreichend großen wLength, sodass der Host den Wert des Felds wTotalLength ermittelt, ohne eine große Übertragung zu übernehmen, und dann noch einmal, wenn die vollständige Deskriptorlänge bekannt ist.

Wenn im WebUSB-Plattformfunktionsdeskriptor das Feld iLandingPage auf einen Wert ungleich null gesetzt ist, führt der Browser eine WebUSB-spezifische GET_URL-Anfrage aus. Dabei wird bRequest aus dem Plattformfunktionsdeskriptor auf den Wert bVendorCode und wValue auf den Wert iLandingPage gesetzt. Der Anfragecode für GET_URL (0x02) wird in wIndex eingegeben:

Auch diese Anfrage kann zweimal gesendet werden, um zuerst die Länge des zu lesenden Descriptors zu prüfen.

Plattformspezifische Hinweise

Die WebUSB API soll zwar eine einheitliche Oberfläche für den Zugriff auf USB-Geräte bieten, Entwickler sollten sich aber trotzdem über die Anforderungen an Anwendungen im Klaren sein, z. B. die Anforderungen eines Webbrowsers für den Zugriff auf Geräte.

macOS

Für macOS ist nichts Besonderes erforderlich. Eine Website mit WebUSB kann eine Verbindung zum Gerät herstellen und alle Schnittstellen beanspruchen, die nicht von einem Kerneltreiber oder einer anderen Anwendung beansprucht werden.

Linux

Linux ist wie macOS, aber die meisten Distributionen richten standardmäßig keine Nutzerkonten mit der Berechtigung zum Öffnen von USB-Geräten ein. Ein System-Daemon namens udev ist für die Zuweisung des Nutzers und der Gruppe zuständig, die Zugriff auf ein Gerät haben. Mit einer Regel wie dieser wird die Inhaberschaft eines Geräts, das den angegebenen Anbieter- und Produkt-IDs entspricht, der Gruppe plugdev zugewiesen. Diese Gruppe ist eine gemeinsame Gruppe für Nutzer mit Zugriff auf Peripheriegeräte:

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

Ersetzen Sie XXXX durch die hexadezimalen Anbieter- und Produkt-IDs Ihres Geräts. Beispiel: ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" entspricht einem Nexus One-Smartphone. Sie müssen ohne das übliche Präfix „0x“ und in Kleinbuchstaben geschrieben werden, damit sie richtig erkannt werden. Führen Sie das Befehlszeilentool lsusb aus, um die IDs für Ihr Gerät zu ermitteln.

Diese Regel sollte in einer Datei im Verzeichnis /etc/udev/rules.d abgelegt werden und tritt in Kraft, sobald das Gerät angeschlossen ist. Sie müssen udev nicht neu starten.

Android

Die Android-Plattform basiert auf Linux, erfordert aber keine Änderungen an der Systemkonfiguration. Standardmäßig ist jedes Gerät, das keinen im Betriebssystem integrierten Treiber hat, für den Browser verfügbar. Entwickler sollten sich jedoch darüber im Klaren sein, dass beim Herstellen einer Verbindung zum Gerät ein zusätzlicher Schritt erforderlich ist. Wenn ein Nutzer auf eine Aufforderung zu requestDevice() reagiert und ein Gerät auswählt, wird auf dem Android-Gerät eine Aufforderung angezeigt, ob Chrome auf das Gerät zugreifen darf. Diese Aufforderung wird auch angezeigt, wenn ein Nutzer zu einer Website zurückkehrt, die bereits eine Berechtigung zum Herstellen einer Verbindung zu einem Gerät hat und die Website open() aufruft.

Außerdem wird unter Android mehr Geräte zugänglich sein als unter Desktop-Linux, da standardmäßig weniger Treiber enthalten sind. Ein bemerkenswertes Fehlen ist beispielsweise die USB-CDC-ACM-Klasse, die häufig von USB-zu-Seriell-Adaptern implementiert wird, da es im Android SDK keine API für die Kommunikation mit einem seriellen Gerät gibt.

ChromeOS

ChromeOS basiert ebenfalls auf Linux und erfordert keine Änderungen an der Systemkonfiguration. Der Dienst „permission_broker“ steuert den Zugriff auf USB-Geräte und erlaubt dem Browser, darauf zuzugreifen, solange es mindestens eine nicht beanspruchte Schnittstelle gibt.

Windows

Das Windows-Treibermodell stellt eine zusätzliche Anforderung. Im Gegensatz zu den oben genannten Plattformen ist es nicht standardmäßig möglich, ein USB-Gerät über eine Nutzeranwendung zu öffnen, auch wenn kein Treiber geladen ist. Stattdessen gibt es einen speziellen Treiber, WinUSB, der geladen werden muss, um die Schnittstelle bereitzustellen, über die Anwendungen auf das Gerät zugreifen. Dies kann entweder mit einer benutzerdefinierten INF-Datei (Driver Information File) erfolgen, die auf dem System installiert ist, oder durch Ändern der Gerätefirmware, um während der Aufzählung die Microsoft-Beschreibungen zur Betriebssystemkompatibilität bereitzustellen.

Driver Information File (INF)

Eine Treiberinformationsdatei teilt Windows mit, was zu tun ist, wenn ein Gerät zum ersten Mal erkannt wird. Da das System des Nutzers bereits den WinUSB-Treiber enthält, müssen Sie in der INF-Datei nur Ihre Anbieter- und Produkt-ID mit dieser neuen Installationsregel verknüpfen. Die folgende Datei ist ein einfaches Beispiel. Speichern Sie die Datei mit der Erweiterung .inf, ändern Sie die Abschnitte, die mit „X“ gekennzeichnet sind, klicken Sie mit der rechten Maustaste darauf und wählen Sie im Kontextmenü „Installieren“ aus.

[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"

Im Abschnitt [Dev_AddReg] wird die Gruppe der DeviceInterfaceGUIDs für das Gerät konfiguriert. Jede Geräteschnittstelle muss eine GUID haben, damit eine Anwendung sie über die Windows API finden und eine Verbindung herstellen kann. Verwenden Sie das New-Guid-PowerShell-Cmdlet oder ein Online-Tool, um eine zufällige GUID zu generieren.

Für Entwicklungszwecke bietet das Zadig-Tool eine einfache Oberfläche, um den für eine USB-Schnittstelle geladenen Treiber durch den WinUSB-Treiber zu ersetzen.

Kompatibilitätsdeskriptoren für Microsoft OS

Der oben beschriebene Ansatz mit der INF-Datei ist umständlich, da der Computer jedes Nutzers im Voraus konfiguriert werden muss. Windows 8.1 und höher bieten eine Alternative durch die Verwendung benutzerdefinierter USB-Beschreibungen. Diese Deskriptoren liefern dem Windows-Betriebssystem beim ersten Anschließen des Geräts Informationen, die normalerweise in der INF-Datei enthalten sind.

Nachdem Sie die WebUSB-Beschreibungen eingerichtet haben, können Sie auch die Beschreibungen zur Betriebssystemkompatibilität von Microsoft hinzufügen. Erweitern Sie zuerst den BOS-Beschreibungsblock mit diesem zusätzlichen Beschreibungsblock für Plattformfunktionen. Aktualisieren Sie wTotalLength und bNumDeviceCaps entsprechend.

Wie bei den WebUSB-Descriptors müssen Sie einen bRequest-Wert auswählen, der für Steuerübertragungen verwendet werden soll, die sich auf diese Descriptors beziehen. In diesem Beispiel habe ich 0x02 ausgewählt. 0x07, das in wIndex eingefügt wird, ist der Befehl zum Abrufen des Microsoft OS 2.0-Descriptor-Sets vom Gerät.

Ein USB-Gerät kann mehrere Funktionen haben. Daher beschreibt der erste Teil des Descriptor-Sets, welcher Funktion die folgenden Properties zugeordnet sind. Im folgenden Beispiel wird die Schnittstelle 1 eines zusammengesetzten Geräts konfiguriert. Der Descriptor liefert dem Betriebssystem zwei wichtige Informationen zu dieser Schnittstelle. Über den kompatiblen ID-Deskriptor wird Windows mitgeteilt, dass dieses Gerät mit dem WinUSB-Treiber kompatibel ist. Der Descriptor für die Registrierungseigenschaft funktioniert ähnlich wie der Abschnitt [Dev_AddReg] im obigen INF-Beispiel. Dabei wird eine Registrierungseigenschaft festgelegt, um dieser Funktion eine Geräteschnittstellen-GUID zuzuweisen.

Windows fragt das Gerät nur einmal nach diesen Informationen ab. Wenn das Gerät nicht mit gültigen Descriptors antwortet, wird beim nächsten Verbinden des Geräts nicht noch einmal gefragt. Microsoft hat eine Liste der USB-Geräte-Registryeinträge veröffentlicht, in der die Registryeinträge beschrieben werden, die beim Auflisten eines Geräts erstellt werden. Löschen Sie zum Testen die für ein Gerät erstellten Einträge, damit Windows versucht, die Deskriptoren noch einmal zu lesen.

Weitere Informationen zur Verwendung dieser Deskriptoren finden Sie im Blogpost von Microsoft.

Beispiele

Beispielcode für die Implementierung von WebUSB-kompatiblen Geräten, die sowohl WebUSB- als auch Microsoft-Beschreibungselemente enthalten, finden Sie in diesen Projekten:

• WebLight
• WebUSB Arduino Library