Erstellen Sie ein Gerät, um die WebUSB API optimal zu nutzen.
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.
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: