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:

Wert Feld Beschreibung
Konfigurations-Deskriptor
0x09 bLength Größe dieses Descriptors
0x02 bDescriptorType Konfigurations-Deskriptor
0x0039 wTotalLength Gesamtlänge dieser Reihe von Deskriptoren
0x02 bNumInterfaces Anzahl der Schnittstellen
0x01 bConfigurationValue Configuration 1
0x00 iConfiguration Konfigurationsname (kein)
0b1010000 bmAttributes Eigenständig mit Strom versorgtes Gerät mit Remote-Weckfunktion
0x32 bMaxPower Die maximale Leistung wird in Schritten von 2 mA angegeben.
Interface-Deskriptor
0x09 bLength Größe dieses Descriptors
0x04 bDescriptorType Interface-Deskriptor
0x00 bInterfaceNumber Schnittstelle 0
0x00 bAlternateSetting Alternative Einstellung 0 (Standard)
0x01 bNumEndpoints 1 Endpunkt
0x03 bInterfaceClass HID-Schnittstellenklasse
0x01 bInterfaceSubClass Boot-Schnittstellenunterklasse
0x01 bInterfaceProtocol Tastatur
0x00 iInterface Schnittstellenname (keine)
HID-Deskriptor
0x09 bLength Größe dieses Descriptors
0x21 bDescriptorType HID-Deskriptor
0x0101 bcdHID HID-Version 1.1
0x00 bCountryCode Zielland der Hardware
0x01 bNumDescriptors Anzahl der HID-Klassen-Deskriptoren, die folgen sollen
0x22 bDescriptorType Berichtsdeskriptortyp
0x003F wDescriptorLength Gesamtlänge des Berichts-Descriptors
Endpunktdeskriptor
0x07 bLength Größe dieses Descriptors
0x05 bDescriptorType Endpunktdeskriptor
0b10000001 bEndpointAddress Endpunkt 1 (IN)
0b00000011 bmAttributes Unterbrechen
0x0008 wMaxPacketSize 8-Byte-Pakete
0x0A bInterval Intervall von 10 ms
Schnittstellendeskriptor
0x09 bLength Größe dieses Descriptors
0x04 bDescriptorType Interface-Deskriptor
0x01 bInterfaceNumber Schnittstelle 1
0x00 bAlternateSetting Alternative Einstellung 0 (Standard)
0x02 bNumEndpoints 2 Endpunkte
0xFF bInterfaceClass Anbieterspezifische Schnittstellenklasse
0x00 bInterfaceSubClass
0x00 bInterfaceProtocol
0x00 iInterface Schnittstellenname (kein)
Endpunktdeskriptor
0x07 bLength Größe dieses Descriptors
0x05 bDescriptorType Endpunktdeskriptor
0b10000010 bEndpointAddress Endpunkt 1 (IN)
0b00000010 bmAttributes Bulk
0x0040 wMaxPacketSize 64-Byte-Pakete
0x00 bInterval Für Bulk-Endpunkte nicht verfügbar
Endpunktdeskriptor
0x07 bLength Größe dieses Descriptors
0x05 bDescriptorType Endpunktdeskriptor
0b00000011 bEndpointAddress Endpunkt 3 (OUT)
0b00000010 bmAttributes Bulk
0x0040 wMaxPacketSize 64-Byte-Pakete
0x00 bInterval Für Bulk-Endpunkte nicht verfügbar

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.

Screenshot der WebUSB-Benachrichtigung in Chrome
WebUSB-Benachrichtigung

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:

Wert Feld Beschreibung
Binärer Objektspeicher-Deskriptor für Geräte
0x05 bLength Größe dieses Descriptors
0x0F bDescriptorType Binärer Objektspeicher-Deskriptor für Geräte
0x001D wTotalLength Gesamtlänge dieser Reihe von Deskriptoren
0x01 bNumDeviceCaps Anzahl der Gerätefunktionsdeskriptoren im BOS
WebUSB-Plattformfunktionsdeskriptor
0x18 bLength Größe dieses Descriptors
0x10 bDescriptorType Gerätefunktionsbeschreibung
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 des WebUSB-Plattformkompatibilitätsdeskriptors im Little-Endian-Format
0x0100 bcdVersion WebUSB-Beschreibungsversion 1.0
0x01 bVendorCode bRequest-Wert für WebUSB
0x01 iLandingPage URL für Landingpage

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:

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

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:

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

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:

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

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.

Wert Feld Beschreibung
Microsoft OS 2.0-Beschreibung der Plattformfunktionen
0x1C bLength Größe dieses Descriptors
0x10 bDescriptorType Gerätefunktionsbeschreibung
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äts-Descriptors im Little-Endian-Format
0x06030000 dwWindowsVersion Mindestens kompatible Windows-Version (Windows 8.1)
0x00B2 wMSOSDescriptorSetTotalLength Gesamtlänge des Descriptor-Sets
0x02 bMS_VendorCode bRequest-Wert zum Abrufen weiterer Microsoft-Deskriptoren
0x00 bAltEnumCode Gerät unterstützt keine alternative Aufzählung

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.

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 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.

Wert Feld Beschreibung
Header des Microsoft OS 2.0-Deskriptorsatzes
0x000A wLength Größe dieses Deskriptors
0x0000 wDescriptorType Deskriptor für Deskriptorsatz-Header
0x06030000 dwWindowsVersion Mindestens kompatible Windows-Version (Windows 8.1)
0x00B2 wTotalLength Gesamtlänge des Descriptor-Sets
Header für Microsoft OS 2.0-Konfigurationssubset
0x0008 wLength Größe dieses Deskriptors
0x0001 wDescriptorType Beschreibung des Headers für die Konfigurationsuntergruppe
0x00 bConfigurationValue Gilt für Konfiguration 1 (wird trotz normaler Indexierung von Konfigurationen ab 1 von 0 indexiert)
0x00 bReserved Muss auf „0“ festgelegt sein
0x00A8 wTotalLength Gesamtlänge des Teilsatzes einschließlich dieses Headers
Header für Microsoft OS 2.0-Funktionssubset
0x0008 wLength Größe dieses Deskriptors
0x0002 wDescriptorType Header-Descriptor für Funktionsuntergruppe
0x01 bFirstInterface Erste Schnittstelle der Funktion
0x00 bReserved Muss auf „0“ festgelegt sein
0x00A0 wSubsetLength Gesamtlänge des Teilsatzes einschließlich dieses Headers
Microsoft OS 2.0-kompatibler ID-Beschreibungsblock
0x0014 wLength Größe dieses Deskriptors
0x0003 wDescriptorType Beschreibung der kompatiblen ID
"WINUSB\0\0" CompatibileID ASCII-String, auf 8 Byte aufgefüllt
"\0\0\0\0\0\0\0\0" SubCompatibleID ASCII-String, auf 8 Byte aufgefüllt
Descriptor für Microsoft OS 2.0-Registrierungseigenschaften
0x0084 wLength Größe dieses Deskriptors
0x0004 wDescriptorType Registry-Attributdeskriptor
0x0007 wPropertyDataType REG_MULTI_SZ
0x002A wPropertyNameLength Länge des Property-Namens
"DeviceInterfaceGUIDs\0" PropertyName Attributname mit Nullterminator, codiert in UTF-16LE
0x0050 wPropertyDataLength Länge des Attributwerts
"{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}\0\0" PropertyData GUID plus zwei Nullterminatoren, codiert in UTF-16LE

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: