Creazione di un dispositivo per WebUSB

Crea un dispositivo per sfruttare al massimo l'API WebUSB.

Questo articolo spiega come creare un dispositivo per sfruttare al meglio l'API WebUSB. Per una breve introduzione all'API, consulta Accedere a dispositivi USB sul web.

Contesto

L'Universal Serial Bus (USB) è diventato l'interfaccia fisica più comune per il collegamento delle periferiche a dispositivi informatici 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 sulla classe dei dispositivi. Si tratta di modelli generali per classi specifiche di dispositivi che i produttori possono implementare, ad esempio archiviazione, audio, video, networking e così via. Il vantaggio di queste specifiche della classe dei dispositivi è che un fornitore di sistema operativo può implementare un singolo driver in base alla specifica della classe ("driver di classe") e sarà supportato qualsiasi dispositivo che implementa questa classe. Si tratta di un grande miglioramento rispetto a ogni produttore che deve scrivere i propri driver di dispositivo.

Tuttavia, alcuni dispositivi non rientrano in una di queste classi standardizzate. Un produttore potrebbe invece scegliere di etichettare il proprio dispositivo per implementare la classe specifica del fornitore. In questo caso, il sistema operativo sceglie il driver del dispositivo da caricare in base alle informazioni fornite nel pacchetto driver del fornitore, in genere un insieme di ID fornitore e prodotto che implementano un protocollo specifico del fornitore.

Un'altra caratteristica delle porte 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 classe audio e video indipendenti che si assumono la responsabilità delle funzioni separate del dispositivo. Questa composizione 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 Human Interface (HID) ascoltando KeyboardEvents o PointerEvents oppure usando l'API Gamepad o WebHID. Proprio come non tutti i dispositivi implementano una definizione standardizzata di classe, non tutti i dispositivi implementano funzionalità che corrispondono alle API delle piattaforme web esistenti. In questo caso, l'API WebUSB può colmare questa lacuna offrendo ai siti un modo per richiedere un'interfaccia specifica del fornitore e implementare il relativo supporto direttamente dalla loro pagina.

I requisiti specifici affinché un dispositivo sia accessibile tramite WebUSB variano leggermente da piattaforma a piattaforma 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 avere già un driver che indichi l'interfaccia che la pagina vuole controllare. Potrebbe essere un driver di classe generico fornito dal fornitore del sistema operativo o un driver di dispositivo fornito dal fornitore. Poiché i dispositivi USB possono fornire più interfacce, ognuna delle quali può avere un proprio driver, è possibile creare un dispositivo per il quale alcune interfacce sono rivendicate da un driver e altre sono lasciate accessibili al browser.

Ad esempio, una tastiera USB di fascia alta potrebbe fornire un'interfaccia di classe HID che verrà rivendicata dal sottosistema di input del sistema operativo e 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 per consentire all'utente di modificare gli aspetti del comportamento del dispositivo, ad esempio chiavi macro ed effetti di illuminazione, senza installare alcun software specifico per la piattaforma. Il descrittore di configurazione di un dispositivo potrebbe avere il seguente aspetto:

Il descrittore di configurazione è costituito da più descrittori concatenati. Ciascuno inizia con i campi bLength e bDescriptorType per poter essere identificati. 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 interfaccia è un'interfaccia specifica del fornitore con due endpoint che possono essere utilizzati per inviare comandi al dispositivo e ricevere risposte.

Descrittori WebUSB

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

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

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

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

Di solito, questa richiesta viene effettuata due volte, la prima con un valore wLength sufficientemente grande in modo che l'host individui il valore del campo wTotalLength senza impegnarsi per 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 inviando un trasferimento di controllo con bRequest impostato sul valore bVendorCode dal descrittore delle funzionalità della piattaforma e wValue impostato sul valore iLandingPage. Il codice della richiesta di GET_URL (0x02) è nel formato wIndex:

Anche in questo caso, questa richiesta può essere inviata due volte per verificare prima la lunghezza del descrittore da leggere.

Considerazioni specifiche per le piattaforme

