Creazione di un dispositivo per WebUSB

Crea un dispositivo per sfruttare appieno l'API WebUSB.

Reilly Grant

Questo articolo spiega come creare un dispositivo per sfruttare appieno l'API WebUSB. Per una breve introduzione all'API stessa, vedi Accedere ai dispositivi USB sul web.

Sfondo

La Universal Serial Bus (USB) è diventata l'interfaccia fisica più comune per collegare le periferiche ai computer desktop e mobili. Oltre a definire le caratteristiche elettriche del bus e un modello generale per la comunicazione con un dispositivo, le specifiche USB includono un insieme di specifiche per le classi di dispositivi. Si tratta di modelli generali per determinate classi di dispositivi, come archiviazione, audio, video, networking e così via, che i produttori di dispositivi possono implementare. Il vantaggio di queste specifiche della classe del dispositivo è che un fornitore del sistema operativo può implementare un singolo driver in base alla specifica della classe ("driver della classe") e qualsiasi dispositivo che implementa quella classe sarà supportato. Si tratta di un grande miglioramento rispetto alla necessità di ogni produttore di scrivere i propri driver di dispositivo.

Tuttavia, alcuni dispositivi non rientrano in una di queste classi di dispositivi standardizzate. Un produttore può scegliere di etichettare il proprio dispositivo come l'implementazione della classe specifica del fornitore. In questo caso il sistema operativo sceglie quale driver di dispositivo caricare in base alle informazioni fornite nel pacchetto del driver del fornitore, di solito un insieme di ID fornitore e prodotto che sono noti per l'implementazione di un particolare protocollo specifico del fornitore.

Un'altra caratteristica delle USB è che i dispositivi possono fornire più interfacce all'host a cui sono collegati. Ogni interfaccia può implementare una classe standardizzata o essere specifica del fornitore. Quando un sistema operativo sceglie i driver giusti per gestire il dispositivo, ogni interfaccia può essere richiesta da un driver diverso. 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 audio USB (per il microfono). Il sistema operativo non carica un singolo "driver della webcam", ma carica driver di classi video e audio indipendenti che si occupano delle funzioni separate del dispositivo. Questa combinazione di classi di interfaccia offre una maggiore flessibilità.

Nozioni di base sulle API

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

I requisiti specifici per l'accesso a un dispositivo tramite WebUSB variano leggermente da una piattaforma all'altra a causa delle differenze nel modo in cui i sistemi operativi gestiscono i dispositivi USB, ma il requisito di base è che un dispositivo non debba già avere un driver che rivendichi l'interfaccia che la pagina vuole controllare. Potrebbe trattarsi di un driver di classe generico fornito dal fornitore del sistema operativo o di un driver di dispositivo fornito dal fornitore. Poiché i dispositivi USB possono fornire più interfacce, ciascuna delle quali può avere il proprio driver, è possibile creare un dispositivo per cui alcune interfacce sono rivendicate da un driver e altre sono lasciate accessibili al browser.

Ad esempio, una tastiera USB di fascia alta può fornire un'interfaccia di classe HID che verrà rivendicata dal sottosistema di input del sistema operativo e da un'interfaccia specifica del fornitore 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 e consente all'utente di modificare aspetti del comportamento del dispositivo, come i tasti macro e gli effetti di illuminazione, senza installare alcun software specifico per la piattaforma. Il descrittore di configurazione di un dispositivo sarebbe simile al seguente:

Il descrittore di configurazione è costituito da più descrittori concatenati tra loro. Ognuno inizia con i campi bLength e bDescriptorType per poter essere identificato. La prima interfaccia è un'interfaccia HID con un descrittore HID associato e un singolo endpoint utilizzato per inviare eventi di input al sistema operativo. La seconda è un'interfaccia specifica del fornitore con due endpoint che possono essere utilizzati per inviare comandi al dispositivo e ricevere risposte a loro volta.

Descrittori WebUSB

Sebbene WebUSB possa funzionare con molti dispositivi senza modifiche al firmware, la funzionalità aggiuntiva viene attivata contrassegnando il dispositivo con descrittori specifici che indicano il supporto di WebUSB. Ad esempio, puoi specificare un URL della pagina di destinazione a cui il browser può indirizzare l'utente quando il dispositivo è collegato alla corrente.

.

Il Binary device Object Store (BOS) è un concetto introdotto in USB 3.0 ma è stato anche sottoposto a backporting su dispositivi USB 2.0 come parte della versione 2.1. La dichiarazione del supporto per WebUSB inizia con l'inclusione del seguente descrittore della funzionalità della piattaforma nel descrittore BOS:

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

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

Questa richiesta viene solitamente effettuata due volte, la prima volta con un valore wLength sufficientemente grande da consentire all'host di scoprire il valore del campo wTotalLength senza impegnarsi in un trasferimento di grandi dimensioni e poi di nuovo quando è nota la lunghezza completa del descrittore.

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

Anche questa richiesta può essere inviata due volte per verificare prima la lunghezza del descrittore in fase di lettura.

Considerazioni specifiche della piattaforma

Sebbene l'API WebUSB cerchi di fornire un'interfaccia coerente per l'accesso ai dispositivi USB, gli sviluppatori devono comunque essere consapevoli dei requisiti imposti su applicazioni come quelli dei browser web per accedere ai dispositivi.

macOS

Non è necessario nulla di speciale per macOS. Un sito web che utilizza WebUSB può connettersi al dispositivo e rivendicare le interfacce non rivendicate da un driver del kernel o da un'altra applicazione.

