Connexion à des appareils HID rares

La API de WebHID posibilita que los sitios la toile accedan a teclados auxiliares alternativos y gamepads exóticos.

15 septembre 2020

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.

Cas d'utilisation suggérés

Un périphérique HID prend les entrées des humains ou leur fournit une sortie. Des exemples d'appareils incluent les claviers, les dispositifs de pointage (souris, écrans tactiles, etc.) et les manettes de jeu. Les Protocole 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. Couverture Elgato Stream, Écouteurs Jabra, Touches X) 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 navigateurs 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 le navigateur dependa de peculiaridades en el comportamiento de dispositivos específicos.

État actuel

Terminologie

HID consta de dos conceptos fundamentales: informes y descriptores de informes. Los informes son los datos que se intercambian entre un dispositivo y un client de Logiciel. 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 gens 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.

Les appareils et applications HID échangent des données binaires via trois types de rapports:

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 Format Le descripteur est défini par la spécification 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

Activation via chrome: // flags

Pour expérimenter l'API WebHID localement sur toutes les plates-formes de bureau, sans jeton de preuve d'origine, activez le #experimental-web-platform-features drapeau sur
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 Guide de test d'origine pour les développeurs Web. Pour vous inscrire à cette preuve d'origine ou à toute autre preuve d'origine, visitez le page d'inscription.

Inscrivez-vous pour obtenir une preuve d'origine

1. Demander un jeton par votre origine.
2. Ajoutez le jeton à vos pages. Il y a deux façons de le faire:
   • Ajouter un origine-procès etiqueta al encabezado de cada página. A modo de ejemplo, esto puede verse así:
     
   • Si puede configurar su serveur, además puede agregar el token utilizando un Essai d'origine Encabezado HTTP. El encabezado de respuesta resultante debería verse así:
     Essai d'origine: TOKEN_GOES_HERE

Détection des fonctionnalités

Para chequear si la API de WebHID es compatible, utilice:

si ("hid" dans navigateur) {
}

Ouvrez une connexion HID

La API de WebHID es asincrónica por diseño para evitar que la interface utilisateur 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.

Pour ouvrir une connexion HID, accédez d'abord à un HIDDevice objeto. Para esto, puede solicitar al Nom d'utilisateur que seleccione un dispositivo llamando
navigator.hid.requestDevice ()ou choisissez l'un des navigator.hid.getDevices ()
que devuelve una lista de dispositivos a los que el portal web tuvo acceso previamente.

Les navigator.hid.requestDevice () La función toma un objeto obligatorio que establece les filtres. Se usan para hacer coincidir cualquier dispositivo conectado con un identificador de proveedor USB (fournisseur ID), un identifiant de produit USB (productId), une valeur de page d'utilisation (usagePage) et une valeur d'usage (usage). Puedes conseguirlos de el repositorio de ID USB y el Document sur les tables d'utilisation HID.

Le multiple HIDDevice Los objetos devueltos por esta función representan diversos interfaces HID en el mismo dispositivo físico.

const filters = [
{
fournisseur ID: 0x057e, 
productId: 0x2006 
},
{
fournisseur ID: 0x057e, 
productId: 0x2007 
}
];

const [appareil] = attendre navigateur.hid.requestDevice({ filters });

const devices = attendre navigateur.hid.getDevices();

ONGLE HIDDevice L'objet contient des identifiants de fournisseur et de produit USB pour l'identification de l'appareil. Leur collections le attribut se inicializa con una descripción jerárquica de los formatos de reporte del dispositivo.

pour (laisser collection of appareil.collections) {
console.Journal(`Usage: ${collection.usage}`);
console.Journal(`Usage page: ${collection.usagePage}`);
pour (laisser inputReport of collection.inputReports) {
console.Journal(`Input report: ${inputReport.reportId}`);
}
pour (laisser outputReport of collection.outputReports) {
console.Journal(`Output report: ${outputReport.reportId}`);
}
pour (laisser featureReport of collection.featureReports) {
console.Journal(`Feature report: ${featureReport.reportId}`);
}

}

Les HIDDevice los dispositivos se devuelven de manera predeterminada en un estado «cerrado» y deben abrirse llamando ouvert () avant que les données puissent être envoyées ou reçues.

