La API de WebHID posibilita que los sitios web accedan a teclados auxiliares alternativos y gamepads exóticos.
La API de WebHID es parte del proyecto Capabilities y en este momento está en desarrollo. Esta publicación se actualizará a medida que avance la implementación.
Existe una larga lista de dispositivos de interfaz humana (HID), como teclados alternativos o gamepads exóticos, que son demasiado nuevos, demasiado antiguos o poco comunes para que los controladores de dispositivos de los sistemas puedan ingresar a ellos. La API WebHID resuelve esto proporcionando una forma de poner en práctica la lógica específica del dispositivo en JavaScript.
Casos de uso sugeridos
Un dispositivo HID toma la entrada de los seres humanos o les proporciona una salida. Ejemplos de dispositivos incluyen teclados, dispositivos señaladores (mouse, pantallas táctiles, etc.) y gamepads. los Protocolo HID hace viable ingresar a estos dispositivos en computadoras de escritorio usando controladores del sistema operativo. La plataforma web es compatible con dispositivos HID basándose en estos controladores.
La imposibilidad de ingresar a dispositivos HID poco comunes es concretamente dolorosa cuando consiste en teclados auxiliares alternativos (p. Ej. Cubierta de Elgato Stream, Auriculares Jabra, X-llaves) y soporte exótico para gamepad. Los gamepads diseñados para el escritorio a menudo utilizan HID para las entradas del gamepad (botones, joysticks, disparadores) y salidas (LED, rumble). Desafortunadamente, las entradas y salidas del gamepad no están bien estandarizadas y los navegadores web a menudo requieren una lógica personalizada para dispositivos específicos. Esto es insostenible y da como consecuencia un soporte deficiente para la larga cola de dispositivos más antiguos y poco comunes. Además hace que el navegador dependa de peculiaridades en el comportamiento de dispositivos específicos.
Estado actual
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 reporte 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 personas o proporciona salidas a ellas. Además se refiere al protocolo HID, un estándar para la comunicación bidireccional entre un host y un dispositivo que está diseñado para simplificar el proceso de instalación. El protocolo HID se desarrolló originalmente para dispositivos USB, pero desde entonces se ha implementado en muchos otros protocolos, incluido Bluetooth.
Las aplicaciones y los dispositivos HID intercambian datos binarios a través de tres tipos de informes:
| Tipo de reporte | Descripción |
|---|---|
| Reporte de entrada | Datos que se envían desde el dispositivo a la aplicación (a modo de ejemplo, se presiona un botón). |
| Reporte de salida | Datos que se envían desde la aplicación al dispositivo (a modo de ejemplo, una solicitud para encender la luz de fondo del teclado). |
| Reporte de funciones | Datos que pueden enviarse en cualquier dirección. El formato es específico del dispositivo. |
Un descriptor de reporte describe el formato binario de los informes admitidos por el dispositivo. Su estructura es jerárquica y puede agrupar informes como colecciones distintas dentro de la colección de nivel superior. los formato del descriptor está definido por la especificación HID.
Un uso de HID es un valor numérico que se refiere a una entrada o salida estandarizada. Los valores de uso posibilitan que un dispositivo describa el uso previsto del dispositivo y el propósito de cada campo en sus informes. A modo de ejemplo, se establece uno para el botón izquierdo de un mouse. Los usos además se organizan en páginas de uso, que proporcionan una indicación de la categoría de alto nivel del dispositivo o reporte.
Utilizando la API de WebHID
Habilitación a través de chrome: // flags
Para experimentar con la API de WebHID localmente en todas las plataformas de escritorio, sin un token de prueba de origen, habilite el #experimental-web-platform-features bandera en
chrome://flags.
Habilitar el apoyo durante la etapa de prueba de origen
La API de WebHID se encuentra disponible en todas las plataformas de escritorio (Chrome OS, Linux, macOS y Windows) como una prueba de origen en Chrome 86. Se espera que la prueba de origen finalice justo antes de que Chrome 89 se establezca en febrero de 2021. La API además puede habilitarse a través de una bandera.
Las pruebas de Origin le posibilitan probar nuevas funciones y otorgar comentarios sobre su usabilidad, practicidad y efectividad a la comunidad de estándares web. Para conseguir más información, consulte el Guía de pruebas de Origin para desarrolladores web. Para inscribirse en esta u otra prueba de origen, visite el página de registro.
Regístrese para la prueba de origen
- Solicita un token por tu origen.
- Agrega el token a tus páginas. Hay dos maneras de hacerlo:
- Agregar un
origin-trial<meta>etiqueta al encabezado de cada página. A modo de ejemplo, esto puede verse así:<meta http-equiv="origin-trial" content="TOKEN_GOES_HERE"> - Si puede configurar su servidor, además puede agregar el token utilizando un
Origin-TrialEncabezado HTTP. El encabezado de respuesta resultante debería verse así:Origin-Trial: TOKEN_GOES_HERE
- Agregar un
Detección de características
Para chequear si la API de WebHID es compatible, utilice:
if ("hid" in navigator) {
}Abra una conexión HID
La API de WebHID es asincrónica por diseño para evitar que la interfaz de usuario del portal web se bloquee cuando se espera una entrada. Esto es esencial debido a que los datos HID se pueden recibir en cualquier momento, lo que necesita una forma de escucharlos.
Para abrir una conexión HID, primero acceda a un HIDDevice objeto. Para esto, puede solicitar al usuario que seleccione un dispositivo llamando
navigator.hid.requestDevice()o elige uno de navigator.hid.getDevices()
que devuelve una lista de dispositivos a los que el portal web tuvo acceso previamente.
los navigator.hid.requestDevice() La función toma un objeto obligatorio que establece 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 conseguirlos de el repositorio de ID USB y el Documento de tablas de uso de HID.
El múltiple HIDDevice Los objetos devueltos por esta función representan diversos interfaces HID en el mismo dispositivo físico.
const filters = [
{
vendorId: 0x057e,
productId: 0x2006
},
{
vendorId: 0x057e,
productId: 0x2007
}
];
const [device] = await navigator.hid.requestDevice({ filters });
const devices = await navigator.hid.getDevices();
UNA HIDDevice El objeto contiene identificadores de productos y proveedores de USB para la identificación del dispositivo. Sus collections El atributo se inicializa con una descripción jerárquica de los formatos de reporte del dispositivo.
for (let collection of device.collections) {
console.log(`Usage: ${collection.usage}`);
console.log(`Usage page: ${collection.usagePage}`);for (let inputReport of collection.inputReports) {
console.log(`Input report: ${inputReport.reportId}`);
}
for (let outputReport of collection.outputReports) {
console.log(`Output report: ${outputReport.reportId}`);
}
for (let featureReport of collection.featureReports) {
console.log(`Feature report: ${featureReport.reportId}`);
}
}
los HIDDevice los dispositivos se devuelven de manera predeterminada en un estado «cerrado» y deben abrirse llamando open() antes de que se puedan enviar o recibir datos.
await device.open();Recibir informes de entrada
Una vez que se ha establecido la conexión HID, puede manejar los informes de entrada entrantes escuchando "inputreport" eventos del dispositivo. Esos eventos contienen los datos HID como DataView objetodata), el dispositivo HID al que pertenece (device) y el ID de reporte de 8 bits asociado con el reporte de entrada (reportId).
Continuando con el ejemplo anterior, el siguiente código le muestra cómo detectar qué botón ha presionado el usuario en un dispositivo Joy-Con Right para que, con suerte, pueda probarlo en casa.
device.addEventListener("inputreport", event => {
const { data, device, reportId } = event;
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]}.`);
});
Enviar informes de salida
Para enviar un reporte de salida a un dispositivo HID, pase el ID de reporte de 8 bits asociado con el reporte de salida (reportId) y bytes como BufferSource (data) a
device.sendReport(). La promesa devuelta se resuelve una vez que se ha enviado el reporte. Si el dispositivo HID no usa ID de reporte, configure reportId a 0.
El siguiente ejemplo se aplica a un dispositivo Joy-Con y le muestra cómo hacerlo vibrar con los informes de salida.
const enableVibrationData = [1, 0, 1, 64, 64, 0, 1, 64, 64, 0x48, 0x01];
await device.sendReport(0x01, new Uint8Array(enableVibrationData));
const rumbleData = [ ];
await device.sendReport(0x10, new Uint8Array(rumbleData));
Enviar y recibir informes de funciones
Los informes de características son el único tipo de informes de datos HID que pueden viajar en ambas direcciones. Posibilitan que los dispositivos y 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 características de forma regular.
Para enviar un reporte de funciones a un dispositivo HID, pase el ID de reporte de 8 bits asociado con el reporte de funciones (reportId) y bytes como BufferSource (data) a
device.sendFeatureReport(). La promesa devuelta se resuelve una vez que se ha enviado el reporte. Si el dispositivo HID no usa ID de reporte, configure reportId a 0.
El siguiente ejemplo ilustra el uso de informes de funciones mostrándole cómo solicitar un dispositivo de retroiluminación de teclado de Apple, abrirlo y hacer que parpadee.
const waitFor = duration => new Promise(r => setTimeout(r, duration));
const [device] = await navigator.hid.requestDevice({
filters: [{ vendorId: 0x05ac, usage: 0x0f, usagePage: 0xff00 }]
});
await device.open();
const reportId = 1;
for (let i = 0; i < 10; i++) {
await device.sendFeatureReport(reportId, Uint32Array.from([0, 0]));
await waitFor(100);
await device.sendFeatureReport(reportId, Uint32Array.from([512, 0]));
await waitFor(100);
}
Para recibir un reporte de funciones de un dispositivo HID, pase el ID de reporte de 8 bits asociado con el reporte de funciones (reportId) a
device.receiveFeatureReport(). La promesa devuelta se resuelve con un
DataView objeto que contiene el contenido del reporte de características. Si el dispositivo HID no usa ID de reporte, configure reportId a 0.
const dataView = await device.receiveFeatureReport( 1);Escuche la conexión y la desconexión
Cuando el portal web tiene permiso para ingresar a un dispositivo HID, puede recibir activamente eventos de conexión y desconexión escuchando "connect"
y "disconnect" eventos.
navigator.hid.addEventListener("connect", event => {
});navigator.hid.addEventListener("disconnect", event => {
});
Consejos para desarrolladores
Depurar HID en Chrome es fácil con la página interna, chrome://device-log
donde puede ver todos los eventos relacionados con dispositivos USB y HID en un único lugar.
Población
Algunas demostraciones de WebHID se enumeran en web.dev/hid-examples. ¡Ve a echar un vistazo!
Seguridad y privacidad
Los autores de especificaciones han diseñado e implementado la API de WebHID usando los principios básicos definidos en Controlar el acceso a las potentes funciones de la plataforma web, incluido el control del usuario, la transparencia y la ergonomía. La capacidad de utilizar esta API está principalmente controlada por un modelo de permisos que otorga acceso a un solo dispositivo HID a la vez. En respuesta a un mensaje de usuario, el usuario debe tomar medidas activas para elegir un dispositivo HID en particular.
Para saber las compensaciones de seguridad, consulte la Consideraciones de seguridad y privacidad sección de la especificación WebHID.
A parte de esto, Chrome inspecciona el uso de cada colección de nivel superior y si una colección de nivel superior tiene un uso protegido (.eg teclado genérico, mouse), entonces un portal web no podrá enviar ni recibir ningún reporte definido. en esa colección. El listado completa de usos protegidos es disponible públicamente.
Tenga en cuenta que los dispositivos HID sensibles a la seguridad (como los dispositivos FIDO HID utilizados para una autenticación más sólida) además están bloqueados en Chrome. Ver el lista de bloqueos expediente.
Realimentación
Al equipo de Chrome le encantaría conocer sus pensamientos y experiencias con la API de WebHID.
Cuéntanos sobre el diseño de la API
¿Puede haber algo en la API que no funcione como se esperaba? ¿O faltan métodos o propiedades que requiere para poner en práctica su idea?
Presentar un obstáculo de especificaciones en el Repositorio de GitHub de API de WebHID o agregue sus pensamientos a un obstáculo existente.
Informar un obstáculo con la implementación
¿Encontraste un error con la implementación de Chrome? ¿O la implementación es distinto de la especificación?
Presentar un error en https://new.crbug.com. Asegúrese de incluir todos los detalles que pueda, proporcione instrucciones sencillas para reproducir el error y
Componentes ajustado a Blink>HID. Falla funciona muy bien para compartir repros rápidos y fáciles.
Mostrar apoyo
¿Está pensando en usar la API de WebHID? Su apoyo público ayuda al equipo de Chrome a priorizar funciones y muestra a otros proveedores de navegadores lo importante que es brindarles soporte.
Enviar un tweet a @Cromodev con #WebHID y háganos saber dónde y cómo lo está utilizando.
Links Útiles
Agradecimientos
Gracias a Matt Reynolds y Joe Medley por sus reseñas de este post. Imagen de héroe de Valentin Müller, rojo y azul nintendo switch foto de Sara Kurfeß, y una foto de computadora portátil negra y plateada de Athul Cyriac Ajay en Unsplash.
