Cómo compilar un dispositivo para WebUSB

Compila un dispositivo para aprovechar al máximo la API de WebUSB.

Reilly Grant

En este artículo, se explica cómo compilar un dispositivo para aprovechar al máximo la API de WebUSB. Para obtener una breve introducción a la API, consulta Cómo acceder a dispositivos USB en la Web.

Segundo plano

El bus universal en serie (USB) se convirtió en la interfaz física más común para conectar periféricos a dispositivos de procesamiento de computadoras de escritorio y móviles. Además de definir las características eléctricas del bus y un modelo general para comunicarse con un dispositivo, las especificaciones de USB incluyen un conjunto de especificaciones de clase de dispositivo. Estos son modelos generales para clases particulares de dispositivos, como almacenamiento, audio, video, redes, etc., que los fabricantes de dispositivos pueden implementar. La ventaja de estas especificaciones de clase de dispositivo es que un proveedor de sistemas operativos puede implementar un solo controlador basado en la especificación de clase (un "controlador de clase") y se admitirá cualquier dispositivo que implemente esa clase. Esta fue una gran mejora en comparación con cada fabricante que necesitaba escribir sus propios controladores de dispositivos.

Sin embargo, algunos dispositivos no se ajustan a una de estas clases de dispositivos estandarizados. En su lugar, un fabricante puede optar por etiquetar su dispositivo como implementador de la clase específica del proveedor. En este caso, el sistema operativo elige qué controlador de dispositivo cargar en función de la información proporcionada en el paquete de controladores del proveedor, por lo general, un conjunto de IDs de proveedor y producto que se sabe que implementan un protocolo específico del proveedor.

Otra característica del USB es que los dispositivos pueden proporcionar varias interfaces al host al que están conectados. Cada interfaz puede implementar una clase estandarizada o ser específica del proveedor. Cuando un sistema operativo elige los controladores correctos para controlar el dispositivo, cada interfaz puede ser reclamada por un controlador diferente. Por ejemplo, una cámara web USB suele proporcionar dos interfaces, una que implementa la clase de video USB (para la cámara) y otra que implementa la clase de audio USB (para el micrófono). El sistema operativo no carga un solo “controlador de cámara web”, sino que carga controladores independientes de clase de audio y video que se responsabilizan de las funciones independientes del dispositivo. Esta composición de clases de interfaz proporciona una mayor flexibilidad.

Conceptos básicos de API

Muchas de las clases USB estándar tienen las APIs web correspondientes. Por ejemplo, una página puede capturar video de un dispositivo de clase de video con getUserMedia() o recibir eventos de entrada de un dispositivo de clase de interfaz humana (HID) escuchando KeyboardEvents o PointerEvents, o con el Gamepad o la API de WebHID. Así como no todos los dispositivos implementan una definición de clase estandarizada, tampoco todos implementan funciones que correspondan a las APIs de plataformas web existentes. Cuando este es el caso, la API de WebUSB puede llenar esa brecha, ya que proporciona una forma para que los sitios reclamen una interfaz específica del proveedor y la implementen directamente desde su página.

Los requisitos específicos para que se pueda acceder a un dispositivo a través de WebUSB varían ligeramente de una plataforma a otra debido a las diferencias en la forma en que los sistemas operativos administran los dispositivos USB, pero el requisito básico es que un dispositivo no debería tener un controlador que reclame la interfaz que la página desea controlar. Puede ser un controlador de clase genérico que proporciona el proveedor del SO o un controlador de dispositivo que proporciona el proveedor. Como los dispositivos USB pueden proporcionar varias interfaces, cada una de las cuales puede tener su propio controlador, es posible compilar un dispositivo para el que un controlador reclame algunas interfaces y otras queden accesibles para el navegador.

Por ejemplo, un teclado USB de alta gama puede proporcionar una interfaz de clase HID que reclamará el subsistema de entrada del sistema operativo y una interfaz específica del proveedor que permanecerá disponible para WebUSB para que la use una herramienta de configuración. Esta herramienta se puede entregar en el sitio web del fabricante, lo que permite al usuario cambiar aspectos del comportamiento del dispositivo, como las teclas de macro y los efectos de iluminación, sin instalar ningún software específico de la plataforma. El descriptor de configuración de un dispositivo de este tipo se vería de la siguiente manera:

El descriptor de configuración consta de varios descriptores concatenados juntos. Cada uno comienza con los campos bLength y bDescriptorType para que se puedan identificar. La primera interfaz es una interfaz HID con un descriptor HID asociado y un solo extremo que se usa para entregar eventos de entrada al sistema operativo. La segunda interfaz es una interfaz específica del proveedor con dos extremos que se pueden usar para enviar comandos al dispositivo y recibir respuestas a cambio.

