Gerät für WebUSB erstellen

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

Reilly Grant
Reilly Grant

In diesem Artikel wird erläutert, wie Sie ein Gerät erstellen, um die WebUSB API optimal zu nutzen. Eine kurze Einführung in die API selbst finden Sie unter Auf USB-Geräte im Web zugreifen.

Hintergrund

Der Universal Serial Bus (USB) ist die gängigste physische Schnittstelle für die Verbindung von Peripheriegeräten mit Desktop- und mobilen Computing-Geräten. Neben der Definition der elektrischen Eigenschaften des Busses und einem allgemeinen Modell für die Kommunikation mit einem Gerät enthalten USB-Spezifikationen eine Reihe von Spezifikationen für die Geräteklasse. Dies sind allgemeine Modelle für bestimmte Geräteklassen wie Speicher, Audio, Video, Netzwerke usw., die Gerätehersteller implementieren können. Der Vorteil dieser Geräteklassenspezifikationen besteht darin, dass ein Betriebssystemanbieter einen einzelnen Treiber basierend auf der Klassenspezifikation implementieren kann (einen "Klassentreiber") und jedes Gerät unterstützt wird, das diese Klasse implementiert. Das war eine große Verbesserung gegenüber allen Herstellern, die eigene Gerätetreiber entwickeln mussten.

Einige Geräte lassen sich jedoch keiner dieser standardisierten Geräteklassen zuordnen. Hersteller können stattdessen ihr Gerät so kennzeichnen, dass die anbieterspezifische Klasse implementiert wird. In diesem Fall wählt das Betriebssystem anhand der Informationen im Treiberpaket des Anbieters aus, welcher Gerätetreiber geladen werden soll. Dies sind in der Regel eine Reihe von Anbieter- und Produkt-IDs, von denen bekannt ist, dass sie ein bestimmtes anbieterspezifisches Protokoll implementieren.

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

API-Grundlagen

Viele der Standard-USB-Klassen haben entsprechende Web-APIs. Beispielsweise kann eine Seite Videos von einem Videoklassengerät mit getUserMedia() erfassen oder Eingabeereignisse von einem HID-Klassengerät (HID) empfangen. Dazu wird KeyboardEvents oder PointerEvents überwacht oder die Gamepad- oder WebHID API verwendet. Nicht alle Geräte implementieren eine standardisierte Klassendefinition. Ebenso implementieren nicht alle Geräte Funktionen, die vorhandenen Webplattform-APIs entsprechen. In diesem Fall kann die WebUSB API diese Lücke schließen. Sie bietet Websites die Möglichkeit, eine anbieterspezifische Schnittstelle zu beanspruchen und die Unterstützung dafür direkt auf ihrer Seite zu implementieren.

Die spezifischen Anforderungen für den Zugriff auf ein Gerät über WebUSB variieren von Plattform zu Plattform leicht, da Betriebssysteme USB-Geräte anders verwalten. Die grundlegende Anforderung ist jedoch, dass das Gerät nicht bereits einen Treiber haben sollte, der die Schnittstelle beansprucht, die die Seite steuern möchte. Dies kann entweder ein generischer Klassentreiber sein, der vom Betriebssystemanbieter bereitgestellt wird, oder ein Gerätetreiber, der vom Anbieter bereitgestellt wird. USB-Geräte können mehrere Schnittstellen haben, von denen jede einen eigenen Treiber haben kann. Daher ist es möglich, ein Gerät zu entwickeln, für das einige Schnittstellen von einem Treiber beansprucht werden und andere vom Browser zugänglich bleiben.

Eine High-End-USB-Tastatur kann beispielsweise eine HID-Klassenschnittstelle haben, die vom Eingabesubsystem des Betriebssystems beansprucht wird, und eine anbieterspezifische Schnittstelle, die WebUSB für die Verwendung durch ein Konfigurationstool zur Verfügung steht. Dieses Tool kann auf der Website des Herstellers bereitgestellt werden, sodass der Nutzer Aspekte des Geräteverhaltens wie Makroschlüssel und Lichteffekte ändern kann, ohne eine plattformspezifische Software installieren zu müssen. Der Konfigurationsdeskriptor eines solchen Geräts sieht in etwa so aus:

