Human Interface Device (HID) API


#1

A Human Interface Device (HID) is a type of device that takes input from or provides output to humans. It also refers to the HID protocol, a standard for bi-directional communication between a host and a device that is designed to simplify the installation procedure.

The web already supports input from HID devices. Keyboards, mice, touchscreens, and gamepads are all typically implemented using the HID protocol. However, this support relies on the operating system’s HID drivers to transform incoming HID reports into native input events. Devices that are not well supported by the generic HID driver are often inaccessible to web applications. Similarly, the outputs on most devices are also inaccessible.

This issue is particularly painful when it comes to HID gamepads. The HID standard defines many usages that are relevant for gamepads, but the mapping of these usages to physical button locations is inconsistent across manufacturers. As a result, it is almost always the case that some device-specific logic is needed. Native applications typically leave this device-specific logic to a dedicated library.

We propose an API for requesting access to HID devices using a chooser-based permission model similar to the one used for WebUSB and Web Bluetooth. The API would enable a web application to send output and feature reports to the device as well as listen for input reports. Direct access to devices using the HID protocol would allow the device-specific logic to move out of the user agent and into the application layer, enabling the use of more devices on the web and reducing the complexity of the user agent.

Please take a look at our WebHID explainer. The API is similar to the chrome.hid API and is intended to fill a similar niche.


#2

Thanks for putting this proposal together, together with the comprehensive README.

Just making a few notes/reactions/reactions… this seems to have a similarity to Web MIDI - does it exhibit potentially the same security characteristics? (i.e., can messages be sent that could cause the HID device to be misused/hijacked).

There might be some relationship in design with the Web Serial API.

If the main use case is gamepads, could we continue to improve the GamePad API instead? Are there mainstream HID devices in common use where this API would bring significant value to users?


#3

Yes, this API would have similar security characteristics to APIs like MIDI, USB, Bluetooth, and Serial that allow bidirectional communication with external devices. To mitigate the risk, we require that the device is selected from a chooser before any data can be sent or received. As an additional mitigation, we will block HID access to devices that generate trusted input events.

I would prefer to see more gamepads supported through the Gamepad API. However, the design of the API makes it difficult to support new devices as well as the long tail of less-popular devices. To support a device, the browser must be able to recognize the device’s input report format so it knows how to transform the button and axis data to match the Standard Gamepad layout. The work to add support for a device typically requires access to the device itself, relies on undocumented behavior, is difficult to test for regressions, and is unlikely to be undertaken by browser vendors for all but the most popular devices.

Some mainstream HID devices that could take advantage of WebHID:

Nintendo Switch Joy-Cons are Bluetooth HID devices and can be used on several OSes as Bluetooth gamepads. However, they typically need additional software to support the mode where two Joy-Cons are used together as one gamepad. Furthermore, Switch users are accustomed to a complex GUI-driven procedure for pairing and associating the gamepads which is not feasible to implement within the browser. Enabling the page to communicate HID directly to the devices would allow applications to provide their own association flow for unusual devices like these.

The Logitech Unifying receiver is a USB HID device that forwards input events from a wireless device but does not use the OS’s support for wireless protocols like Bluetooth. Once a wireless device is paired with the receiver, it generally does not require any device-specific logic beyond what is provided by the OS’s generic HID drivers. However, it does require some device-specific logic to initiate the pairing process. On most platforms this is provided by a native executable, but sometimes this is not possible. By enabling access to HID devices, the pairing app could be implemented as a web app. This is important on platforms like Chrome OS where the native app functionality may be difficult to access or unavailable.