Creazione di un dispositivo per WebUSB

Crea un dispositivo per sfruttare appieno l'API WebUSB.

Reilly Grant

Questo articolo spiega come realizzare un dispositivo per sfruttare al meglio API WebUSB. Per una breve introduzione all'API, consulta la sezione Accesso a dispositivi USB sul web.

Sfondo

L'Universal Serial Bus (USB) è diventato l'interfaccia fisica più comune per collegare le periferiche ai dispositivi informatici e per dispositivi mobili. Oltre a definendo le caratteristiche elettriche dell'autobus e un modello generale per comunicano con un dispositivo, le specifiche USB includono un insieme di classi specifiche. Si tratta di modelli generali per particolari classi di dispositivi, come spazio di archiviazione, audio, video, networking ecc. che i produttori di dispositivi possono da implementare. Il vantaggio di queste specifiche delle classi di dispositivi è che il fornitore del sistema operativo può implementare un singolo driver in base alla classe specifiche (un "driver di classe") e qualsiasi dispositivo che implementa tale classe sarà supportati. Si tratta di un grande miglioramento rispetto a ogni produttore che doveva scrivere i propri driver di dispositivo.

Alcuni dispositivi, tuttavia, non rientrano in una di queste classi di dispositivi standardizzate. R il produttore può scegliere di etichettare il proprio dispositivo come l'implementazione e la classe specifica del fornitore. In questo caso è il sistema operativo a scegliere il dispositivo il conducente da caricare in base alle informazioni fornite nel pacchetto del driver del fornitore di solito un insieme di ID fornitore e prodotto che implementano un protocollo specifico del fornitore.

Un'altra caratteristica delle USB è che i dispositivi possono fornire più interfacce per l'host a cui sono connessi. Ogni interfaccia può implementare standardizzata o specifica del fornitore. Quando un sistema operativo sceglie i driver giusti per gestire il dispositivo; ciascuna interfaccia può essere conducente. Ad esempio, una webcam USB in genere fornisce due interfacce, una che implementa la classe video USB (per la videocamera) e una che implementa la classe USB audio (per il microfono). Il sistema operativo non carica "driver della webcam" ma carica driver di classe audio e video indipendenti che si assumono la responsabilità delle singole funzioni del dispositivo. Questo delle classi di interfaccia offre una maggiore flessibilità.

Nozioni di base sulle API

Molte classi USB standard hanno API web corrispondenti. Ad esempio, un pagina può acquisire video da un dispositivo di classe video utilizzando getUserMedia() o ricevere eventi di input da un dispositivo di classe Human Interface (HID) ascoltando per KeyboardEvents o PointerEvents oppure utilizzando il Gamepad o il API WebHID. Così come non tutti i dispositivi implementano una definizione di classe standardizzata, non tutti I dispositivi implementano funzionalità che corrispondono alle API delle piattaforme web esistenti. Quando In questo caso l'API WebUSB può colmare questa lacuna fornendo ai siti un modo richiedere un'interfaccia specifica del fornitore e implementarne il supporto direttamente all'interno della pagina.

I requisiti specifici per l'accessibilità di un dispositivo tramite WebUSB variano leggermente da una piattaforma all'altra a causa delle differenze nel modo in cui i sistemi operativi gestiscono le porte USB dispositivi mobili, ma il requisito di base è che un dispositivo non dovrebbe già disporre che dichiara l'interfaccia che la pagina vuole controllare. Potrebbe essere un driver di classe generico fornito dal fornitore del sistema operativo o driver di dispositivo fornito da il fornitore. I dispositivi USB possono fornire più interfacce, ognuna delle quali può avere un proprio driver, è possibile creare un dispositivo per il quale alcune interfacce vengono rivendicati da un conducente e altri vengono lasciati accessibili al browser.

Ad esempio, una tastiera USB di fascia alta può fornire un'interfaccia di classe HID verranno rivendicati dal sottosistema di input del sistema operativo e da un che rimane disponibile per WebUSB per l'utilizzo da parte di uno strumento di configurazione. Questo strumento può essere pubblicato sul sito web del produttore consentendo all'utente di modificare aspetti del comportamento del dispositivo, ad esempio i tasti macro ed effetti di luce senza installando software specifico della piattaforma. Il descrittore di configurazione di un dispositivo avrà un aspetto simile al seguente:

Il descrittore di configurazione è composto da più descrittori concatenati in sinergia. Ognuna inizia con i campi bLength e bDescriptorType in modo che identificabili. La prima interfaccia è un'interfaccia HID con un descrittore HID e un singolo endpoint utilizzato per consegnare eventi di input al un intero sistema operativo. La seconda è un'interfaccia specifica del fornitore con due endpoint che possono essere utilizzati per inviare comandi al dispositivo e ricevere risposte in cambio.

Descrittori WebUSB

Sebbene WebUSB possa funzionare con molti dispositivi senza modifiche firmware, le funzionalità aggiuntive vengono attivate contrassegnando il dispositivo con specifiche che indicano il supporto di WebUSB. Ad esempio, puoi specificare URL pagina di destinazione a cui il browser può indirizzare l'utente quando il tuo dispositivo è collegato alla corrente.

Il Binary device Object Store (BOS) è un concetto introdotto in USB 3.0 ma ha anche stato retroportato su dispositivi USB 2.0 come parte della versione 2.1. Dichiarazione il supporto per WebUSB inizia con l'inclusione delle seguenti funzionalità della piattaforma Descrittore nel descrittore BOS:

L'UUID della funzionalità della piattaforma lo identifica come Funzionalità della piattaforma WebUSB descrittore, che fornisce informazioni di base sul dispositivo. Per il browser per recuperare ulteriori informazioni sul dispositivo per cui usa il valore bVendorCode inviare richieste aggiuntive al dispositivo. L'unica richiesta attualmente specificata è GET_URL che restituisce un descrittore URL. Sono simili alle stringhe ma sono progettati per codificare gli URL con il minor numero di byte. Un URL descrittore di "https://google.com" avrà il seguente aspetto:

Quando il dispositivo viene collegato per la prima volta al browser, legge il descrittore BOS che emette questo trasferimento di controllo GET_DESCRIPTOR standard:

Questa richiesta viene generalmente effettuata due volte, la prima volta con un valore wLength sufficientemente grande in modo che l'host rilevi il valore del campo wTotalLength senza eseguendo un committente su un trasferimento di grandi dimensioni e poi di nuovo quando la lunghezza massima del descrittore noti.

Se il descrittore delle funzionalità della piattaforma WebUSB ha il campo iLandingPage impostato su un valore diverso da zero, il browser esegue quindi una richiesta GET_URL specifica per WebUSB eseguendo un trasferimento del controllo con il valore bRequest impostato sul valore bVendorCode dal descrittore della funzionalità della piattaforma e wValue impostato su iLandingPage valore. Il codice di richiesta per GET_URL (0x02) deve essere inserito in wIndex:

Anche in questo caso, questa richiesta può essere inviata due volte per verificare la durata del descrittore letto.

Considerazioni specifiche per la piattaforma

Mentre l'API WebUSB tenta di fornire un'interfaccia coerente per l'accesso Gli sviluppatori di dispositivi USB devono comunque essere a conoscenza dei requisiti imposti di applicazioni quali i requisiti dei browser web per accedere ai dispositivi.

macOS

Non è necessario nulla di speciale per macOS. Un sito web che utilizza WebUSB può collegarsi a il dispositivo e rivendicare le interfacce che non sono richieste da un driver kernel un'altra applicazione.

Linux

Linux è come macOS, ma per impostazione predefinita la maggior parte delle distribuzioni non configura account autorizzati ad aprire i dispositivi USB. Un daemon di sistema chiamato udev responsabile dell'assegnazione dell'utente e del gruppo a cui è consentito accedere a un dispositivo. Una regola come questa assegnerà la proprietà di un dispositivo corrispondente al fornitore specificato ID prodotto al gruppo plugdev, che è un gruppo comune per gli utenti con accesso alle periferiche:

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

Sostituisci XXXX con gli ID esadecimali del fornitore e del prodotto del tuo dispositivo, ad es. ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" corrisponde a un Nexus One telefono. Devono essere scritti senza il consueto valore "0x" prefisso e tutte minuscole vengano riconosciuti correttamente. Per trovare gli ID del tuo dispositivo, esegui la riga di comando strumento lsusb.

Questa regola deve essere inserita in un file nella directory /etc/udev/rules.d e hanno effetto non appena il dispositivo viene collegato. Non è necessario riavviare udev.

Android

La piattaforma Android è basata su Linux, ma non richiede alcuna modifica alle configurazione di sistema. Per impostazione predefinita, i dispositivi sprovvisti di driver integrato nel sistema operativo sono disponibili per il browser. Gli sviluppatori dovrebbero tuttavia, gli utenti dovranno eseguire un ulteriore passaggio quando si connetteranno del dispositivo. Una volta che un utente seleziona un dispositivo in risposta a una chiamata a requestDevice(), Android mostrerà un messaggio che chiede se consentire o meno Chrome per accedervi. La richiesta viene visualizzata di nuovo anche se un utente torna su un sito web. che dispone già dell'autorizzazione per connettersi a un dispositivo e alle chiamate dal sito web open()

Inoltre, saranno accessibili più dispositivi su Android che su computer Linux. perché per impostazione predefinita sono inclusi meno driver. Un'omissione notevole, ad esempio, è la classe USB CDC-ACM comunemente implementata dagli adattatori da USB a seriale non è un'API nell'SDK Android per comunicare con un dispositivo seriale.

ChromeOS

ChromeOS è basato anch'esso su Linux e non richiede alcuna modifica. alla configurazione del sistema. Il servizio permission_broker controlla l'accesso a USB dispositivi e consentirà al browser di accedervi purché ci siano almeno a un'interfaccia non rivendicata.

Windows

Il modello di driver Windows introduce un requisito aggiuntivo. A differenza del piattaforme che non consentono di aprire un dispositivo USB da un'applicazione utente non è per impostazione predefinita, anche se non è stato caricato alcun driver. C'è invece un'eccezione WinUSB, che deve essere caricato per fornire l'interfaccia utilizzate dalle applicazioni per accedere al dispositivo. Questa operazione può essere eseguita con una file con le informazioni del driver (INF) installato sul sistema o modificando il dispositivo per fornire i descrittori di compatibilità del sistema operativo Microsoft durante l'enumerazione.

File con informazioni sul conducente (INF)

Un file con le informazioni sul driver indica a Windows cosa fare quando rileva un dispositivo per la prima volta. Poiché il sistema dell'utente include già il driver WinUSB è sufficiente che il file INF associ il tuo fornitore e l'ID prodotto con questa nuova regola di installazione. Il file seguente è un esempio di base. Salvalo in un file con estensione .inf, modifica le sezioni contrassegnate con "X" e poi a destra fai clic sul pulsante e scegli "Installa" dal menu contestuale.

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

La sezione [Dev_AddReg] configura l'insieme di DeviceInterfaceGUID per il parametro dispositivo. Ogni interfaccia del dispositivo deve avere un GUID affinché un'applicazione individuarlo e connetterlo tramite l'API Windows. Utilizza New-Guid PowerShell cmdlet o uno strumento online per generare un GUID casuale.

Ai fini dello sviluppo, lo strumento Zadig offre un'interfaccia semplice per sostituendo il driver caricato per un'interfaccia USB con il driver WinUSB.

Descrittori di compatibilità del sistema operativo Microsoft

L’approccio con il file INF descritto sopra è complicato perché richiede la configurazione di ogni il computer dell'utente in anticipo. Windows 8.1 e versioni successive offrono un'alternativa tramite l'uso di descrittori USB personalizzati. Questi descrittori forniscono informazioni al sistema operativo Windows quando il dispositivo viene collegato per la prima volta. normalmente sono incluse nel file INF.

Una volta configurati i descrittori WebUSB è facile aggiungere il sistema operativo Microsoft di compatibilità. Innanzitutto, estendi il descrittore BOS con questo descrittore aggiuntivo di funzionalità della piattaforma. Assicurati di aggiornare wTotalLength e bNumDeviceCaps.

Come per i descrittori WebUSB devi scegliere un valore bRequest da utilizzare controllare i trasferimenti relativi a questi descrittori. In questo esempio ho scelto 0x02. 0x07, posizionato in wIndex, è il comando per recuperare il sistema operativo Microsoft 2.0 Descrittore impostato dal dispositivo.

Un dispositivo USB può avere più funzioni, quindi la prima parte del descrittore set descrive a quale funzione sono associate le proprietà che seguono. La L'esempio riportato di seguito configura l'interfaccia 1 di un dispositivo composito. Il descrittore fornisce due parti importanti di questa interfaccia. Il modello compatibile Il descrittore dell'ID indica a Windows che questo dispositivo è compatibile con l'interfaccia WinUSB conducente. Il descrittore della proprietà del registry funziona in modo simile Sezione [Dev_AddReg] dell'esempio INF precedente, che imposta una proprietà del registry su e assegnare a questa funzione un GUID dell'interfaccia del dispositivo.

Windows eseguirà una query sul dispositivo per ottenere queste informazioni solo una volta. Se il dispositivo non risponde con descrittori validi, non chiederà più la prossima volta dispositivo connesso. Microsoft ha fornito un elenco di registri dei dispositivi USB Voci che descrivono le voci del registro create durante l'enumerazione di un dispositivo. Quando test elimina le voci create per un dispositivo per forzare Windows a provare a leggere di nuovo i descrittori.

Per ulteriori informazioni, leggi il post del blog di Microsoft su come utilizzare questi descrittori.

Esempi

Codice di esempio che implementa dispositivi WebUSB che includono entrambi WebUSB descrittori e descrittori di Microsoft OS sono disponibili in questi progetti:

• WebLight
• Libreria Arduino WebUSB