Wert Field Beschreibung
Konfigurationsdeskriptor
0x09 bLength Größe dieses Deskriptors
0x02 bDescriptorType Konfigurationsdeskriptor
0x0039 wTotalLength Gesamtlänge dieser Reihe von Schlagwörtern
0x02 bNumInterfaces Anzahl der Schnittstellen
0x01 bConfigurationValue Configuration 1
0x00 iConfiguration Konfigurationsname (kein)
0b1010000 bmAttributes Selbstbetriebenes Gerät mit Remote-Aktivierung
0x32 bMaxPower Die maximale Leistung wird in 2-mA-Schritten ausgedrückt.
Schnittstellendeskriptor
0x09 bLength Größe dieses Deskriptors
0x04 bDescriptorType Schnittstellendeskriptor
0x00 bInterfaceNumber Schnittstelle 0
0x00 bAlternateSetting Alternative Einstellung 0 (Standardeinstellung)
0x01 bNumEndpoints 1 Endpunkt
0x03 bInterfaceClass HID-Schnittstellenklasse
0x01 bInterfaceSubClass Unterklasse der Bootschnittstelle
0x01 bInterfaceProtocol Tastatur
0x00 iInterface Schnittstellenname (kein)
HID-Deskriptor
0x09 bLength Größe dieses Deskriptors
0x21 bDescriptorType HID-Deskriptor
0x0101 bcdHID HID-Version 1.1
0x00 bCountryCode Hardware-Zielland
0x01 bNumDescriptors Anzahl der HID-Klassendeskriptoren, denen gefolgt werden soll
0x22 bDescriptorType Typ des Berichtsdeskriptors
0x003F wDescriptorLength Gesamtlänge des Berichtsdeskriptors
Endpunktdeskriptor
0x07 bLength Größe dieses Deskriptors
0x05 bDescriptorType Endpunktdeskriptor
0b10000001 bEndpointAddress Endpunkt 1 (IN)
0b00000011 bmAttributes Unterbrechung
0x0008 wMaxPacketSize 8-Byte-Pakete
0x0A bInterval Intervall von 10 ms
Schnittstellendeskriptor
0x09 bLength Größe dieses Deskriptors
0x04 bDescriptorType Schnittstellendeskriptor
0x01 bInterfaceNumber Schnittstelle 1
0x00 bAlternateSetting Alternative Einstellung 0 (Standardeinstellung)
0x02 bNumEndpoints 2 Endpunkte
0xFF bInterfaceClass Anbieterspezifische Schnittstellenklasse
0x00 bInterfaceSubClass
0x00 bInterfaceProtocol
0x00 iInterface Schnittstellenname (kein)
Endpunktdeskriptor
0x07 bLength Größe dieses Deskriptors
0x05 bDescriptorType Endpunktdeskriptor
0b10000010 bEndpointAddress Endpunkt 1 (IN)
0b00000010 bmAttributes Bulk
0x0040 wMaxPacketSize 64-Byte-Pakete
0x00 bInterval Nicht zutreffend für Bulk-Endpunkte
Endpunktdeskriptor
0x07 bLength Größe dieses Deskriptors
0x05 bDescriptorType Endpunktdeskriptor
0b00000011 bEndpointAddress Endpunkt 3 (OUT)
0b00000010 bmAttributes Bulk
0x0040 wMaxPacketSize 64-Byte-Pakete
0x00 bInterval Nicht zutreffend für Bulk-Endpunkte

Der Konfigurationsdeskriptor besteht aus mehreren miteinander verketteten Deskriptoren. Jedes Feld beginnt mit den Feldern bLength und bDescriptorType, damit sie identifiziert werden können. Die erste Schnittstelle ist eine HID-Schnittstelle mit einem verknüpften HID-Deskriptor 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 funktioniert zwar mit vielen Geräten ohne Firmware-Änderungen, aber zusätzliche Funktionen werden aktiviert, wenn das Gerät mit spezifischen Deskriptoren gekennzeichnet wird, die auf die Unterstützung von WebUSB hinweisen. Sie können beispielsweise eine Landingpage-URL angeben, an die der Browser den Nutzer weiterleiten kann, wenn Ihr Gerät angeschlossen ist.

Screenshot der WebUSB-Benachrichtigung in Chrome
WebUSB-Benachrichtigung.

Der Binary Device Object Store (BOS) ist ein mit USB 3.0 eingeführtes Konzept, wurde aber im Rahmen von Version 2.1 auch auf USB 2.0-Geräte zurückportiert. Um die Unterstützung für WebUSB zu deklarieren, müssen Sie zuerst den folgenden Plattformfunktionsdeskriptor in den BOS-Deskriptor aufnehmen:

