Verbindung zu seltenen HID-Geräten

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

15. September 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.

Vorgeschlagene Anwendungsfälle

Ein HID-Gerät nimmt Eingaben von Menschen entgegen oder liefert ihnen eine Ausgabe. Beispiele für Geräte sind Tastaturen, Zeigegeräte (Mäuse, Touchscreens usw.) und Gamepads. das HID-Protokoll 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. Elgato Stream Cover, Jabra Kopfhörer, X-Tasten) 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.

Tatsächlicher Zustand

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

HID-Geräte und -Anwendungen tauschen Binärdaten über drei Arten von Berichten aus:

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 Der Deskriptor wird durch die HID-Spezifikation definiert.

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

Aktivierung über chrome: // flags

Um mit der WebHID-API lokal auf allen Desktop-Plattformen ohne Herkunftsnachweis-Token zu experimentieren, aktivieren Sie die Option #experimental-Web-Plattform-Funktionen Flagge an
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 Origin-Testhandbuch für Webentwickler. Um sich für diesen oder einen anderen Herkunftsnachweis anzumelden, besuchen Sie die Registrierungsseite.

Registrieren Sie sich für den Herkunftsnachweis

1. Fordern Sie einen Token an von Ihrer Herkunft.
2. Fügen Sie das Token Ihren Seiten hinzu. Es gibt zwei Möglichkeiten, dies zu tun:
   • Füge hinzu ein Ursprungsversuch Tag an die Kopfzeile jeder Seite an. Als Beispiel könnte dies so aussehen:
     
   • Wenn Sie Ihren Server konfigurieren können, können Sie das Token auch mit a . hinzufügen Origin-Trial HTTP-Header. Der resultierende Antwortheader sollte folgendermaßen aussehen:
     Origin-Trial: TOKEN_GOES_HERE

Funktionserkennung

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

wenn ("hid" im Navigator) {
}

Öffnen Sie eine HID-Verbindung

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.

Um eine HID-Verbindung herzustellen, greifen Sie zuerst auf a zu HIDDevice objeto. Para esto, puede solicitar al usuario que seleccione un dispositivo llamando
navigator.hid.requestDevice ()oder wählen Sie eine von navigator.hid.getDevices ()
que devuelve una lista de dispositivos a los que el portal web tuvo acceso previamente.

das 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 (Hersteller-ID), eine USB-Produktkennung (Produkt ID), ein Nutzungsseitenwert (usagePage) und einen Gebrauchswert (Verwendung). Puedes conseguirlos de el repositorio de ID USB y el HID-Verwendungstabellen-Dokument.

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

const filters = [
{
Hersteller-ID: 0x057e, 
Produkt ID: 0x2006 
},
{
Hersteller-ID: 0x057e, 
Produkt ID: 0x2007 
}
];

const [Gerät] = erwarten Navigator.hid.requestDevice({ filters });

const devices = erwarten Navigator.hid.getDevices();

EIN HIDDevice Das Objekt enthält USB-Hersteller- und Produktkennungen zur Geräteidentifikation. Ihr Sammlungen El atributo se inicializa con una descripción jerárquica de los formatos de reporte del dispositivo.

zum (Lassen collection of Gerät.Sammlungen) {
console.Log(`Usage: ${collection.Verwendung}`);
console.Log(`Usage page: ${collection.usagePage}`);
zum (Lassen inputReport of collection.inputReports) {
console.Log(`Input report: ${inputReport.reportId}`);
}
zum (Lassen outputReport of collection.outputReports) {
console.Log(`Output report: ${outputReport.reportId}`);
}
zum (Lassen featureReport of collection.featureReports) {
console.Log(`Feature report: ${featureReport.reportId}`);
}

}

das HIDDevice los dispositivos se devuelven de manera predeterminada en un estado «cerrado» y deben abrirse llamando open () bevor Daten gesendet oder empfangen werden können.

erwarten Gerät.open();

Eingangsberichte erhalten

Sobald die HID-Verbindung hergestellt wurde, können Sie eingehende Berichte durch Abhören verarbeiten "Eingabebericht" Geräteereignisse. Diese Ereignisse enthalten die HID-Daten wie Datenansicht ObjektDaten), das HID-Gerät, zu dem es gehört (Gerät) y el ID de reporte de 8 bits asociado con el reporte de entrada (reportId).

