Conexión a dispositivos HID poco comunes

La API de WebHID permite que los sitios web accedan a teclados auxiliares alternativos y gamepads exóticos.

François Beaufort

Hay una cola larga de dispositivos de interfaz humana (HID), como teclados alternativos o gamepads exóticos, que son demasiado nuevos, demasiado antiguos o demasiado poco comunes para que los controladores de dispositivos de los sistemas puedan acceder a ellos. La API de WebHID resuelve este problema, ya que proporciona una manera de implementar la lógica específica del dispositivo en JavaScript.

Casos de uso sugeridos

Un dispositivo HID recibe entradas de las personas o les proporciona salidas. Algunos ejemplos de dispositivos son teclados, dispositivos de puntero (mouse, pantallas táctiles, etcétera) y controles de juegos. El protocolo HID permite acceder a estos dispositivos en computadoras de escritorio con controladores del sistema operativo. La plataforma web admite dispositivos HID gracias a estos controladores.

La incapacidad de acceder a dispositivos HID poco comunes es particularmente dolorosa cuando se trata de teclados auxiliares alternativos (p.ej., Elgato Stream Deck, auriculares Jabra, X-keys) y compatibilidad con gamepads exóticos. Los controles de juegos diseñados para computadoras de escritorio a menudo usan HID para las entradas (botones, joysticks, activadores) y salidas (luces LED, vibración) del control de juegos. Lamentablemente, las entradas y salidas de los controles de juegos no están bien estandarizadas y, a menudo, los navegadores web requieren una lógica personalizada para dispositivos específicos. Esto no es sostenible y genera una mala compatibilidad con la cola larga de dispositivos más antiguos y poco comunes. También hace que el navegador dependa de peculiaridades en el comportamiento de dispositivos específicos.

Terminología

HID consta de dos conceptos fundamentales: informes y descriptores de informes. Los informes son los datos que se intercambian entre un dispositivo y un cliente de software. El descriptor de informes describe el formato y el significado de los datos que admite el dispositivo.

Un HID (dispositivo de interfaz humana) es un tipo de dispositivo que recibe entradas de las personas o les proporciona salidas. También hace referencia al protocolo HID, un estándar para la comunicación bidireccional entre un host y un dispositivo diseñado para simplificar el procedimiento de instalación. El protocolo HID se desarrolló originalmente para dispositivos USB, pero desde entonces se implementó en muchos otros protocolos, incluido Bluetooth.

Las aplicaciones y los dispositivos HID intercambian datos binarios a través de tres tipos de informes:

Un descriptor de informe describe el formato binario de los informes que admite el dispositivo. Su estructura es jerárquica y puede agrupar informes como colecciones distintas dentro de la colección de nivel superior. La especificación HID define el formato del descriptor.

Un uso de HID es un valor numérico que hace referencia a una entrada o salida estandarizada. Los valores de uso permiten que un dispositivo describa el uso previsto del dispositivo y el propósito de cada campo en sus informes. Por ejemplo, uno se define para el botón izquierdo del mouse. Los usos también se organizan en páginas de uso, que proporcionan una indicación de la categoría de alto nivel del dispositivo o informe.

Cómo usar la API de WebHID

Detección de atributos

Para verificar si la API de WebHID es compatible, usa lo siguiente:

if ("hid" in navigator) {
  // The WebHID API is supported.
}

Cómo abrir una conexión HID

La API de WebHID es asíncrona de forma predeterminada para evitar que la IU del sitio web se bloquee cuando espera una entrada. Esto es importante porque los datos HID se pueden recibir en cualquier momento, lo que requiere una forma de escucharlos.

Para abrir una conexión HID, primero accede a un objeto HIDDevice. Para ello, puedes pedirle al usuario que seleccione un dispositivo llamando a navigator.hid.requestDevice() o elegir uno de navigator.hid.getDevices(), que muestra una lista de los dispositivos a los que se le otorgó acceso al sitio web anteriormente.