Wert Field Beschreibung
Objektspeicher-Deskriptor für Binärgeräte
0x05 bLength Größe dieses Deskriptors
0x0F bDescriptorType Objektspeicher-Deskriptor für Binärgeräte
0x001D wTotalLength Gesamtlänge dieser Reihe von Schlagwörtern
0x01 bNumDeviceCaps Anzahl der Gerätefunktionsbeschreibungen im BOS
Funktionsbeschreibung der WebUSB-Plattform
0x18 bLength Größe dieses Deskriptors
0x10 bDescriptorType Beschreibung der Gerätefunktion
0x05 bDevCapabilityType Beschreibung der Plattformfunktionen
0x00 bReserved
{0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} PlatformCapablityUUID GUID der WebUSB-Plattformfunktionsbeschreibung im Little-Endian-Format
0x0100 bcdVersion WebUSB-Deskriptor Version 1.0
0x01 bVendorCode bRequest-Wert für WebUSB
0x01 iLandingPage URL der Landingpage

Die UUID der Plattformfunktion identifiziert dies als WebUSB-Plattformfunktionsdeskriptor, der grundlegende Informationen über das Gerät liefert. 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, die einen URL-Deskriptor zurückgibt. Sie ähneln Stringdeskriptoren, sind aber darauf ausgelegt, URLs mit möglichst wenigen Byte zu codieren. Ein URL-Deskriptor für "https://google.com" würde so aussehen:

Wert Field Beschreibung
URL-Deskriptor
0x0D bLength Größe dieses Deskriptors
0x03 bDescriptorType URL-Deskriptor
0x01 bScheme https://
"google.com" URL UTF-8-codierter URL-Inhalt

Wenn das Gerät zum ersten Mal angeschlossen wird, liest der Browser den BOS-Deskriptor mit dieser standardmäßigen GET_DESCRIPTOR-Steuerungsübertragung:

bmRequestType bRequest wValue wIndex wLength Daten (Antwort)
0b10000000 0x06 0x0F00 0x0000 * BOS-Deskriptor

Diese Anfrage wird in der Regel zweimal gesendet, einmal mit einer ausreichend großen wLength, sodass der Host den Wert des Felds wTotalLength findet, ohne eine umfangreiche Übertragung durchzuführen, und noch einmal, wenn die vollständige Deskriptorlänge bekannt ist.

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

bmRequestType bRequest wValue wIndex wLength Daten (Antwort)
0b11000000 0x01 0x0001 0x0002 * URL-Deskriptor

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

Plattformspezifische Überlegungen

Obwohl die WebUSB API versucht, eine einheitliche Schnittstelle für den Zugriff auf USB-Geräte bereitzustellen, sollten Entwickler die Anforderungen für Anwendungen wie Webbrowser-Anforderungen für den Zugriff auf Geräte berücksichtigen.

macOS

Für macOS ist nichts Besonderes erforderlich. Eine Website, die WebUSB verwendet, 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 dafür verantwortlich, den Nutzer und die Gruppe zuzuweisen, die auf ein Gerät zugreifen dürfen. Mit einer solchen Regel wird der Gruppe plugdev die Inhaberschaft eines Geräts zugewiesen, das dem angegebenen Anbieter und der angegebenen Produkt-ID entspricht. 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 hexadezimale Anbieter- und Produkt-ID für Ihr Gerät. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" entspricht z. B. einem Nexus One-Smartphone. Sie müssen ohne das übliche Präfix „0x“ und nur in Kleinbuchstaben geschrieben werden, um korrekt zu erkennen. 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 wird wirksam, sobald das Gerät angeschlossen wird. Sie müssen udev nicht neu starten.

Android

Die Android-Plattform basiert auf Linux, erfordert jedoch keine Änderung der Systemkonfiguration. Standardmäßig ist jedes Gerät ohne integrierten Treiber im Betriebssystem für den Browser verfügbar. Entwickler sollten sich jedoch bewusst sein, dass Nutzer beim Verbinden mit dem Gerät auf einen zusätzlichen Schritt stoßen. Wenn ein Nutzer ein Gerät als Reaktion auf einen Aufruf von requestDevice() auswählt, wird Android in einer Meldung gefragt, ob Chrome auf das Gerät zugreifen darf. Diese Eingabeaufforderung wird auch wieder angezeigt, wenn ein Nutzer zu einer Website zurückkehrt, die bereits die Berechtigung zum Herstellen einer Verbindung mit einem Gerät hat, und die Website open() aufruft.

