Gerät für WebUSB erstellen

Erstellen Sie ein Gerät, das die WebUSB API optimal nutzt.

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 Über das 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 einen einzelnen Treiber basierend auf der Klassenspezifikation implementieren kann (einen „Klassentreiber“). Alle Geräte, die diese Klasse implementieren, werden dann 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 Gerät mit der implementierten 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.

Eine weitere Besonderheit von USB ist, dass Geräte mehrere Schnittstellen zum Host bereitstellen 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 unabhängige Video- und Audio-Klassentreiber, die für die einzelnen Funktionen des Geräts verantwortlich sind. Diese Zusammensetzung von Interface-Klassen bietet mehr Flexibilität.

API-Grundlagen

Viele der 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 vom Betriebssystemanbieter bereitgestellter generischer Klassentreiber oder ein vom Anbieter bereitgestellter Gerätetreiber sein. 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 der Nutzer Aspekte des Geräteverhaltens wie Makroschaltflächen und Beleuchtungseffekte ändern kann, 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 in USB 3.0 eingeführt wurde, aber im Rahmen von Version 2.1 auch auf USB 2.0-Geräte übertragen wurde. Wenn Sie die Unterstützung für WebUSB deklarieren möchten, müssen Sie zuerst den folgenden Deskriptor für die Plattformfunktion in den BOS-Deskriptor aufnehmen:

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. Derzeit ist nur die Anfrage GET_URL angegeben, die einen URL-Beschreibungsblock zurückgibt. Sie ähneln String-Beschreibungen, sind aber so konzipiert, dass URLs mit möglichst wenigen Bytes codiert werden. 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 in der Regel zweimal gesendet, das erste Mal mit einem ausreichend großen wLength, damit der Host den Wert des wTotalLength-Felds ermitteln kann, ohne sich zu einer großen Übertragung zu verpflichten, und dann noch einmal, wenn die vollständige Descriptor-Länge bekannt ist.

Wenn im WebUSB-Beschreibungs-Descriptor für die Plattformfähigkeit das Feld iLandingPage auf einen Wert ungleich 0 festgelegt ist, führt der Browser eine WebUSB-spezifische GET_URL-Anfrage aus, indem er eine Steuerübertragung mit bRequest = bVendorCode aus dem Beschreibungs-Descriptor für die Plattformfähigkeit und wValue = iLandingPage ausführt. 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 ähnelt macOS, aber bei den meisten Distributionen werden standardmäßig keine Nutzerkonten mit Berechtigung zum Öffnen von USB-Geräten eingerichtet. Ein System-Daemon namens udev ist dafür verantwortlich, dem Nutzer und der Gruppe, die auf ein Gerät zugreifen dürfen, die entsprechenden Berechtigungen zuzuweisen. Mit einer solchen Regel wird die Inhaberschaft eines Geräts, das mit den angegebenen Anbieter- und Produkt-IDs übereinstimmt, der Gruppe plugdev zugewiesen. Diese Gruppe ist eine gängige 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 gespeichert werden und tritt in Kraft, sobald das Gerät angeschlossen wird. 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 jedoch wissen, dass Nutzer bei der Verbindung zum Gerät einen zusätzlichen Schritt ausführen müssen. 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 sind unter Android mehr Geräte zugänglich als unter Linux auf dem Desktop, 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 Datei mit Treiberinformationen gibt Windows an, 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ätsbeschreibungen für Microsoft-Betriebssysteme

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 Descriptors stellen dem Windows-Betriebssystem beim ersten Anschließen des Geräts Informationen zur Verfügung, die normalerweise in der INF-Datei enthalten wären.

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 die zugehörigen Steuerübertragungen verwendet werden soll. 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 Descriptorsets, welcher Funktion die folgenden Eigenschaften 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. Der kompatible ID-Beschreibungsblock teilt Windows mit, 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 Schlagworte finden Sie im Blogpost von Microsoft.

Beispiele

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

• WebLight
• WebUSB Arduino Library