Linux

Linux è come macOS, ma per impostazione predefinita la maggior parte delle distribuzioni non configura account utente con l'autorizzazione ad aprire i dispositivi USB. Un daemon di sistema chiamato udev è responsabile dell'assegnazione dell'utente e del gruppo a cui è consentito l'accesso a un dispositivo. Una regola di questo tipo assegnerà la proprietà di un dispositivo corrispondente agli ID fornitore e prodotto specificati 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 prodotto e fornitore esadecimali del tuo dispositivo, ad esempio ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" corrisponde a uno smartphone Nexus One. Per essere riconosciuti correttamente, devono essere scritti senza il consueto prefisso "0x" e in minuscolo. Per trovare gli ID del dispositivo, esegui lo strumento a riga di comando lsusb.

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

Android

La piattaforma Android è basata su Linux, ma non richiede alcuna modifica alla configurazione del sistema. Per impostazione predefinita, qualsiasi dispositivo che non dispone di un driver integrato nel sistema operativo è disponibile per il browser. Gli sviluppatori devono tuttavia essere consapevoli che gli utenti dovranno eseguire un passaggio aggiuntivo per connettersi al dispositivo. Quando un utente seleziona un dispositivo in risposta a una chiamata a requestDevice(), Android mostra una richiesta di conferma per consentire a Chrome di accedervi. Questa richiesta viene visualizzata di nuovo anche se un utente torna su un sito web che ha già l'autorizzazione a connettersi a un dispositivo e il sito web chiama open().

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

ChromeOS

Anche ChromeOS è basato su Linux e non richiede alcuna modifica alla configurazione di sistema. Il servizio permission_broker controlla l'accesso ai dispositivi USB e consente al browser di accedervi a condizione che sia presente almeno un'interfaccia non rivendicata.

Windows

Il modello di driver Windows introduce un requisito aggiuntivo. A differenza delle piattaforme precedenti, la possibilità di aprire un dispositivo USB da un'applicazione utente non è l'impostazione predefinita, anche se non è caricato alcun driver. Esiste invece un driver speciale, WinUSB, che deve essere caricato per fornire l'interfaccia utilizzata dalle applicazioni per accedere al dispositivo. Questo può essere fatto con un file INF (File di informazioni del driver) personalizzato installato sul sistema o modificando il firmware del dispositivo per fornire i descrittori di compatibilità del sistema operativo Microsoft durante l'enumerazione.

File INF (Driver Information File)

Un file di 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 fornitore e l'ID prodotto a 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", poi fai clic con il pulsante destro del mouse 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 dispositivo. Ogni interfaccia del dispositivo deve avere un GUID affinché un'applicazione possa individuarla e connettersi tramite l'API Windows. Utilizza il cmdlet New-Guid PowerShell o uno strumento online per generare un GUID casuale.

Per scopi di sviluppo, lo strumento Zadig fornisce un'interfaccia semplice per sostituire il driver caricato per un'interfaccia USB con il driver WinUSB.

Descrittori di compatibilità del sistema operativo Microsoft

L'approccio con i file INF sopra indicato è complicato perché richiede la configurazione anticipata del computer di ogni utente. Windows 8.1 e versioni successive offrono un'alternativa tramite l'utilizzo di descrittori USB personalizzati. Questi descrittori forniscono al sistema operativo Windows informazioni che normalmente verrebbero incluse nel file INF quando il dispositivo viene collegato per la prima volta.

Una volta configurati i descrittori WebUSB, è facile aggiungere anche i descrittori di compatibilità del sistema operativo di Microsoft. Estendi prima il descrittore BOS con questo descrittore aggiuntivo della funzionalità della piattaforma. Assicurati di aggiornare wTotalLength e bNumDeviceCaps in base a questo.

Come per i descrittori WebUSB, devi scegliere un valore bRequest da utilizzare dai trasferimenti di controllo relativi a questi descrittori. In questo esempio ho scelto 0x02. 0x07, posizionato in wIndex, è il comando per recuperare il set di descrittori di Microsoft OS 2.0 dal dispositivo.

Un dispositivo USB può avere più funzioni, pertanto la prima parte dell'insieme di descrittori descrive a quale funzione sono associate le proprietà che seguono. L'esempio riportato di seguito configura l'interfaccia 1 di un dispositivo composito. Il descrittore fornisce al sistema operativo due informazioni importanti su questa interfaccia. Il descrittore ID compatibile indica a Windows che il dispositivo è compatibile con il driver WinUSB. Il descrittore della proprietà del registry funziona in modo simile alla sezione [Dev_AddReg] dell'esempio INF precedente, impostando una proprietà del registry per assegnare a questa funzione un GUID dell'interfaccia del dispositivo.

Windows eseguirà una query sul dispositivo per queste informazioni una sola volta. Se il dispositivo non risponde con descrittori validi, la richiesta non verrà ripetuta alla successiva connessione del dispositivo. Microsoft ha fornito un elenco di voci del Registro di dispositivi USB che descrivono le voci del Registro create durante l'enumerazione di un dispositivo. Durante il test, elimina le voci create per un dispositivo per forzare Windows a tentare di leggere di nuovo i descrittori.

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

Esempi

Il codice di esempio che implementa i dispositivi compatibili con WebUSB che includono sia i descrittori WebUSB sia i descrittori del sistema operativo Microsoft è disponibile in questi progetti:

• WebLight
• Libreria Arduino WebUSB