La función navigator.hid.requestDevice() toma un objeto obligatorio que define los filtros. Se usan para hacer coincidir cualquier dispositivo conectado con un identificador de proveedor USB (vendorId), un identificador de producto USB (productId), un valor de página de uso (usagePage) y un valor de uso (usage). Puedes obtenerlos del repositorio de IDs de USB y del documento de tablas de uso de HID.

Los múltiples objetos HIDDevice que muestra esta función representan varias interfaces HID en el mismo dispositivo físico.

// Filter on devices with the Nintendo Switch Joy-Con USB Vendor/Product IDs.
const filters = [
  {
    vendorId: 0x057e, // Nintendo Co., Ltd
    productId: 0x2006 // Joy-Con Left
  },
  {
    vendorId: 0x057e, // Nintendo Co., Ltd
    productId: 0x2007 // Joy-Con Right
  }
];

// Prompt user to select a Joy-Con device.
const [device] = await navigator.hid.requestDevice({ filters });

// Get all devices the user has previously granted the website access to.
const devices = await navigator.hid.getDevices();

También puedes usar la clave opcional exclusionFilters en navigator.hid.requestDevice() para excluir algunos dispositivos del selector de navegador que se sabe que funcionan mal, por ejemplo.

// Request access to a device with vendor ID 0xABCD. The device must also have
// a collection with usage page Consumer (0x000C) and usage ID Consumer
// Control (0x0001). The device with product ID 0x1234 is malfunctioning.
const [device] = await navigator.hid.requestDevice({
  filters: [{ vendorId: 0xabcd, usagePage: 0x000c, usage: 0x0001 }],
  exclusionFilters: [{ vendorId: 0xabcd, productId: 0x1234 }],
});

Un objeto HIDDevice contiene identificadores de productos y proveedores USB para la identificación de dispositivos. Su atributo collections se inicializa con una descripción jerárquica de los formatos de informes del dispositivo.

for (let collection of device.collections) {
  // An HID collection includes usage, usage page, reports, and subcollections.
  console.log(`Usage: ${collection.usage}`);
  console.log(`Usage page: ${collection.usagePage}`);

  for (let inputReport of collection.inputReports) {
    console.log(`Input report: ${inputReport.reportId}`);
    // Loop through inputReport.items
  }

  for (let outputReport of collection.outputReports) {
    console.log(`Output report: ${outputReport.reportId}`);
    // Loop through outputReport.items
  }

  for (let featureReport of collection.featureReports) {
    console.log(`Feature report: ${featureReport.reportId}`);
    // Loop through featureReport.items
  }

  // Loop through subcollections with collection.children
}

De forma predeterminada, los dispositivos HIDDevice se muestran en un estado "cerrado" y se deben abrir llamando a open() antes de que se puedan enviar o recibir datos.

// Wait for the HID connection to open before sending/receiving data.
await device.open();

Cómo recibir informes de entradas

Una vez establecida la conexión HID, puedes controlar los informes de entrada entrantes escuchando los eventos "inputreport" del dispositivo. Esos eventos contienen los datos HID como un objeto DataView (data), el dispositivo HID al que pertenece (device) y el ID de informe de 8 bits asociado con el informe de entrada (reportId).

Siguiendo con el ejemplo anterior, en el siguiente código, se muestra cómo detectar qué botón presionó el usuario en un dispositivo Joy-Con derecho para que puedas probarlo en casa.

device.addEventListener("inputreport", event => {
  const { data, device, reportId } = event;

  // Handle only the Joy-Con Right device and a specific report ID.
  if (device.productId !== 0x2007 && reportId !== 0x3f) return;

  const value = data.getUint8(0);
  if (value === 0) return;

  const someButtons = { 1: "A", 2: "X", 4: "B", 8: "Y" };
  console.log(`User pressed button ${someButtons[value]}.`);
});

Cómo enviar informes de salida

