Gerät für WebUSB erstellen

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

Reilly Grant

In diesem Artikel wird erläutert, wie Sie ein Gerät bauen können, um die Vorteile der WebUSB API Eine kurze Einführung in die API selbst findest du unter Auf USB-Geräte zugreifen im Web.

Hintergrund

Der Universal Serial Bus (USB) ist zur gängigsten physischen Schnittstelle für Peripheriegeräte mit Desktop- und Mobilgeräten verbinden. Zusätzlich zu Definition der elektrischen Eigenschaften des Busses und eines mit einem Gerät kommunizieren können, umfassen die USB-Spezifikationen eine Reihe von Geräteklassen. Spezifikationen. Dies sind allgemeine Modelle für bestimmte Geräteklassen wie wie Speicherplatz, Audio, Video, Netzwerk usw., die Gerätehersteller umsetzen. Der Vorteil dieser Spezifikationen für die Geräteklasse besteht darin, dass ein Betriebssystemanbieter kann einen einzelnen Treiber basierend auf der Klasse implementieren. -Spezifikation (ein "Klassentreiber") und jedes Gerät, das diese Klasse implementiert, unterstützt. Dies war eine große Verbesserung gegenüber jedem Hersteller, der ihre eigenen Gerätetreiber.

Einige Geräte lassen sich jedoch keiner dieser standardisierten Geräteklassen zuordnen. A kann der Hersteller sein Gerät stattdessen so kennzeichnen, anbieterspezifische Klasse zu erstellen. In diesem Fall wählt das Betriebssystem aus, basierend auf den Informationen im Treiberpaket des Anbieters. in der Regel eine Reihe von Anbieter- und Produkt-IDs, die bekanntermaßen eine eines bestimmten anbieterspezifischen Protokolls.

Eine weitere Funktion von USB besteht darin, dass Geräte mehrere Schnittstellen zur Verfügung stellen können, mit dem sie verbunden sind. Jede Schnittstelle kann entweder ein standardisierten Klassen oder anbieterspezifisch sein. Wenn ein Betriebssystem die die richtigen Treiber für das Gerät sind. Jede Schnittstelle kann von einem anderen . Eine USB-Webcam hat typischerweise zwei Schnittstellen, eine Implementierung der USB-Videoklasse (für die Kamera) und der Implementierung der USB- Audioklasse (für das Mikrofon) Das Betriebssystem lädt kein einzelnes "Webcam-Treiber" lädt stattdessen aber unabhängige Treiber für die Video- und Audioklasse. die für die separaten Funktionen des Geräts verantwortlich sind. Dieses Die Zusammensetzung von Schnittstellenklassen bietet mehr Flexibilität.

API-Grundlagen

Viele der Standard-USB-Klassen haben entsprechende Web-APIs. Beispiel: Seite kann mit getUserMedia() Videos von einem Gerät für den Videokurs aufnehmen oder Eingabeereignisse von einem Gerät der HID-Klasse (HID-Klasse) empfangen, indem Sie für KeyboardEvents oder PointerEvents oder über das Gamepad bzw. die WebHID API. Genauso wie nicht alle Geräte eine standardisierte Klassendefinition implementieren, -Geräte implementieren Funktionen, die vorhandenen Webplattform-APIs entsprechen. Wann? kann das WebUSB API diese Lücke schließen, indem es Websites die Möglichkeit bietet, eine anbieterspezifische Schnittstelle zu beanspruchen und Support dafür direkt auf ihrer Seite.

Die spezifischen Anforderungen für den Zugriff auf ein Gerät über WebUSB variieren geringfügig von Plattform zu Plattform, da die USB-Verbindung von Betriebssystemen unterschiedlich verwaltet wird. Geräte einrichten, aber die Grundvoraussetzung ist, dass ein Gerät nicht bereits eine der die gewünschte Oberfläche beansprucht. Dies kann entweder eine Generischer Klassentreiber, der vom Betriebssystemanbieter bereitgestellt wird, oder Gerätetreiber, der von Zulieferunternehmen. Da USB-Geräte mehrere Schnittstellen haben können, eigenen Treiber haben, ist es möglich, ein Gerät zu entwickeln, für das einige Schnittstellen vom Fahrer beansprucht und andere für den Browser zugänglich bleiben.

High-End-USB-Tastaturen bieten beispielsweise eine Schnittstelle der HID-Klasse, die vom Eingabesubsystem des Betriebssystems und einem anbieterspezifischen Schnittstelle, die WebUSB zur Verwendung durch ein Konfigurationstool zur Verfügung steht. Dieses kann auf der Website des Herstellers angezeigt werden, sodass Nutzende Aspekte des Geräteverhaltens, wie Makrotasten und Lichteffekte, ohne plattformspezifische Software zu installieren. Der Konfigurationsdeskriptor eines solchen Geräts würde etwa so aus:

Der Konfigurationsdeskriptor besteht aus mehreren verketteten Deskriptoren. miteinander verbinden. Jedes beginnt mit den Feldern bLength und bDescriptorType. identifiziert werden kann. Die erste Schnittstelle ist eine HID-Schnittstelle mit einem zugehörigen HID-Deskriptor und einem einzelnen Endpunkt, mit dem Eingabeereignisse an den Betriebssystem. Die zweite ist eine anbieterspezifische Schnittstelle mit zwei Endpunkte, über die Befehle an das Gerät gesendet und Antworten empfangen werden können im Gegenzug erhalten.

WebUSB-Deskriptoren

WebUSB funktioniert zwar mit vielen Geräten ohne Firmware-Änderungen, werden zusätzliche Funktionen aktiviert, indem das Gerät mit spezifischen Deskriptoren, die die Unterstützung von WebUSB angeben. Sie können beispielsweise einen Landingpage-URL, an die der Nutzer weitergeleitet werden kann, wenn das Gerät an die Stromversorgung angeschlossen ist.

</ph>

Der Binary Device Object Store (BOS) ist ein Konzept, das mit USB 3.0 eingeführt wurde, im Rahmen von Version 2.1 auch auf USB 2.0-Geräte zurückportiert. Wird deklariert beginnt die Unterstützung für WebUSB mit den folgenden Plattformfunktionen Deskriptor im BOS-Deskriptor:

Laut der UUID der Plattformfunktion ist dies ein WebUSB Platform Capability Deskriptor mit grundlegenden Informationen zum Gerät. Für den Browser , um weitere Informationen über das Gerät abzurufen, für das der Wert bVendorCode verwendet wird. zusätzliche Anfragen an das Gerät senden. Die einzige derzeit angegebene Anfrage ist GET_URL: gibt einen URL-Deskriptor zurück. Sie ähneln Zeichenfolgen verwenden. Sie sind jedoch darauf ausgelegt, URLs mit wenigen Byte zu codieren. Eine URL Deskriptor für "https://google.com" würde so aussehen:

Wenn Ihr Gerät zum ersten Mal angeschlossen wird, liest der Browser den BOS-Deskriptor, indem er Standardübertragung von GET_DESCRIPTOR-Kontrollen:

Diese Anfrage wird normalerweise zweimal gestellt, das erste Mal mit einer ausreichend großen wLength damit der Host den Wert des Felds wTotalLength erfährt, Commit für eine große Übertragung und dann erneut, wenn die vollständige Deskriptorlänge gleich bekannt sind.

Wenn im Feld iLandingPage der WebUSB-Plattformfunktionsbeschreibung der Wert einen Wert ungleich null, der der Browser dann eine WebUSB-spezifische GET_URL-Anfrage ausführt durch Ausführen einer Kontrollübertragung mit bRequest auf den Wert bVendorCode aus dem Plattformfunktionsdeskriptor und wValue auf iLandingPage festgelegt Wert. Der Anfragecode für GET_URL (0x02) lautet in wIndex:

Auch dieser Antrag kann zweimal gestellt werden, des gelesenen Deskriptors.

Plattformspezifische Überlegungen

Während die WebUSB API versucht, eine einheitliche Schnittstelle für den Zugriff auf Entwickler von USB-Geräten sollten sich dennoch über die Anforderungen wie z. B. Webbrowser-Anforderungen, um auf Geräte zugreifen zu können.

macOS

Für macOS ist nichts Besonderes erforderlich. Eine Website, die WebUSB verwendet, kann eine Verbindung zu und alle Schnittstellen beanspruchen, die nicht von einem Kernel-Treiber oder eine andere Anwendung nutzen.

Linux

Linux ist wie macOS, aber bei den meisten Distributionen wird standardmäßig Konten mit der Berechtigung zum Öffnen von USB-Geräten Ein System-Daemon namens udev ist ist für die Zuweisung des Nutzers und der Gruppe verantwortlich, die Zugriff auf ein Gerät haben. Eine Regel Dadurch wird die Eigentümerschaft eines Geräts zugewiesen, das dem angegebenen Anbieter entspricht. Produkt-IDs zur Gruppe plugdev, die eine gemeinsame Gruppe für Nutzer mit Zugriff ist an 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. z.B. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" würde einem Nexus One entsprechen Smartphone. Diese Werte müssen ohne das übliche "0x" geschrieben werden. Präfix und ausschließlich Kleinbuchstaben nicht richtig erkannt werden. Führen Sie die Befehlszeile aus, um die IDs für Ihr Gerät zu finden Tool lsusb.

Diese Regel sollte in einer Datei im Verzeichnis /etc/udev/rules.d abgelegt und wird wirksam, sobald das Gerät angeschlossen ist. Es ist kein Neustart erforderlich udev verwenden.

Android

Die Android-Plattform basiert auf Linux, erfordert jedoch keine Änderungen, Systemkonfiguration. Standardmäßig alle Geräte ohne Treiber Betriebssystem ist für den Browser verfügbar. Entwickelnde sollten wissen, dass beim Herstellen der Verbindung auf dem Gerät. Sobald ein Nutzer als Reaktion auf einen Aufruf der requestDevice() eingeben, werden Sie in Android gefragt, ob Sie dies zulassen möchten. Chrome, um darauf zuzugreifen. Diese Aufforderung erscheint auch wieder, wenn ein Nutzer zu einer Website zurückkehrt. die bereits die Berechtigung hat, sich mit einem Gerät zu verbinden, und die Website ruft auf open()

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