Descriptores de WebUSB

Si bien WebUSB puede funcionar con muchos dispositivos sin modificaciones de firmware, se habilita la funcionalidad adicional marcando el dispositivo con descriptores específicos que indican compatibilidad con WebUSB. Por ejemplo, puedes especificar una URL de página de destino a la que el navegador pueda dirigir al usuario cuando el dispositivo esté conectado.

El almacén de objetos de dispositivos binarios (BOS) es un concepto que se introdujo en USB 3.0, pero también se retroportó a dispositivos USB 2.0 como parte de la versión 2.1. La declaración de compatibilidad con WebUSB comienza con la inclusión del siguiente descriptor de capacidades de la plataforma en el descriptor de BOS:

El UUID de la capability de la plataforma lo identifica como un descriptor de capability de la plataforma WebUSB, que proporciona información básica sobre el dispositivo. Para que el navegador recupere más información sobre el dispositivo, usa el valor bVendorCode para enviar solicitudes adicionales al dispositivo. La única solicitud especificada actualmente es GET_URL, que muestra un descriptor de URL. Son similares a los descriptores de cadenas, pero están diseñados para codificar URLs en la menor cantidad de bytes posible. Un descriptor de URL para "https://google.com" se vería de la siguiente manera:

Cuando el dispositivo se conecta por primera vez, el navegador lee el descriptor de BOS emitiendo esta transferencia de control GET_DESCRIPTOR estándar:

Por lo general, esta solicitud se realiza dos veces: la primera vez con un wLength lo suficientemente grande para que el host descubra el valor del campo wTotalLength sin confirmar una transferencia grande y, luego, otra vez cuando se conozca la longitud completa del descriptor.

Si el descriptor de capacidades de la plataforma WebUSB tiene el campo iLandingPage configurado en un valor distinto de cero, el navegador realiza una solicitud GET_URL específica de WebUSB mediante la emisión de una transferencia de control con bRequest establecido en el valor bVendorCode del descriptor de capacidades de la plataforma y wValue establecido en el valor iLandingPage. El código de solicitud de GET_URL (0x02) se coloca en wIndex:

Una vez más, esta solicitud se puede emitir dos veces para sondear primero la longitud del descriptor que se está leyendo.

Consideraciones específicas de la plataforma

Si bien la API de WebUSB intenta proporcionar una interfaz coherente para acceder a los dispositivos USB, los desarrolladores deben conocer los requisitos que se imponen a las aplicaciones, como los requisitos de los navegadores web para acceder a los dispositivos.

macOS

No es necesario hacer nada especial en macOS. Un sitio web que usa WebUSB puede conectarse al dispositivo y reclamar cualquier interfaz que no reclame un controlador de kernel o otra aplicación.

Linux

Linux es como macOS, pero de forma predeterminada, la mayoría de las distribuciones no configuran cuentas de usuario con permiso para abrir dispositivos USB. Un daemon del sistema llamado udev es responsable de asignar el usuario y el grupo que pueden acceder a un dispositivo. Una regla como esta asignará la propiedad de un dispositivo que coincida con los IDs de proveedor y producto determinados al grupo plugdev, que es un grupo común para los usuarios con acceso a periféricos:

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

Reemplaza XXXX por los IDs de proveedor y producto hexadecimales de tu dispositivo. Por ejemplo, ATTR{idVendor}=="18d1", ATTR{idProduct}=="4e11" coincidiría con un teléfono Nexus One. Para que se reconozcan correctamente, deben escribirse sin el prefijo "0x" habitual y en minúsculas. Para encontrar los IDs de tu dispositivo, ejecuta la herramienta de línea de comandos lsusb.

Esta regla debe colocarse en un archivo del directorio /etc/udev/rules.d y se aplica en cuanto se enchufa el dispositivo. No es necesario reiniciar udev.

Android

La plataforma de Android se basa en Linux, pero no requiere ninguna modificación en la configuración del sistema. De forma predeterminada, cualquier dispositivo que no tenga un controlador integrado en el sistema operativo está disponible para el navegador. Sin embargo, los desarrolladores deben tener en cuenta que los usuarios encontrarán un paso adicional cuando se conecten al dispositivo. Una vez que un usuario selecciona un dispositivo en respuesta a una llamada a requestDevice(), Android mostrará un mensaje en el que se le preguntará si permite que Chrome acceda a él. Este mensaje también vuelve a aparecer si un usuario regresa a un sitio web que ya tiene permiso para conectarse a un dispositivo y el sitio web llama a open().