Para enviar un informe de salida a un dispositivo HID, pasa el ID de informe de 8 bits asociado con el informe de salida (reportId) y los bytes como BufferSource (data) a device.sendReport(). La promesa que se muestra se resuelve una vez que se envió el informe. Si el dispositivo HID no usa IDs de informe, establece reportId en 0.

En el siguiente ejemplo, se aplica a un dispositivo Joy-Con y se muestra cómo hacer que vibre con informes de salida.

// First, send a command to enable vibration.
// Magical bytes come from https://github.com/mzyy94/joycon-toolweb
const enableVibrationData = [1, 0, 1, 64, 64, 0, 1, 64, 64, 0x48, 0x01];
await device.sendReport(0x01, new Uint8Array(enableVibrationData));

// Then, send a command to make the Joy-Con device rumble.
// Actual bytes are available in the sample below.
const rumbleData = [ /* ... */ ];
await device.sendReport(0x10, new Uint8Array(rumbleData));

Envía y recibe informes de funciones

Los informes de funciones son el único tipo de informes de datos HID que pueden viajar en ambas direcciones. Permiten que los dispositivos y las aplicaciones HID intercambien datos HID no estandarizados. A diferencia de los informes de entrada y salida, la aplicación no recibe ni envía informes de funciones de forma periódica.

Para enviar un informe de funciones a un dispositivo HID, pasa el ID de informe de 8 bits asociado con el informe de funciones (reportId) y los bytes como un BufferSource (data) a device.sendFeatureReport(). La promesa que se muestra se resuelve una vez que se envía el informe. Si el dispositivo HID no usa IDs de informe, establece reportId en 0.

En el siguiente ejemplo, se ilustra el uso de los informes de funciones, ya que te muestra cómo solicitar un dispositivo de retroiluminación del teclado Apple, abrirlo y hacer que parpadee.

const waitFor = duration => new Promise(r => setTimeout(r, duration));

// Prompt user to select an Apple Keyboard Backlight device.
const [device] = await navigator.hid.requestDevice({
  filters: [{ vendorId: 0x05ac, usage: 0x0f, usagePage: 0xff00 }]
});

// Wait for the HID connection to open.
await device.open();

// Blink!
const reportId = 1;
for (let i = 0; i < 10; i++) {
  // Turn off
  await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
  await waitFor(100);
  // Turn on
  await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
  await waitFor(100);
}

Para recibir un informe de atributos de un dispositivo HID, pasa el ID de informe de 8 bits asociado con el informe de atributos (reportId) a device.receiveFeatureReport(). La promesa que se muestra se resuelve con un objeto DataView que contiene el contenido del informe de atributos. Si el dispositivo HID no usa IDs de informe, establece reportId en 0.

// Request feature report.
const dataView = await device.receiveFeatureReport(/* reportId= */ 1);

// Read feature report contents with dataView.getInt8(), getUint8(), etc...

Escucha la conexión y la desconexión

Cuando se le otorga permiso al sitio web para acceder a un dispositivo HID, puede recibir eventos de conexión y desconexión de forma activa escuchando eventos "connect" y "disconnect".

navigator.hid.addEventListener("connect", event => {
  // Automatically open event.device or warn user a device is available.
});

navigator.hid.addEventListener("disconnect", event => {
  // Remove |event.device| from the UI.
});

Cómo revocar el acceso a un dispositivo HID

El sitio web puede limpiar los permisos de acceso a un dispositivo HID que ya no le interesa retener llamando a forget() en la instancia de HIDDevice. Por ejemplo, en el caso de una aplicación web educativa que se usa en una computadora compartida con muchos dispositivos, una gran cantidad de permisos generados por el usuario acumulados crea una experiencia del usuario deficiente.

Si llamas a forget() en una sola instancia de HIDDevice, se revocará el acceso a todas las interfaces HID en el mismo dispositivo físico.

// Voluntarily revoke access to this HID device.
await device.forget();

Como forget() está disponible en Chrome 100 o versiones posteriores, verifica si esta función es compatible con lo siguiente:

if ("hid" in navigator && "forget" in HIDDevice.prototype) {
  // forget() is supported.
}

Sugerencias para desarrolladores

La depuración de HID en Chrome es fácil con la página interna about://device-log, en la que puedes ver todos los eventos relacionados con dispositivos HID y USB en un solo lugar.

Consulta el explorador de HID para volcar información del dispositivo HID en un formato legible por humanos. Asigna valores de uso a nombres para cada uso de HID.

En la mayoría de los sistemas Linux, los dispositivos HID se asignan con permisos de solo lectura de forma predeterminada. Para permitir que Chrome abra un dispositivo HID, deberás agregar una nueva regla de udev. Crea un archivo en /etc/udev/rules.d/50-yourdevicename.rules con el siguiente contenido:

KERNEL=="hidraw*", ATTRS{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"

En la línea anterior, [yourdevicevendor] es 057e si tu dispositivo es un Joy-Con de Nintendo Switch, por ejemplo. También se puede agregar ATTRS{idProduct} para una regla más específica. Asegúrate de que tu user sea miembro del grupo plugdev. Luego, vuelve a conectar el dispositivo.

Navegadores compatibles

La API de WebHID está disponible en todas las plataformas de computadoras (ChromeOS, Linux, macOS y Windows) en Chrome 89.

Demostraciones

Algunas demostraciones de WebHID se enumeran en web.dev/hid-examples. Ve a echar un vistazo.

Seguridad y privacidad

Los autores de la especificación diseñaron e implementaron la API de WebHID con los principios básicos definidos en Controlling Access to Powerful Web Platform Features, incluidos el control del usuario, la transparencia y la ergonomía. La capacidad de usar esta API está restringida principalmente por un modelo de permisos que otorga acceso a un solo dispositivo HID a la vez. En respuesta a una solicitud del usuario, este debe realizar pasos activos para seleccionar un dispositivo HID en particular.

Para comprender las compensaciones de seguridad, consulta la sección Consideraciones de seguridad y privacidad de la especificación de WebHID.

Además, Chrome inspecciona el uso de cada colección de nivel superior y, si una de ellas tiene un uso protegido (p.ej., un teclado o un mouse genéricos), un sitio web no podrá enviar ni recibir los informes definidos en esa colección. La lista completa de los usos protegidos está disponible públicamente.

Ten en cuenta que los dispositivos HID sensibles a la seguridad (como los dispositivos HID de FIDO que se usan para una autenticación más sólida) también están bloqueados en Chrome. Consulta los archivos lista de bloqueo de USB y lista de bloqueo de HID.

Comentarios

Al equipo de Chrome le encantaría conocer tus opiniones y experiencias con la API de WebHID.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que no funciona como se espera? ¿O faltan métodos o propiedades que necesitas para implementar tu idea?

Informa un problema de especificación en el repositorio de GitHub de la API de WebHID o agrega tus comentarios a un problema existente.

Denuncia un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente de la especificación?

Consulta Cómo informar errores de WebHID. Asegúrate de incluir la mayor cantidad de detalles posible, proporciona instrucciones simples para reproducir el error y establece Componentes en Blink>HID. Glitch es excelente para compartir reproducciones rápidas y fáciles.

Expresar apoyo

¿Piensas usar la API de WebHID? Tu apoyo público ayuda al equipo de Chrome a priorizar las funciones y les muestra a otros proveedores de navegadores lo importante que es admitirlas.

Envía un tuit a @ChromiumDev con el hashtag #WebHID y cuéntanos dónde y cómo lo usas.

Vínculos útiles

• Especificación
• Error de seguimiento
• Entrada de ChromeStatus.com
• Componente Blink: Blink>HID

Agradecimientos

Agradecemos a Matt Reynolds y Joe Medley por revisar este artículo. Foto de la Nintendo Switch roja y azul de Sara Kurfeß y foto de la laptop negra y plateada de Athul Cyriac Ajay en Unsplash.