attendre appareil.open();

Recevoir des rapports d'entrée

Une fois la connexion HID établie, vous pouvez gérer les rapports entrants en écoutant "inputreport" événements de l'appareil. Ces événements contiennent les données HID comme DataView objetLes données), le périphérique HID auquel il appartient (appareil) y el ID de reporte de 8 bits asociado con el reporte de entrada (reportId).

En continuant avec l'exemple précédent, le code suivant vous montre comment détecter le bouton sur lequel l'utilisateur a appuyé sur un appareil Joy-Con Right afin que vous puissiez, espérons-le, le tester à la maison.

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]}.`);
});

Envoyer des rapports sortants

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) et des octets comme BufferSource (Les données) à
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 à 0.

L'exemple suivant s'applique à un appareil Joy-Con et vous montre comment le faire vibrer avec les rapports de sortie.

const enableVibrationData = [1, 0, 1, 64, 64, 0, 1, 64, 64, 0x48, 0x01];
attendre appareil.sendReport(0x01, new Uint8Array(enableVibrationData));

const rumbleData = [  ];
attendre appareil.sendReport(0x10, new Uint8Array(rumbleData));

Envoyer et recevoir des rapports de fonction

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) et des octets comme BufferSource (Les données) à
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 à 0.

L'exemple suivant illustre l'utilisation des rapports de fonctionnalités en vous montrant comment commander un appareil de rétroéclairage de clavier Apple, l'ouvrir et le faire clignoter.

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

const [appareil] = attendre navigateur.hid.requestDevice({
filters: [{ fournisseur ID: 0x05ac, usage: 0x0f, usagePage: 0xff00 }]
});

attendre appareil.open();

const reportId = 1;
pour (laisser je = 0; je < 10; je++) {
attendre appareil.sendFeatureReport(reportId, Uint32Array.desde([0, 0]));
attendre waitFor(100);
attendre appareil.sendFeatureReport(reportId, Uint32Array.desde([512, 0]));
attendre 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) à
device.receiveFeatureReport (). La promesse retournée est résolue avec un
DataView objeto que contiene el Contenu del reporte de características. Si el dispositivo HID no usa ID de reporte, configure reportId à 0.

const dataView = attendre appareil.receiveFeatureReport( 1);

Écoutez la connexion et la déconnexion

Cuando el portal web tiene permiso para ingresar a un dispositivo HID, puede recibir activamente eventos de conexión y desconexión escuchando "relier"
y "déconnecter" événements.

navigateur.hid.addEventListener("relier", un événement => {
});
navigateur.hid.addEventListener("déconnecter", un événement => {
});

Conseils aux développeurs

Le débogage HID dans Chrome est facile avec la page intérieure, chrome://device-log
donde puede ver todos los eventos relacionados con dispositivos USB y HID en un único lugar.

Ville

Certaines démos de WebHID sont répertoriées sur web.dev/hid-examples. Allez jeter un œil!

Sécurité et confidentialité

Los autores de especificaciones han diseñado e implementado la API de WebHID usando los principios básicos definidos en Contrôlez l'accès aux fonctionnalités puissantes de la plate-forme 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 Considérations de sécurité et de confidentialité section de la spécification 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 publiquement.

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 liste de blocage Record.

Retour

L'équipe Chrome aimerait connaître vos impressions et vos expériences avec l'API WebHID.

Parlez-nous de la conception de l'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 Dépôt GitHub de l'API 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?

Signaler un bogue dans https://new.crbug.com. Assurez-vous d'inclure autant de détails que possible, de fournir des instructions simples pour reproduire le bogue, et
Composants (modifier) ajusté à Clignoter> HID. Échec fonctionne très bien pour un partage rapide et facile des répétitions.

Montrez votre soutien

¿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.

Envoyer un tweeter à @Cromodev avec #WebHID y háganos saber dónde y cómo lo está utilizando.

Links Útiles

Merci

Grâce à Matt Reynolds y Joe medley por sus reseñas de este Publier. Image de héros de Valentin Müller, photo de commutateur nintendo rouge et bleu de Sara Kurfeß, et une photo d'ordinateur portable noir et argent de Athul Cyriac Ajay sur Unsplash.