Además, se podrá acceder a más dispositivos en Android que en Linux para computadoras, ya que se incluyen menos controladores de forma predeterminada. Una omisión notable, por ejemplo, es la clase USB CDC-ACM que suelen implementar los adaptadores USB a serie, ya que no hay una API en el SDK de Android para comunicarse con un dispositivo serie.

ChromeOS

ChromeOS también se basa en Linux y no requiere ninguna modificación en la configuración del sistema. El servicio permission_broker controla el acceso a los dispositivos USB y permitirá que el navegador acceda a ellos, siempre y cuando haya al menos una interfaz sin reclamar.

Windows

El modelo de controlador de Windows introduce un requisito adicional. A diferencia de las plataformas anteriores, la capacidad de abrir un dispositivo USB desde una aplicación de usuario no es la predeterminada, incluso si no se cargó ningún controlador. En su lugar, hay un controlador especial, WinUSB, que se debe cargar para proporcionar la interfaz que usan las aplicaciones para acceder al dispositivo. Esto se puede hacer con un archivo de información del controlador (INF) personalizado instalado en el sistema o modificando el firmware del dispositivo para proporcionar los descriptores de compatibilidad del SO de Microsoft durante la enumeración.

Archivo de información del controlador (INF)

Un archivo de información del controlador le indica a Windows qué hacer cuando detecta un dispositivo por primera vez. Como el sistema del usuario ya incluye el controlador WinUSB, lo único que se necesita es que el archivo INF asocie tu ID de proveedor y producto con esta nueva regla de instalación. El siguiente archivo es un ejemplo básico. Guárdalo en un archivo con la extensión .inf, cambia las secciones marcadas con una “X” y, luego, haz clic con el botón derecho en él y elige “Instalar” en el menú contextual.

[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 sección [Dev_AddReg] configura el conjunto de DeviceInterfaceGUIDs para el dispositivo. Cada interfaz de dispositivo debe tener un GUID para que una aplicación lo encuentre y se conecte a él a través de la API de Windows. Usa el cmdlet New-Guid de PowerShell o una herramienta en línea para generar un GUID aleatorio.

Para fines de desarrollo, la herramienta Zadig proporciona una interfaz sencilla para reemplazar el controlador cargado para una interfaz USB con el controlador WinUSB.

Descriptores de compatibilidad del SO de Microsoft

El enfoque del archivo INF anterior es engorroso porque requiere configurar la máquina de cada usuario con anticipación. Windows 8.1 y versiones posteriores ofrecen una alternativa a través del uso de descriptores USB personalizados. Estos descriptores proporcionan información al sistema operativo Windows cuando se conecta el dispositivo por primera vez, que normalmente se incluiría en el archivo INF.

Una vez que hayas configurado los descriptores de WebUSB, también es fácil agregar los descriptores de compatibilidad del SO de Microsoft. Primero, extiende el descriptor de BOS con este descriptor de capacidades de plataforma adicional. Asegúrate de actualizar wTotalLength y bNumDeviceCaps para tener en cuenta este cambio.

Al igual que con los descriptores de WebUSB, debes elegir un valor bRequest que usarán las transferencias de control relacionadas con estos descriptores. En este ejemplo, elegí 0x02. 0x07, que se coloca en wIndex, es el comando para recuperar el conjunto de descriptores del SO 2.0 de Microsoft del dispositivo.

Un dispositivo USB puede tener varias funciones, por lo que la primera parte del conjunto de descriptores describe con qué función están asociadas las propiedades que siguen. En el siguiente ejemplo, se configura la interfaz 1 de un dispositivo compuesto. El descriptor le brinda al SO dos datos importantes sobre esta interfaz. El descriptor de ID compatible le indica a Windows que este dispositivo es compatible con el controlador de WinUSB. El descriptor de propiedades del registro funciona de manera similar a la sección [Dev_AddReg] del ejemplo de INF anterior, ya que establece una propiedad del registro para asignarle a esta función un GUID de interfaz de dispositivo.

Windows solo consultará esta información al dispositivo una vez. Si el dispositivo no responde con descriptores válidos, no volverá a preguntar la próxima vez que se conecte. Microsoft proporcionó una lista de entradas del registro del dispositivo USB que describe las entradas del registro creadas cuando se enumera un dispositivo. Cuando realices pruebas, borra las entradas creadas para un dispositivo para forzar a Windows a intentar leer los descriptores nuevamente.

Para obtener más información, consulta la entrada de blog de Microsoft sobre cómo usar estos descriptores.

Ejemplos

En estos proyectos, puedes encontrar código de ejemplo que implementa dispositivos compatibles con WebUSB que incluyen descriptores de WebUSB y descriptores del SO de Microsoft:

• WebLight
• Biblioteca de Arduino para WebUSB