Tworzenie urządzenia na potrzeby WebUSB

Stwórz urządzenie, aby w pełni wykorzystać możliwości interfejsu WebUSB API.

Reilly Grant

Z tego artykułu dowiesz się, jak zaprojektować urządzenie, aby w pełni wykorzystać Interfejs WebUSB API. Krótkie wprowadzenie do interfejsu API znajdziesz w artykule Dostęp do urządzeń USB w internecie.

Tło

Uniwersalna magistrala szeregowa (USB) jest najpopularniejszym fizycznym interfejsem dla podłączania urządzeń peryferyjnych do komputerów stacjonarnych i urządzeń mobilnych. Oprócz określić parametry elektryczne autobusu i określić ogólny model w czasie komunikacji z urządzeniem, specyfikacje USB obejmują zestaw klasy urządzenia specyfikacji. To są ogólne modele dla określonych klas urządzeń, takich jak m.in. pamięci, dźwięku, wideo, sieci i innych funkcji. do wdrożenia. Zaletą tych specyfikacji klasy urządzeń jest to, dostawca systemu operacyjnego może wdrożyć pojedynczy sterownik na podstawie klasy („kierowca klasy”) i każde urządzenie z implementacją tej klasy obsługiwane. To była ogromna poprawa w porównaniu z każdym producentem, który musiał pisać sterowniki urządzenia.

Niektóre urządzenia nie pasują jednak do żadnej z tych standardowych klas urządzeń. O producent może zamiast tego oznaczyć swoje urządzenie jako implementujące klasy dostawcy. W tym przypadku to system operacyjny wybiera urządzenie. ładowanie sterownika w oparciu o informacje zawarte w pakiecie sterownika zwykle jest zbiorem identyfikatorów dostawcy i produktu, o których wiadomo, że implementują protokołu określonego dostawcy.

Inną cechą urządzeń USB jest możliwość połączenia z wieloma interfejsami z hostem, z którym są połączone. W każdym interfejsie możesz zaimplementować albo lub być specyficzne dla dostawcy. Gdy system operacyjny wybiera odpowiednie sterowniki do obsługi danego urządzenia mogą być deklarowane przez różne sterownika. Na przykład kamera internetowa USB ma zazwyczaj 2 interfejsy, po jednym implementuje klasę wideo USB (dla kamery) i jedno z klasą interfejsu USB zajęcia audio (dla mikrofonu). System operacyjny nie wczytuje żadnego „sterownik kamery internetowej” ale zamiast tego wczytuje niezależne sterowniki klas wideo i audio które odpowiadają za różne funkcje urządzenia. Ten klas interfejsu zapewnia większą elastyczność.

Podstawowe informacje o interfejsie API

Wiele standardowych klas USB ma odpowiednie interfejsy API. Na przykład plik strona może rejestrować film z urządzenia do lekcji wideo za pomocą narzędzia getUserMedia() lub odbierać zdarzenia wejściowe z urządzenia klasy interfejsu HID (HID) przez nasłuchiwanie dla KeyboardEvents lub PointerEvents albo Gamepad lub Interfejs API WebHID. Tak jak nie wszystkie urządzenia mają ustandaryzowaną definicję klasy, a urządzenia mają stosowanie funkcji odpowiadających istniejącym interfejsom API platformy internetowej. Kiedy Dzięki temu interfejs WebUSB API może wypełnić tę lukę, udostępniając witrynom zadeklarowanie interfejsu konkretnego dostawcy i wdrożenie jego obsługi bezpośrednio na swojej stronie.

Konkretne wymagania dotyczące dostępności urządzenia przez WebUSB nieco się od siebie różnią z powodu różnic w sposobie zarządzania USB przez systemy operacyjne urządzeń, ale podstawowym wymaganiem jest to, aby urządzenie nie miało sterownik zgłaszającego prawa do interfejsu, który ma kontrolować strona. Może to być ogólny sterownik klasy dostarczany przez dostawcę systemu operacyjnego lub sterownik urządzenia dostarczony przez od dostawcy. Urządzenia USB mogą mieć wiele interfejsów, z których każdy może ma własny sterownik, można stworzyć urządzenie, dla którego niektóre interfejsy są zgłaszane przez sterownik, a pozostałe są dostępne dla przeglądarki.