Außerdem sind unter Android mehr Geräte als unter Linux für den Desktop verfügbar, da standardmäßig weniger Treiber enthalten sind. Auffällig ist beispielsweise, dass die USB CDC-ACM-Klasse in der Regel von USB-zu-seriellen 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 ermöglicht dem Browser den Zugriff darauf, sofern mindestens eine nicht beanspruchte Schnittstelle vorhanden ist.

Windows

Mit dem Windows-Treibermodell wird eine zusätzliche Anforderung eingeführt. Im Gegensatz zu den oben genannten Plattformen ist die Möglichkeit, ein USB-Gerät über eine Nutzeranwendung zu öffnen, nicht die Standardeinstellung, auch wenn kein Treiber geladen ist. Stattdessen gibt es einen speziellen Treiber, WinUSB, der geladen werden muss, um die Schnittstellen bereitzustellen, die Anwendungen für den Zugriff auf das Gerät verwenden. Dazu können Sie entweder eine auf dem System installierte benutzerdefinierte Treiberinformationsdatei (INF) verwenden oder die Firmware des Geräts so ändern, dass während der Aufzählung die Microsoft OS-Kompatibilitätsdeskriptoren bereitgestellt werden.

Driver Information File (INF)

Eine Datei mit Treiberinformationen 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 in der INF-Datei lediglich der Anbieter und die Produkt-ID der neuen Installationsregel zugeordnet werden. Die folgende Datei zeigt ein einfaches Beispiel. Speichern Sie ihn in einer Datei mit der Erweiterung .inf, ändern Sie die mit „X“ gekennzeichneten Abschnitte, 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 von DeviceInterfaceGUIDs für das Gerät konfiguriert. Jede Geräteschnittstelle muss eine GUID haben, damit eine Anwendung sie finden und über die Windows API eine Verbindung dazu herstellen kann. Verwenden Sie das PowerShell-Cmdlet New-Guid oder ein Onlinetool, um eine zufällige GUID zu generieren.

Für Entwicklungszwecke bietet das Zadig-Tool eine einfache Schnittstelle, über die Sie den für eine USB-Schnittstelle geladenen Treiber einfach durch den WinUSB-Treiber ersetzen können.

Deskriptoren zur Microsoft-Betriebssystemkompatibilität

Der obige Ansatz mit der INF-Datei ist umständlich, da er den Computer jedes Nutzers im Voraus konfigurieren muss. Windows 8.1 und höher bieten eine Alternative durch die Verwendung von benutzerdefinierten USB-Deskriptoren. Diese Deskriptoren liefern Informationen für das Windows-Betriebssystem, wenn das Gerät zum ersten Mal angeschlossen wird. Diese Informationen sind normalerweise in der INF-Datei enthalten.

Sobald Sie WebUSB-Deskriptoren eingerichtet haben, können Sie ganz einfach auch die Kompatibilitätsdeskriptoren des Betriebssystems von Microsoft hinzufügen. Erweitern Sie zuerst den BOS-Deskriptor mit diesem zusätzlichen Plattformfunktionsdeskriptor. Denken Sie daran, wTotalLength und bNumDeviceCaps entsprechend zu aktualisieren.

Wert Field Beschreibung
Funktionsbeschreibung der Microsoft OS 2.0-Plattform
0x1C bLength Größe dieses Deskriptors
0x10 bDescriptorType Beschreibung der Gerätefunktion
0x05 bDevCapabilityType Beschreibung der Plattformfunktionen
0x00 bReserved
{0xDF, 0x60, 0xDD, 0xD8, 0x89, 0x45, 0xC7, 0x4C, 0x9C, 0xD2, 0x65, 0x9D, 0x9E, 0x64, 0x8A, 0x9F} PlatformCapablityUUID GUID des Microsoft OS 2.0-Plattformkompatibilitätsdeskriptors im Little-Endian-Format
0x06030000 dwWindowsVersion Kompatible Mindestversion von Windows (Windows 8.1)
0x00B2 wMSOSDescriptorSetTotalLength Gesamtlänge des Deskriptorsatzes
0x02 bMS_VendorCode bRequest-Wert zum Abrufen weiterer Microsoft-Deskriptoren
0x00 bAltEnumCode Gerät unterstützt keine alternative Aufzählung