Sebbene l'API WebUSB tenti di fornire un'interfaccia coerente per l'accesso ai dispositivi USB, gli sviluppatori devono comunque essere consapevoli dei requisiti imposti alle applicazioni, ad esempio i requisiti 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 tutte 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 per aprire i dispositivi USB. Un daemon di sistema chiamato udev è responsabile dell'assegnazione dell'utente e del gruppo autorizzato ad accedere a un dispositivo. Una regola come questa assegnerà la proprietà di un dispositivo corrispondente agli ID fornitore e prodotto indicati 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 esadecimale del dispositivo, ad esempio ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" corrisponde a un telefono Nexus One. Per essere riconosciuti correttamente, questi caratteri devono essere scritti senza il consueto prefisso "0x" e contenere solo lettere minuscole. Per trovare gli ID del dispositivo, esegui lo strumento a riga di comando lsusb.

Questa regola dovrebbe essere inserita in un file nella directory /etc/udev/rules.d e avrà effetto non appena il dispositivo viene collegato. 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 sapere, tuttavia che gli utenti dovranno affrontare un passaggio aggiuntivo quando si connetteranno al dispositivo. Quando un utente seleziona un dispositivo in risposta a una chiamata al numero requestDevice(), Android mostra un messaggio che chiede se consentire a Chrome di accedervi. Questo messaggio viene visualizzato di nuovo anche se un utente torna a un sito web già autorizzato a connettersi a un dispositivo e il sito web chiama open().

Inoltre, su Android saranno accessibili più dispositivi 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, in quanto nell'SDK Android non esiste un'API per la comunicazione con un dispositivo seriale.

ChromeOS

ChromeOS è basato anche su Linux e non richiede modifiche alla configurazione del sistema. Il servizio autorizzazione_broker controlla l'accesso ai dispositivi USB e consente al browser di accedervi purché sia presente almeno un'interfaccia non rivendicata.

Windows

Il modello di driver di Windows introduce un requisito aggiuntivo. A differenza delle piattaforme riportate sopra, la possibilità di aprire un dispositivo USB da un'applicazione utente non è l'impostazione predefinita, anche se non sono stati caricati driver. È necessario invece caricare un driver speciale, WinUSB, per fornire l'interfaccia utilizzata dalle applicazioni per accedere al dispositivo. Per farlo, puoi utilizzare un file INF (driver information file) personalizzato installato sul sistema o modificare il firmware del dispositivo in modo da fornire i descrittori di compatibilità di Microsoft OS durante l'enumerazione.

File informazioni driver (INF)

Un file con le informazioni del driver indica a Windows cosa fare quando il dispositivo viene rilevato 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 alla nuova regola di installazione. Il file seguente è un esempio di base. Salvalo in un file con l'estensione .inf, modifica le sezioni contrassegnate con la "X", fai clic con il tasto destro del mouse sul file 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. L'interfaccia di ogni dispositivo deve avere un GUID per consentire a un'applicazione di trovarla e connettersi tramite l'API Windows. Utilizza il cmdlet PowerShell New-Guid o uno strumento online per generare un GUID casuale.

A scopo 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 basato sui file INF sopra è complicato perché richiede di configurare in anticipo la macchina di ogni utente. Windows 8.1 e versioni successive offrono un'alternativa grazie all'uso di descrittori USB personalizzati. Questi descrittori forniscono al sistema operativo Windows quando il dispositivo viene collegato per la prima volta e che di solito vengono inclusi nel file INF.

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

Come per i descrittori WebUSB, devi scegliere un valore bRequest da utilizzare per i trasferimenti di controllo correlati a questi descrittori. In questo esempio ho scelto 0x02. 0x07, posizionato in wIndex, è il comando per recuperare il set di descrittori del sistema operativo Microsoft 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 seguente 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 questo dispositivo è compatibile con il driver WinUSB. Il descrittore della proprietà del registro funziona in modo simile alla sezione [Dev_AddReg] dell'esempio INF precedente, impostando una proprietà del registro per 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 lo chiederà di nuovo alla successiva connessione. Microsoft ha fornito un elenco di voci del registro di dispositivi USB in cui sono descritte le voci di registro create durante l'enumerazione di un dispositivo. Durante il test, elimina le voci create per un dispositivo per forzare Windows a provare a leggere di nuovo i descrittori.

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

Esempi

In questi progetti si può trovare un codice di esempio che implementa dispositivi compatibili con WebUSB che includono sia descrittori WebUSB sia descrittori di Microsoft OS:

• WebLight
• Libreria Arduino WebUSB