ChromeOS

ChromeOS basiert ebenfalls auf Linux und muss nicht geändert werden zur Systemkonfiguration. Der Dienst „permission_broker“ steuert den Zugriff auf USB Geräte und lässt den Browser darauf zugreifen, solange mindestens eine unbeanspruchte Schnittstelle.

Windows

Das Windows-Treibermodell stellt eine zusätzliche Anforderung dar. Im Gegensatz zur Plattformen über die Möglichkeit, ein USB-Gerät über eine Nutzeranwendung zu öffnen, auch wenn kein Treiber geladen ist. Stattdessen gibt es eine spezielle WinUSB-Treiber, der geladen werden muss, um die Schnittstelle Apps, mit denen auf das Gerät zugegriffen wird. Dies kann entweder mit einer benutzerdefinierten INF, die auf dem System installiert ist oder durch Ändern des Geräts für die Bereitstellung der Microsoft OS-Kompatibilitätsbeschreibungen Aufzählung.

Datei mit den Treiberinformationen (INF)

Eine Treiberinformationsdatei teilt Windows mit, was zu tun ist, wenn ein Gerät erkannt wird zum ersten Mal. Da das System des Nutzers bereits den WinUSB-Treiber enthält, Sie müssen lediglich die INF-Datei zur Verknüpfung mit Ihrem Anbieter und Ihrer Produkt-ID verwenden. mit dieser neuen Installationsregel. Die folgende Datei ist ein einfaches Beispiel. Speichern Sie es in einem mit der Erweiterung .inf, ändere die mit "X" gekennzeichneten Abschnitte und wähle dann nach rechts aus. klicke darauf und wähle „Installieren“ aus dem Kontextmenü.

[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] werden die DeviceInterfaceGUIDs für die . Jede Geräteschnittstelle muss über eine GUID verfügen, damit eine Anwendung und über die Windows API eine Verbindung herstellen. New-Guid-PowerShell verwenden Cmdlet oder einem Online-Tool, um eine zufällige GUID zu generieren.

Zu Entwicklungszwecken bietet das Zadig-Tool eine einfache Oberfläche für Ersetzen des für eine USB-Schnittstelle geladenen Treibers durch den WinUSB-Treiber

Kompatibilitätsdeskriptoren für Microsoft OS

Der obige Ansatz mit der INF-Datei ist umständlich, da er jedes Mal an das Gerät der Nutzer. Windows 8.1 und höher bietet eine Alternative mit benutzerdefinierten USB-Deskriptoren. Diese Schlagworte enthalten Informationen, an das Windows-Betriebssystem, wenn das Gerät zum ersten Mal angeschlossen wird, in der Regel in der INF-Datei enthalten.

Nachdem Sie die WebUSB-Deskriptoren eingerichtet haben, können Sie ganz einfach das Betriebssystem von Microsoft auch Kompatibilitätsdeskriptoren. Erweitern Sie zunächst den BOS-Deskriptor mit dieser Zusätzliche Beschreibung der Plattformfunktion. wTotalLength aktualisieren und bNumDeviceCaps, um dies zu berücksichtigen.

Wie bei den WebUSB-Deskriptoren musst du einen bRequest-Wert auswählen, der von steuern die Übertragungen im Zusammenhang mit diesen Deskriptoren. In diesem Beispiel habe ich 0x02 0x07 (in wIndex) ist der Befehl zum Abrufen des Microsoft OS 2.0-Deskriptor-Set vom Gerät

USB-Geräte können mehrere Funktionen haben. Der erste Teil der Beschreibung Set beschreibt, welcher Funktion die folgenden Eigenschaften zugeordnet sind. Die Im folgenden Beispiel wird die Schnittstelle 1 eines zusammengesetzten Geräts konfiguriert. Die Beschreibung gibt Informationen zu den wichtigen Informationen des Betriebssystems. Das kompatible Die ID-Beschreibung teilt Windows mit, dass das Gerät mit WinUSB kompatibel ist. . Der Eigenschaftsdeskriptor der Registry funktioniert ähnlich wie der [Dev_AddReg] des INF-Beispiels oben, wobei ein Registry-Attribut auf Weisen Sie dieser Funktion eine Geräteschnittstellen-GUID zu.

Windows fragt das Gerät nur einmal nach diesen Informationen ab. Wenn das Gerät keine gültigen Beschreibungen enthält, wird beim nächsten Mal Gerät verbunden ist. Microsoft stellt eine Liste der Einträge, die die beim Auflisten eines Geräts erstellten Registrierungseinträge beschreiben Wann? Löschen der für ein Gerät erstellten Einträge, um Windows zum Lesen zu zwingen die Deskriptoren erneut.

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

Beispiele

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

• WebLight
• WebUSB-Arduino-Bibliothek