Na przykład zaawansowana klawiatura USB może mieć interfejs klasy HID, który umożliwia będzie zarezerwowany przez podsystem wejściowy systemu operacyjnego i specyficzny dla dostawcy, interfejsu, który pozostaje dostępny dla WebUSB do użycia przez narzędzie konfiguracyjne. Ten może być udostępniany w witrynie producenta, umożliwiając użytkownikowi pewnych aspektów działania urządzenia, takich jak klawisze makro i efekty świetlne, instalowanie jakichkolwiek programów specyficznych dla danej platformy. Taki deskryptor konfiguracji urządzenia wygląda mniej więcej tak:

Deskryptor konfiguracji składa się z wielu połączonych deskryptorów razem. Każdy z nich zaczyna się od pól bLength i bDescriptorType, dzięki czemu jak szybko można je zidentyfikować. Pierwszym z nich jest interfejs HID z powiązanym Deskryptor HID i pojedynczy punkt końcowy używany do dostarczania zdarzeń wejściowych do systemu operacyjnego. Drugi interfejs to interfejs specyficzny dla dostawcy, z 2 elementami punkty końcowe, które mogą być używane do wysyłania poleceń do urządzenia i odbierania odpowiedzi w zamian.

Deskryptory WebUSB

WebUSB może działać z wieloma urządzeniami bez modyfikacji oprogramowania, można włączyć dodatkowe funkcje, oznaczając urządzenie za pomocą deskryptory wskazujące obsługę WebUSB. Możesz na przykład określić parametr URL strony docelowej, na którą przeglądarka może przekierować użytkownika, gdy na podłączonym zasilaniu.

Magazyn obiektów urządzeń binarnych (BOS) to koncepcja wprowadzona w USB 3.0, również zostały przeniesione na urządzenia USB 2.0 w ramach wersji 2.1. Deklarowanie Obsługa WebUSB rozpoczyna się od uwzględnienia następującej funkcji platformy Deskryptor w deskryptorze BOS:

Identyfikator UUID funkcji platformy określa to jako obsługę platformy WebUSB deskryptor, który zawiera podstawowe informacje o urządzeniu. W przeglądarce aby pobrać więcej informacji o urządzeniu, które używa wartości bVendorCode do wysyłać dodatkowe żądania do urządzenia. Obecnie określone jest jedyne żądanie to GET_URL, który zwraca deskryptor adresu URL. Są podobne do ciągu znaków deskryptory, ale zostały zaprojektowane tak, aby kodowały adresy URL o najmniejszej liczbie bajtów. Adres URL deskryptor dla funkcji "https://google.com" będzie wyglądać tak:

Po pierwszym podłączeniu urządzenia przeglądarka odczytuje deskryptor BOS przez wykonanie tego standardowego przeniesienia kontroli GET_DESCRIPTOR:

Zwykle żądanie jest wysyłane 2 razy: za pierwszym razem z wystarczająco dużymi danymi w wLength tak by host mógł określić wartość pola wTotalLength bez zobowiązując się do wykonania dużego transferu, a potem znowu, gdy pełna długość deskryptora nieznane.

Jeśli deskryptor funkcji WebUSB ma pole iLandingPage ustawione na wartość różną od 0, a przeglądarka wykonuje następnie związane z WebUSB żądanie GET_URL przesyłając przekazanie kontroli z wartością bRequest ustawioną na bVendorCode z deskryptora możliwości platformy, a pole wValue jest ustawione na iLandingPage . Kod żądania w przypadku usługi GET_URL (0x02) wpisuje się w skrzynce wIndex:

Także w przypadku pierwszej prośby to prośba może zostać wysłana dwa razy, by najpierw sprawdzić jej długość. odczytywanego deskryptora.

Uwagi dotyczące poszczególnych platform

Wprawdzie interfejs WebUSB API stara się zapewnić spójny interfejs dostępu Programiści urządzeń USB powinni znać wymagania dotyczące urządzeń USB np. wymagania dotyczące przeglądarek.

macOS

W systemie macOS nie jest wymagane żadne specjalne działanie. Witryna korzystająca z WebUSB może połączyć się z urządzenia i zgłosić prawa do wszystkich interfejsów, które nie są zarezerwowane przez sterownik jądra, do innej aplikacji.

Linux

Linux jest jak macOS, ale domyślnie w większości dystrybucji Konta z uprawnieniami do otwierania urządzeń USB. Demon systemu o nazwie udev to odpowiada za przypisanie użytkownika i grupy z dostępem do urządzenia. Reguła na przykład przypisać własność urządzenia pasującego do danego dostawcy. identyfikatorów produktów do grupy plugdev, która jest wspólną grupą użytkowników mających dostęp do urządzeń peryferyjnych:

SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="XXXX", GROUP="plugdev"

Zastąp XXXX szesnastkowymi identyfikatorami dostawcy i produktu urządzenia. np. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" pasuje do Nexus One telefonu. Musisz je wpisywać bez zwykłego „0x”. prefiks i małe litery zostały poprawnie rozpoznane. Aby znaleźć identyfikatory swojego urządzenia, uruchom wiersz poleceń narzędzie lsusb.

Reguła ta należy umieścić w pliku w katalogu /etc/udev/rules.d zostanie zastosowany z chwilą podłączenia urządzenia do zasilania. Nie ma potrzeby ponownego uruchamiania udev.

Android

Platforma Android opiera się na Linuksie, ale nie wymaga żadnych modyfikacji, konfiguracji systemu. Domyślnie na każdym urządzeniu bez wbudowanego sterownika do systemu operacyjnego i będzie dostępna dla przeglądarki. Programiści powinni pamiętaj jednak, że użytkownicy napotkają dodatkowy krok przy próbie nawiązania połączenia urządzenia. Gdy użytkownik wybierze urządzenie w odpowiedzi na połączenie z requestDevice(), Android wyświetli pytanie o zgodę Chrome. Ta prośba pojawia się także wtedy, gdy użytkownik wróci na stronę. które ma już pozwolenie na połączenie się z urządzeniem, a strona wywołuje open()

Ponadto na urządzeniach z Androidem będzie dostępnych więcej urządzeń niż na komputerach z systemem Linux. bo domyślnie uwzględniamy mniej sterowników. Istotne pominięcie np. to klasa USB CDC-ACM powszechnie wdrażana przez adaptery USB-seryjne, w pakiecie Android SDK nie ma interfejsu API do komunikacji z urządzeniem szeregowym.

ChromeOS

ChromeOS jest oparty także na Linuksie i nie wymaga żadnych modyfikacji. do konfiguracji systemu. Usługa allow_broker kontroluje dostęp do USB urządzeń i pozwoli przeglądarce na dostęp do nich, pod warunkiem, że jest nie zgłoszono praw do interfejsu.

Windows

Model sterownika Windows wprowadza dodatkowe wymaganie. W przeciwieństwie do platformy powyżej możliwości otwarcia urządzenia USB z aplikacji użytkownika nie jest domyślnie, nawet jeśli nie ma załadowanego sterownika. Zamiast tego jest dostępny specjalny atrybut sterownika WinUSB, który musi być załadowany, aby udostępnić interfejs za pomocą których aplikacje uzyskują dostęp do urządzenia. Można to zrobić za pomocą plik informacji o sterowniku (INF) zainstalowany w systemie lub przez zmianę urządzenia co zapewnia deskryptory zgodności systemu operacyjnego Microsoft do wyliczenia.