Wenn Sie mit dem vorherigen Beispiel fortfahren, zeigt Ihnen der folgende Code, wie Sie erkennen, welche Taste der Benutzer auf einem Joy-Con Right-Gerät gedrückt hat, damit Sie es hoffentlich zu Hause testen können.

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

Ausgehende Berichte senden

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) und Bytes wie BufferSource (Daten) bis
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 bis 0.

Das folgende Beispiel gilt für ein Joy-Con-Gerät und zeigt Ihnen, wie Sie es mit den Ausgabeberichten vibrieren lassen.

const enableVibrationData = [1, 0, 1, 64, 64, 0, 1, 64, 64, 0x48, 0x01];
erwarten Gerät.sendReport(0x01, new Uint8Array(enableVibrationData));

const rumbleData = [  ];
erwarten Gerät.sendReport(0x10, new Uint8Array(rumbleData));

Funktionsberichte senden und empfangen

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) und Bytes wie BufferSource (Daten) bis
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 bis 0.

Das folgende Beispiel veranschaulicht die Verwendung von Funktionsberichten, indem es Ihnen zeigt, wie Sie ein Hintergrundbeleuchtungsgerät für die Apple-Tastatur bestellen, öffnen und blinken lassen.

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

const [Gerät] = erwarten Navigator.hid.requestDevice({
filters: [{ Hersteller-ID: 0x05ac, Verwendung: 0x0f, usagePage: 0xff00 }]
});

erwarten Gerät.open();

const reportId = 1;
zum (Lassen ich = 0; ich < 10; ich++) {
erwarten Gerät.sendFeatureReport(reportId, Uint32Array.desde([0, 0]));
erwarten waitFor(100);
erwarten Gerät.sendFeatureReport(reportId, Uint32Array.desde([512, 0]));
erwarten 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) bis
device.receiveFeatureReport (). Das zurückgegebene Versprechen wird mit a gelöst
Datenansicht objeto que contiene el contenido del reporte de características. Si el dispositivo HID no usa ID de reporte, configure reportId bis 0.

const dataView = erwarten Gerät.receiveFeatureReport( 1);

Hören Sie die Verbindung und Trennung

Cuando el portal web tiene permiso para ingresar a un dispositivo HID, puede recibir activamente eventos de conexión y desconexión escuchando "verbinden"
y "trennen" Veranstaltungen.

Navigator.hid.addEventListener("verbinden", Veranstaltung => {
});
Navigator.hid.addEventListener("trennen", Veranstaltung => {
});

Tipps für Entwickler

Das Debuggen von HID in Chrome ist mit der Innenseite einfach. chrome://device-log
donde puede ver todos los eventos relacionados con dispositivos USB y HID en un único lugar.

Population

Einige Demos von WebHID sind unter web.dev/hid-examples aufgeführt. Schau mal rein!

Sicherheit und Privatsphäre

Los autores de especificaciones han diseñado e implementado la API de WebHID usando los principios básicos definidos en Steuern Sie den Zugriff auf leistungsstarke Funktionen der Webplattform, 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 Sicherheits- und Datenschutzaspekte Abschnitt der WebHID-Spezifikation.

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 Öffentlich verfügbar.

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 Blockliste Verfahren.

Feedback

Das Chrome-Team würde gerne Ihre Gedanken und Erfahrungen mit der WebHID-API hören.

Erzählen Sie uns etwas über das API-Design

¿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 WebHID API GitHub-Repository oder fügen Sie Ihre Gedanken zu einem bestehenden Hindernis hinzu.

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?

Einen Fehler einreichen https://new.crbug.com. Stellen Sie sicher, dass Sie so viele Details wie möglich angeben, einfache Anweisungen zum Reproduzieren des Fehlers bereitstellen und
Komponenten (bearbeiten) angepasst an Blinken> VERSTECKT. Fehler funktioniert hervorragend für das schnelle und einfache Teilen von Wiederholungen.

Unterstützung zeigen

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

Senden Sie einen Tweet an @Cromodev mit #WebHID y háganos saber dónde y cómo lo está utilizando.

Links Útiles

Vielen Dank

Dank an Matt Reynolds y Joe Medley por sus reseñas de este post. Imagen de héroe de Valentin Müller, rot und blau Nintendo Switch Bild von Sara kurfeßund ein schwarz-silbernes Laptop-Foto von Athul Cyriac Ajay auf Unsplash.