Wie bei den WebUSB-Deskriptoren müssen Sie einen bRequest-Wert auswählen, der von den Steuerungsübertragungen dieser Deskriptoren verwendet werden soll. In diesem Beispiel habe ich 0x02 ausgewählt. 0x07 in wIndex ist der Befehl zum Abrufen des Microsoft OS 2.0-Deskriptorsatzes vom Gerät.

bmRequestType bRequest wValue wIndex wLength Daten (Antwort)
0b11000000 0x02 0x0000 0x0007 * MS OS 2.0-Deskriptorsatz

Ein USB-Gerät kann mehrere Funktionen haben. Daher beschreibt der erste Teil des Deskriptorsatzes, mit welcher Funktion die folgenden Eigenschaften verknüpft sind. Im folgenden Beispiel wird die Schnittstelle 1 eines zusammengesetzten Geräts konfiguriert. Der Deskriptor gibt dem Betriebssystem zwei wichtige Informationen zu dieser Schnittstelle. Der kompatible ID-Deskriptor teilt Windows mit, dass dieses Gerät mit dem WinUSB-Treiber kompatibel ist. Der Eigenschaftsdeskriptor der Registry funktioniert ähnlich wie der Abschnitt [Dev_AddReg] des obigen INF-Beispiels. Dabei wird eine Registrierungseigenschaft festgelegt, um dieser Funktion eine Geräteschnittstellen-GUID zuzuweisen.

Wert Field Beschreibung
Microsoft OS 2.0-Deskriptorsatz-Header
0x000A wLength Größe dieses Deskriptors
0x0000 wDescriptorType Header-Deskriptor für Deskriptorsatz
0x06030000 dwWindowsVersion Kompatible Mindestversion von Windows (Windows 8.1)
0x00B2 wTotalLength Gesamtlänge des Deskriptorsatzes
Header für Microsoft OS 2.0-Konfigurationsteil
0x0008 wLength Größe dieses Deskriptors
0x0001 wDescriptorType Konfigurations-Teil-Header-Absatz
0x00 bConfigurationValue Gilt für Konfiguration 1 (indexiert von 0, obwohl Konfigurationen normalerweise von 1 indexiert werden)
0x00 bReserved Muss auf 0 festgelegt sein
0x00A8 wTotalLength Gesamtlänge der Teilmenge einschließlich dieser Überschrift
Microsoft OS 2.0-Funktions-Teilüberschrift
0x0008 wLength Größe dieses Deskriptors
0x0002 wDescriptorType Header-Deskriptor der Funktion-Teilmenge
0x01 bFirstInterface Erste Schnittstelle der Funktion
0x00 bReserved Muss auf 0 festgelegt sein
0x00A0 wSubsetLength Gesamtlänge der Teilmenge einschließlich dieser Überschrift
Mit Microsoft OS 2.0 kompatibler ID-Deskriptor
0x0014 wLength Größe dieses Deskriptors
0x0003 wDescriptorType Kompatible ID-Deskriptor
"WINUSB\0\0" CompatibileID ASCII-String mit Auffüllung auf 8 Byte
"\0\0\0\0\0\0\0\0" SubCompatibleID ASCII-String mit Auffüllung auf 8 Byte
Eigenschaftsdeskriptor für die Microsoft OS 2.0-Registrierung
0x0084 wLength Größe dieses Deskriptors
0x0004 wDescriptorType Attributdeskriptor der Registry
0x0007 wPropertyDataType REG_MULTI_SZ
0x002A wPropertyNameLength Länge des Property-Namens
"DeviceInterfaceGUIDs\0" PropertyName Attributname mit Null-Abschlusszeichen, codiert in UTF-16LE
0x0050 wPropertyDataLength Länge des Eigenschaftswerts
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" PropertyData GUID plus zwei Null-Terminatoren, die in UTF-16LE codiert sind

Windows fragt das Gerät nur einmal nach diesen Informationen ab. Wenn das Gerät keine gültigen Deskriptoren zurückgibt, wird beim nächsten Verbinden des Geräts nicht noch einmal gefragt. Microsoft hat eine Liste der USB-Geräteregistrierungseinträge bereitgestellt, in denen die Registrierungseinträge beschrieben sind, die beim Aufzählen eines Geräts erstellt wurden. Löschen Sie beim Testen die für ein Gerät erstellten Einträge, damit Windows noch einmal versucht, die Deskriptoren zu lesen.

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

Beispiele

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