Plik z informacjami o sterowniku (INF)

Plik z informacjami o sterowniku informuje system Windows, co ma zrobić, gdy napotka urządzenie. po raz pierwszy. Ponieważ system użytkownika zawiera już sterownik WinUSB Wystarczy, że plik INF powiąże dostawcę z identyfikatorem produktu zgodnie z nową zasadą instalacji. Poniższy przykład to podstawowy przykład. Zapisz w z rozszerzeniem .inf, zmień sekcje oznaczone symbolem „X”, a potem w prawo kliknij ją i wybierz „Zainstaluj”. w menu kontekstowym.

[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"

Sekcja [Dev_AddReg] konfiguruje zestaw identyfikatorów DeviceInterfaceGUID dla interfejsu urządzenia. Każdy interfejs urządzenia musi mieć identyfikator GUID, aby aplikacja mogła znaleźć go i połączyć z nim za pomocą interfejsu Windows API. Używanie powłoki PowerShell New-Guid za pomocą polecenia cmdlet lub narzędzia online do wygenerowania losowego identyfikatora GUID.

Do celów programistycznych narzędzie Zadig udostępnia prosty interfejs zastępując sterownik ładowany dla interfejsu USB sterownikiem WinUSB.

Deskryptory zgodności z systemem operacyjnym Microsoft

Użycie pliku INF jest niewygodne, ponieważ wymaga skonfigurowania wszystkich na komputerze użytkownika. Windows 8.1 i nowszy oferuje alternatywę za pomocą niestandardowych deskryptorów USB. Te deskryptory dostarczają informacji do systemu operacyjnego Windows po pierwszym podłączeniu urządzenia, zazwyczaj są umieszczane w pliku INF.

Po skonfigurowaniu deskryptorów WebUSB możesz łatwo dodać system operacyjny Microsoft deskryptory zgodności. Najpierw rozszerz deskryptor BOS o dodatkowego deskryptora funkcji platformy. Pamiętaj, aby zaktualizować aplikację wTotalLength i bNumDeviceCaps.

Tak jak w przypadku deskryptorów WebUSB, musisz wybrać wartość bRequest, która będzie używana przez i kontroli związane z tymi deskryptorami. W tym przykładzie wybrałem 0x02 0x07, umieszczony w wIndex, to polecenie do pobrania systemu operacyjnego Microsoft 2.0 Zestaw deskryptorów z urządzenia.

Urządzenie USB może pełnić wiele funkcji, więc pierwsza część deskryptora opisuje funkcję, z którą są powiązane poniższe właściwości. przykład poniżej konfiguruje interfejs 1 urządzenia złożonego. Deskryptor podaje dwie ważne informacje o interfejsie. Zgodny Deskryptor identyfikatora informuje system Windows, że to urządzenie jest zgodne z WinUSB sterownika. Deskryptor właściwości rejestru działa podobnie jak [Dev_AddReg] w przykładzie INF powyżej, ustawiając właściwość rejestru na przypisać tej funkcji identyfikator GUID interfejsu urządzenia.

System Windows wyśle zapytanie do urządzenia tylko raz. Jeśli urządzenie nie odpowie z użyciem prawidłowych deskryptorów, nie poprosi ponownie, gdy następnym razem urządzenie jest podłączone. Firma Microsoft udostępniła listę rejestru urządzeń USB Wpisy opisujące wpisy rejestru utworzone podczas wyliczania urządzenia. Kiedy testowanie usuń wpisy utworzone dla urządzenia, aby system Windows próbował je odczytać z deskryptorami.

Więcej informacji o korzystaniu z tych funkcji znajdziesz w poście na blogu firmy Microsoft. deskryptory.

Przykłady

Przykładowy kod implementujący urządzenia obsługujące WebUSB, które zawierają zarówno protokół WebUSB deskryptory i deskryptory systemu operacyjnego Microsoft można znaleźć w następujących projektach:

• WebLight
• Biblioteka WebUSB Arduino