WebHID API

Draft Community Group Report

Latest published version:
https://www.w3.org/TR/webhid/
Latest editor's draft:
https://wicg.github.io/webhid/
Editor:
Matt Reynolds (Google)
Participate:
GitHub WICG/webhid
File an issue
Commit history
Pull requests

Abstract

This document describes an API for providing access to devices that support the Human Interface Device (HID) protocol.

Status of This Document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

GitHub Issues are preferred for discussion of this specification.

1. Introduction

This section is non-normative.

A HID (Human Interface Device) 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 HID protocol was originally developed for USB devices but has since been implemented over many other protocols, including Bluetooth.

The web platform already supports input from many HID devices. Keyboards, pointing devices, and gamepads are all typically implemented using the HID protocol. However, this support relies on the operating system's HID drivers that transform the HID input into high-level input APIs. Devices that are not well supported by the host's HID driver are often inaccessible to web pages. Similarly, the outputs on most devices that are not supported by the host's HID driver are inaccessible.

See also the related Explainer document.

2. Motivating Applications

This section is non-normative.

2.1 Niche devices

The most common classes of HID input devices are already well-supported on the web platform through existing high-level input APIs. For instance, mouse input is accessible through PointerEvent and keyboard input is accessible through KeyboardEvent. Input from these devices is handled using the host's native HID driver and typically does not require device-specific drivers or configuration to work correctly. WebHID is not intended for devices like these that are already well-supported through high-level input APIs.

For some classes of HID devices, the web platform supports some features of the device but limits access to other features. For instance, [GAMEPAD] supports the input capabilities of most game controllers but does not support less common capabilities like LED indicators or audio. These features are often not well-supported by host APIs and adding support within the user agent can lead to significant complexity. WebHID would give applications an alternative when the functionality provided by the high-level API is incomplete.

Many HID devices are not supported through any web platform API. The HID specification describes a wide array of devices that could be supported through HID, including virtual reality controls, flight simulators, medical equipment, and more. WebHID would allow these devices to be used without requiring additional drivers or modification to the user agent.

2.2 Prototyping, hobbyists, and educational devices

HID is attractive for prototyping and hobbyist applications because it allows devices to use the host's generic HID driver instead of requiring a driver for each host where the device will be used. The simplified installation procedure also makes it easier for educators to deploy a device to a classroom of students without modifying the system configuration on each host. Providing access to HID devices through the web platform would further reduce installation requirements, particularly for devices that are currently only supported through host-specific applications.

3. Security and Privacy Considerations

This section is non-normative.

3.1 Abusing Access to a Device

HID peripherals may expose powerful functionality that should not be made accessible to the page without explicit consent from the user. For instance, a HID peripheral may have sensors that allow it to collect information about its surroundings. A device may store private information that should not be revealed or overwritten. Many devices expose functionality that allow the device firmware to be upgraded. Operating systems typically do not restrict access to HID devices from applications, and this access can occasionally be abused to damage the device or corrupt the data stored on it.

In some cases, a device may expose functionality that should not be accessible at all from a web page. Specific devices may be blocked by recognizing the device by its vendor ID and product ID and hiding such devices during enumeration. The report descriptor allows a device to describe its own capabilities, and this information can be used to block classes of devices even when the vendor ID and product ID cannot be known in advance. This can be accomplished by inspecting the HID usage values assigned to collections within the report descriptor; for instance, access to keyboard-like devices can be denied by denying access to devices that include a top-level collection with the HID usage for a keyboard.

To mitigate abuse, a device will not be made available to the page until the user has granted explicit access. Access must first be requested by the page and will be granted once the user has selected the device from a chooser displaying all available devices. Once a page has been granted access, an indicator will be displayed to indicate the device is in use.

3.2 Attacking a Device

The HID protocol is extremely versatile, and a wide variety of devices have been designed that take advantage of this versatility. As a result, there are many possibilities for how access to a device could allow a malicious page to damage the device itself. It is relatively common for HID peripherals to allow firmware updates to be sent using custom HID reports. Device manufacturers must take care to design the firmware upgrade mechanism to verify that the firmware binary is authentic, and should also protect against downgrades that could reduce the security of a device. Untrusted upgrades could be used to add new capabilities to a device or cause it to masquerade as an entirely different type of device.

Some devices may be damaged when inputs are provided outside of the expected range. For instance, the rumble feature on a gamepad could become damaged if a page sends an invalid rumble command.

In general, these types of attacks are device-specific and cannot be mitigated at the API level.

3.3 Attacking the Host

If a malicious page gains access to a device, in some cases this access can be used to attack the host. A major concern is whether the device can be used to generate trusted input events. These events serve as a proxy for user intent and can be used to access more powerful web platform features.

Mice and keyboards are typically implemented as HID peripherals, and are also capable of generating trusted input. A HID keyboard or mouse may contain advanced features like programmable macros, which store a sequence of inputs and allow the sequence to be played back at a later time. Device manufacturers must take care to design such features in a way that would prevent a malicious app from reprogramming the device with an unexpected input sequence, and must also protect against triggering macro playback without the user's explicit consent.

3.4 Mitigation

To mitigate security and privacy risks, it is recommended that user agents implement a chooser-based flow for requesting device access. When a page requests access to a HID device, the user agent should display a dialog that informs the user that the page wants to access a device. The dialog should display a list of connected HID devices and ask the user to select a device that will be exposed to the page. To reduce the possibility of accidental clicks, the dialog should require two separate interactions: one interaction to select the device from the list and a second interaction to confirm the selection and dismiss the dialog.

4. Extensions to the Navigator interface

WebIDL[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

hid attribute

When getting, the hid attribute always returns the same instance of the HID object.

5. HID interface

WebIDL[Exposed=Window, SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

Instances of HID are created with the internal slots described in the following table:

Internal slot Initial value Description (non-normative)
[[devices]] An empty ordered set An ordered set of HIDDevice instances representing the HID interfaces currently available on the system
onconnect attribute
onconnect is an event handler IDL attribute for the connect event type.
ondisconnect attribute
ondisconnect is an event handler IDL attribute for the disconnect event type.

When a HID interface becomes available on the system, run the following steps:

Note

A HID interface is a logical interface that can be used to communicate with a device over the HID protocol. Each HID interface has exactly one report descriptor that describes the set of reports supported by that interface. A single physical device may expose more than one HID interface. Devices with multiple HID interfaces run these steps once for each interface.

For example, USB devices are implemented as a collection of interfaces, each of which may specify an interface class. When a device has multiple USB interfaces that use the HID class, each interface is enumerated as a separate HID interface.

  1. Let device be a HIDDevice.
  2. Set device.[[vendorId]] to the vendor ID of the device that exposes the interface.
  3. Set device.[[productId]] to the product ID of the device that exposes the interface.
  4. Set device.[[productName]] to the product name of the device that exposes the interface.
  5. Set device.[[collections]] to the result of parsing the Report descriptor.
  6. Let hid be the result of calling device's relevant global object's Navigator object's hid getter.
  7. Append device to hid.[[devices]].
  8. If the user has allowed the site to access device as the result of a previous call to requestDevice(), then queue a global task on the relevant global object of hid using the HID device task source to fire an event named connect at hid using HIDConnectionEvent with its device attribute initialized to device.

To parse the report descriptor, run the following steps:

Note

The system will typically read the report descriptor byte sequence for each HID interface when a device is first connected and cache the values in the system registry. If the report descriptor is not available but the system provides information that can be used to reconstruct the layout of each report, the user agent may use an alternate algorithm instead of parsing the report descriptor.

The report descriptor format is described in [USBIF-HID-CLASS] section 6.2.2. The algorithm below is intended to implement the same parsing algorithm described in that section.

The report descriptor contains three classes of items. Main items are used to define and group data fields. Global items and Local items describe the data fields. Local items define characteristics that only apply to the next Main item, while Global items define characteristics that affect all subsequently defined Main items.

Each item has a item data field containing 0, 1, 2, or 4 bytes of data associated with the item and a bSize field that describes how many bytes are used to store the item data field. Each item also has a tag that identifies its type.

  1. Let items be the result of converting the report descriptor byte sequence into a list of Main items, Global items, and Local items.
  2. Initialize collections to be an empty sequence of HIDCollectionInfo.
  3. Initialize ancestors to be an empty list.
  4. Initialize localState to be an empty ordered map.
  5. Initialize usages to be an empty sequence of unsigned long.
  6. Initialize stringIndices to be an empty list.
  7. Initialize globalStack to be an empty stack.
  8. Initialize initialGlobalState to be an empty ordered map.
  9. Initialize reportId to 0.
  10. Set initialGlobalState["unitSystem"] to "none".
  11. Set initialGlobalState["unitExponent"] to 0.
  12. Set initialGlobalState["unitFactorLengthExponent"] to 0.
  13. Set initialGlobalState["unitFactorMassExponent"] to 0.
  14. Set initialGlobalState["unitFactorTimeExponent"] to 0.
  15. Set initialGlobalState["unitFactorTemperatureExponent"] to 0.
  16. Set initialGlobalState["unitFactorCurrentExponent"] to 0.
  17. Set initialGlobalState["unitFactorLuminousIntensityExponent"] to 0.
  18. Set initialGlobalState["logicalMinimum"] to 0.
  19. Set initialGlobalState["logicalMaximum"] to 0.
  20. Set initialGlobalState["physicalMinimum"] to 0.
  21. Set initialGlobalState["physicalMaximum"] to 0.
  22. Push initialGlobalState onto globalStack.
  23. For each item of items:
    Note

    Main items are described in [USBIF-HID-CLASS] sections 6.2.2.4 through 6.2.2.6. An item with the Input tag, Output tag, or Feature tag defines a field within an input, output, or feature report. The item data field of a Main item with an Input tag, Output tag, or Feature tag is a bit field containing several boolean parameters describing the data field. An item with the Collection tag defines a new collection nested within the current collection, or a new top-level collection if there is no current collection. The item data field of a Main item with a Collection tag contains the collection type. An item with the End Collection tag closes the current collection.

To create a HID report item with item, localState, globalState, usages, and stringIndices, run the following steps:

  1. Let reportItem be a new HIDReportItem dictionary.
  2. Let value be the item data field interpreted as an unsigned long.
  3. Let bitfield be a list of boolean values representing each of the bits of value, starting from the low-order bits.
  4. Set reportItem["isConstant"] to bitfield[0].
  5. Set reportItem["isArray"] to !bitfield[1].
  6. Set reportItem["isAbsolute"] to !bitfield[2].
  7. Set reportItem["wrap"] to bitfield[3].
  8. Set reportItem["isLinear"] to !bitfield[4].
  9. Set reportItem["hasPreferredState"] to bitfield[5].
  10. Set reportItem["hasNull"] to bitfield[6].
  11. Set reportItem["isVolatile"] to bitfield[7].
  12. Set reportItem["isBufferedBytes"] to bitfield[8].
  13. Set reportItem["usages"] to usages.
  14. Set reportItem["reportSize"] to globalState["reportSize"].
  15. Set reportItem["reportCount"] to globalState["reportCount"].
  16. Set reportItem["unitExponent"] to globalState["unitExponent"].
  17. Set reportItem["unitSystem"] to globalState["unitSystem"].
  18. Set reportItem["unitFactorLengthExponent"] to globalState["unitFactorLengthExponent"].
  19. Set reportItem["unitFactorMassExponent"] to globalState["unitFactorMassExponent"].
  20. Set reportItem["unitFactorTimeExponent"] to globalState["unitFactorTimeExponent"].
  21. Set reportItem["unitFactorTemperatureExponent"] to globalState["unitFactorTemperatureExponent"].
  22. Set reportItem["unitFactorCurrentExponent"] to globalState["unitFactorCurrentExponent"].
  23. Set reportItem["unitFactorLuminousIntensityExponent"] to globalState["unitFactorLuminousIntensityExponent"].
  24. Set reportItem["logicalMinimum"] to globalState["logicalMinimum"].
  25. Set reportItem["logicalMaximum"] to globalState["logicalMaximum"].
  26. Set reportItem["physicalMinimum"] to globalState["physicalMinimum"].
  27. Set reportItem["physicalMaximum"] to globalState["physicalMaximum"].
  28. If "usageMinimum" is in localState, then set reportItem["usageMinimum"] to localState["usageMinimum"].

  29. If "usageMaximum" is in localState, then set reportItem["usageMaximum"] to localState["usageMaximum"].

  30. Set reportItem["isRange"] to true if reportItem["usageMinimum"] is less than reportItem["usageMaximum"], or false otherwise.
  31. If "stringMinimum" is in localState and "stringMaximum" is in localState:
    1. Append the items of the range from localState["stringMinimum"] to localState["stringMaximum"] to stringIndices.
  32. For each stringIndex of stringIndices:
    1. Let string be the result of reading the string descriptor at index stringIndex.
    2. Append string to reportItem["strings"].
  33. Return reportItem.

When a HID interface becomes unavailable on the system, run the following steps:

  1. Let device be the HIDDevice in hid.[[devices]] representing the interface.
  2. Let hid be the result of calling device's relevant global object's Navigator object's hid getter.
  3. Remove device from hid.[[devices]].
  4. If the user has allowed the site to access device as the result of a previous call to requestDevice(), then queue a global task on the relevant global object of hid using the HID device task source to fire an event named disconnect at hid using HIDConnectionEvent with its device attribute initialized to device.

5.1 getDevices() method

The getDevices() method steps are:

  1. Let promise be a new promise.
  2. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "hid", reject promise with a "SecurityError" DOMException and return promise.
  3. Run the following steps in parallel:
    1. Let devices be an empty sequence of HIDDevice.
    2. For each device of this.[[devices]]:
      1. If the user has allowed the site to access device as the result of a previous call to requestDevice(), then append device to devices.
    3. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with devices.
  4. Return promise.

5.2 requestDevice() method

Note

The requestDevice() permission dialog presents a list of connected devices and asks the user to select one.

If a device has multiple HID interfaces, the dialog MAY present only a single item that represents all the interfaces. When the user selects an item that represents multiple HID interfaces, the user agent MUST grant access to all the HID interfaces exposed by the device.

The requestDevice() method steps are:

  1. Let promise be a new promise.
  2. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "hid", reject promise with a "SecurityError" DOMException and return promise.
  3. If the relevant global object of this does not have transient activation, reject promise with a "SecurityError" DOMException and return promise.
  4. If options["filters"] is present, then run the following steps for each filter of options["filters"]:
    1. If filter is empty, then reject promise with a TypeError and return promise.
    2. If filter["productId"] is present and filter["vendorId"] is not present, reject promise with a TypeError and return promise.
    3. If filter["usage"] is present and filter["usagePage"] is not present, reject promise with a TypeError and return promise.
  5. Run the following steps in parallel:
    1. Initialize availableDevices to be an empty list.
    2. For each device of this.[[devices]]:
      1. If device matches any filter in options["filters"], then append device to availableDevices.
    3. Prompt the user to grant the site access to a HID device by presenting them with the list of devices in availableDevices.
      Note
      The user agent may modify the device list before presenting it to the user. For example, devices with multiple HID interfaces SHOULD be represented by a single item such that selecting the item grants access to all interfaces exposed by the device. Whether a device is implemented as a single interface or a collection of interfaces is an implementation detail that may not be known by the user and should not be considered relevant for device access permissions.
    4. Let devices be an empty sequence of HIDDevice.
    5. If the user does not choose a device, queue a global task on the relevant global object of this using the HID device task source to resolve promise with devices and abort these steps.
    6. For each device of this.[[devices]]:
      1. If device represents a HID interface exposed by the chosen device, then append device to devices.
    7. Queue a global task on the relevant global object of device using the HID device task source to resolve promise with devices.
  6. Return promise.

5.2.1 HIDDeviceRequestOptions dictionary

WebIDLdictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
};
filters member
Filters for HID devices.

5.2.2 HIDDeviceFilter dictionary

WebIDLdictionary HIDDeviceFilter {
    unsigned long vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};
vendorId member
The vendor ID to match.
productId member
The product ID to match. If the vendorId member is not present, productId is ignored.
usagePage member
The top-level collection usage page to match.
usage member
The top-level collection usage ID to match. If the usagePage member is not present, usage is ignored.
Note

Device filters are used to narrow the list of devices presented to the user in the chooser dialog created by requestDevice(). When no filters are provided, all connected devices are included. When one or more filters are provided, a device is included if any filter matches.

All HIDDeviceFilter members are optional. Each member specifies a rule. To match a HIDDeviceFilter, every rule must be satisfied. An empty HIDDeviceFilter matches any device.

Device ID rules are used to select devices by their vendor ID and product ID. This is useful when an application is only designed to work with a specific device, or otherwise relies on vendor-specific functionality. Including a vendorId rule causes the filter to only match devices with the specified vendor ID. If a productId rule is also included, the filter will only match devices with the specified vendor ID and product ID. productId is ignored if it is specified without a vendorId rule.

Usage rules are used to select devices by the HID usages assigned to the top-level collections of the device. This is useful when an application is designed to work with a standard class of device. To match a device, at least one of the device's collections must match every usage rule. Including a usagePage rule causes the filter to only match if the device contains a collection with the specified usage page. If a usage rule is also included, the filter will only match devices with the specified usage page and usage ID. usage is ignored if it is specified without a usagePage rule.

Device ID rules and usage rules may be combined. For instance, an application may want to match devices from a particular vendor, but only devices that implement a specific device class.

A HIDDevice device matches any filter in a sequence filters of HIDDeviceFilter if these steps return true:

  1. If filters is empty, then return true.
  2. For each filter of filters:
    1. If filter matches the device IDs of device and filter matches any collection of device, then return true.
  3. Return false.

A HIDDeviceFilter filter matches the device IDs of device if these steps return true:

  1. If "vendorId" is in filter:
    1. If filter["vendorId"] is not equal to device.vendorId, then return false.
    2. If "productId" is in filter and filter["productId"] is not equal to device.productId, then return false.
  2. Return true.

A HIDDeviceFilter filter matches any collection of device if these steps return true:

  1. For each collection of device.collections:
    1. If filter matches the collection collection then return true.
  2. Return false.

A HIDDeviceFilter filter matches the collection collection if these steps return true:

  1. If "usagePage" is in filter:
    1. If filter["usagePage"] is not equal to collection.usagePage, then return false.
    2. If "usage" is in filter and filter["usage"] is not equal to collection.usage, then return false.
  2. Return true.

6. HIDDevice interface

WebIDL[Exposed=Window, SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

Methods on this interface typically complete asynchronously, queuing work on the HID device task source.

Instances of HIDDevice are created with the internal slots described in the following table:

Internal slot Initial value Description (non-normative)
[[state]] "closed" Tracks the active state of the HIDDevice
[[vendorId]] 0 The vendor ID of the device
[[productId]] 0 The product ID of the device
[[productName]] "" The product name of the device
[[collections]] An empty sequence of HIDCollectionInfo The top-level collections created by parsing the report descriptor
[[pendingSendReportPromises]] An empty list Pending sendReport() Promises
[[pendingSendFeatureReportPromises]] An empty list Pending sendFeatureReport() Promises
[[pendingReceiveFeatureReportPromises]] An empty list Pending receiveFeatureReport() Promises
oninputreport attribute
oninputreport is an event handler IDL attribute for the inputreport event type.
opened attribute

A flag indicating that the HIDDevice is ready to transfer data.

The opened getter steps are:

  1. If this.[[state]] is opened, then return true.
  2. Return false.
vendorId attribute

A vendor ID is an unsigned short value assigned by a vendor ID source that identifies the manufacturer of a device.

The vendorId attribute is the vendor ID of the device. If the device has no vendor ID or the vendor ID cannot be accessed, the attribute MUST be 0.

The vendorId getter steps are:

  1. Return this.[[vendorId]].
productId attribute

A product ID is an unsigned short value assigned by the manufacturer of the device that identifies the product.

The productId attribute is the product ID of the device. If the device has no product ID or the product ID cannot be accessed, the attribute MUST be 0.

The productId getter steps are:

  1. Return this.[[productId]].
productName attribute

A string identifying the product.

For USB HID devices, the product name SHOULD contain the value of the string descriptor at the index iProduct specified in the Device Descriptor. For Bluetooth HID devices, the product name SHOULD contain the value of the Device Name characteristic. If the device has no product name or the product name is empty or cannot be accessed, the attribute MUST return an empty string.

The productName string SHOULD NOT contain any identifiers like a serial number or Bluetooth device address that could be used to uniquely identify the device.

The productName getter steps are:

  1. Return this.[[productName]].
collections attribute

A sequence of HIDCollectionInfo representing the top-level collections in the report descriptor.

The collections getter steps are:

  1. Return this.[[collections]].
Note
Top-level collections group items that serve similar purposes within the device. Applications look at the HID usage applied to top-level collections to identify devices. An application may not recognize a device if it does not follow the conventions for a particular type of device. Refer to [USBIF-HID-USAGE] for more information about the conventional behavior for standard HID devices.

When an input report is received from a device, run the following steps:

  1. If the input report is a blocked report, abort these steps.
  2. Let reportId be the report ID for this report, or 0 if the HID interface does not use report IDs.
  3. Let data be a DataView created over the byte sequence representing the input report. If the HID interface uses report IDs, the byte sequence MUST NOT include the report ID byte.
  4. Queue a global task on the relevant global object of this using the HID device task source to fire an event named inputreport at device using HIDInputReportEvent with its device attribute initialized to device, its reportId attribute initialized to reportId, and its data attribute initialized to data.

6.1 open() method

The open() method steps are:

  1. Let promise be a new promise.
  2. If this.[[state]] is not "closed", then reject promise with a "InvalidStateError" DOMException and return promise.
  3. Set this.[[state]] to "opening".
  4. Perform the following steps in parallel:
    1. Invoke the operating system to open the HID device.
    2. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
    3. Set this.[[state]] to "opened".
    4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
  5. Return promise.

6.2 close() method

The close() method steps are:

  1. Let promise be a new promise.
  2. Set this.[[state]] to "closing".
  3. For each pendingPromise of this.[[pendingSendReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  4. Empty this.[[pendingSendReportPromises]].
  5. For each pendingPromise of this.[[pendingSendFeatureReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  6. Empty this.[[pendingSendFeatureReportPromises]].
  7. For each pendingPromise of this.[[pendingReceiveFeatureReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  8. Empty this.[[pendingReceiveFeatureReportPromises]].
  9. Perform the following steps in parallel:
    1. Invoke the operating system to close the HID device and release any associated resources.
    2. Set this.[[state]] to "closed".
    3. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
  10. Return promise.

6.3 sendReport() method

Note

The sendReport() method is used to send an output report with the specified reportId and data. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The sendReport() method steps are:

  1. Let promise be a new promise.
  2. If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
  3. If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
  4. Append promise to this.[[pendingSendReportPromises]].
  5. Perform the following steps in parallel:
    1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
    2. Invoke the operating system to send an output report with the specified reportId and data.
    3. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
    4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
  6. Return promise.

6.4 sendFeatureReport() method

Note

The sendFeatureReport() method is used to send a feature report with the specified reportId and data. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The sendFeatureReport() method steps are:

  1. Let promise be a new promise.
  2. If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
  3. If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
  4. Append promise to this.[[pendingSendFeatureReportPromises]].
  5. Perform the following steps in parallel:
    1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
    2. Invoke the operating system to send a feature report with the specified reportId and data.
    3. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
    4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
  6. Return promise.

6.5 receiveFeatureReport() method

Note

The receiveFeatureReport() method is used to request a feature report with the specified reportId. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The receiveFeatureReport() method steps are:

  1. Let promise be a new promise.
  2. If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
  3. If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
  4. Append promise to this.[[pendingReceiveFeatureReportPromises]].
  5. Perform the following steps in parallel:
    1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
    2. Let data be a DataView created over the byte sequence representing the result of invoking the operating system to read a feature report with the specified reportId.
      Note
      data will contain whatever report data was received from the operating system. If the device uses report IDs the first byte may be the report ID. This byte is included because the device may respond with other data in place of the report ID.
    3. If reading the feature report fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
    4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with data.
  6. Return promise.

7. HIDConnectionEvent interface

WebIDL[Exposed=Window, SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};
device attribute
The HIDDevice instance that represents the connected or disconnected device.

7.1 HIDConnectionEventInit dictionary

WebIDLdictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};
device member
The device associated with the event.

8. HIDInputReportEvent interface

WebIDL[Exposed=Window, SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};
device attribute
The HIDDevice instance that represents the HID interface that sent the input report.
reportId attribute
The one-byte identification prefix for this report, or 0 if the HID interface does not use report IDs.
data attribute
A DataView containing the data from the input report, excluding the reportId byte if the HID interface uses report IDs.

8.1 HIDInputReportEventInit dictionary

WebIDLdictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};
device member
The device associated with the event.
reportId member
The report ID for the input report.
data member
The data for the input report.

9. HIDCollectionInfo dictionary

WebIDLdictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

When a device is first connected to the system, the system MUST retrieve the report descriptor for each HID interface exposed by the device. The Report descriptor is a byte sequence that can be expanded into a hierarchical data structure describing the layout of each report supported by the device. The elements of this data structure are called items. Groups of items that share a relationship are called collections.

A HIDCollectionInfo object represents a single collection within the report descriptor. When a collection contains nested collections, the nested collections are included as elements of children.

The inputReports, outputReports, and featureReports attributes contain sequences of HIDReportInfo that give information about each report described within this collection. For a top-level collection, the HIDReportInfo represents a flattened view of all items that compose the report. The flattened view interleaves items contained in nested collections with items contained within the top-level collection. For a nested collection, the HIDReportInfo includes only the items contained within the collection and its nested collections.

usagePage member

The usage page component of the HID usage associated with this collection.

HID usages are constants that can be interpreted by an application to identify the purpose and meaning of an item or collection. A HID usage is an unsigned long value composed of an unsigned short usage page in the high order bits and an unsigned short usage ID in the low order bits. Standard HID usage values are described in [USBIF-HID-CLASS] and other documents published by the USB Implementers Forum.

The HID usages of the top-level collections exposed by the device is used to identify the general device type.

usage member

The usage ID component of the HID usage associated with this collection.

A usage ID is used to select an individual HID usage on a usage page. By convention, usage IDs 0x01 through 0x1F are reserved for top-level collections.

type member

A value representing the collection type.

Collection type Value
Physical 0x00
Application 0x01
Logical 0x02
Report 0x03
Named Array 0x04
Usage Switch 0x05
Usage Modified 0x06
Reserved for future use 0x07 to 0x7F
Vendor-defined 0x80 to 0xFF

Each collection type describes a different type of relationship among the grouped items. Refer to [USBIF-HID-CLASS] section 6.2.2.6 for more information about collection types.

children member
A sequence of HIDCollectionInfo representing the collections nested within this collection.
inputReports member
A sequence of HIDReportInfo representing the input reports described within this collection.
outputReports member
A sequence of HIDReportInfo representing the output reports described within this collection.
featureReports member
A sequence of HIDReportInfo representing the feature reports described within this collection.

10. HIDReportInfo dictionary

WebIDLdictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

A HIDReportInfo represents one input, output, or feature report within the report descriptor.

reportId member
A HID interface uses report IDs if it prepends a one-byte identification prefix to each report transfer. The reportId member is the prefix for this report if the interface uses report IDs, or 0 otherwise.
items member
A sequence of HIDReportItem representing the fields of this report.

11. HIDReportItem dictionary

WebIDLdictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};
isAbsolute member
true if the data is absolute (based on a fixed origin), or false if the data is relative (indicating the change in value from the last report).
isArray member
true if the item creates array data fields in reports where each data field contains an index corresponding to a pressed button or key, or false if the item creates variable data fields in reports where each data field contains a value.
isBufferedBytes member
true if the item emits a fixed-sized stream of bytes, or false if the item is a numeric quantity.
isConstant member
true if the item is a static read-only field and cannot be modified, or false if the item defines report fields that contain modifiable device data.
isLinear member
true if the item represents a linear relationship between what is measured and what is reported, or false if the data has been processed in some way.
isRange member
true if the item assigns usages from a HID usage range defined by usageMinimum and usageMaximum, or false if the item has a sequence of HID usage values in usages.
isVolatile member

true if the item value can change without host interaction, or false if the item value should only be changed by the host.

Only used for Feature and Output items.

hasNull member
true if the item has a null state in which it is not sending meaningful data, or false if it does not have a null state. When in a null state, the item will report a value outside of the specified logicalMinimum and logicalMaximum.
hasPreferredState member
true if the item has a preferred state to which it will return when the user is not physically interacting with the control, or false if the item does not have a preferred state.
wrap member
true if the item value rolls over when reaching either the extreme high or low value, or false if the item value does not roll over.
usages member

If isRange is true or this item has no associated HID usage values, then usages MUST be undefined.

If isRange is false then usages is a sequence of HID usage values associated with this item.

usageMinimum member

If isRange is true then usageMinimum contains the minimum HID usage value in the usage range associated with this item.

If isRange is false then usageMinimum MUST be undefined.

usageMaximum member

If isRange is true then usageMaximum contains the maximum HID usage value in the usage range associated with this item.

If isRange is false then usageMaximum MUST be undefined.

reportSize member
The size of each report data field in bits. The reportSize MUST be greater than 0.
reportCount member
The number of fields included in the report for this item. The reportCount MUST be greater than 0.
unitExponent member
The value of the unit exponent, or 0 if the item has no unit definition.
unitSystem member
A HIDUnitSystem enum value specifying the unit system for the unit definition, or "none" if the item has no unit definition.
unitFactorLengthExponent member
The value of the exponent for the length unit (centimeters, radians, inch, or degrees) in the unit definition, or 0 if the item has no unit definition.
unitFactorMassExponent member
The value of the exponent for the mass unit (gram or slug) in the unit definition, or 0 if the item has no unit definition.
unitFactorTimeExponent member
The value of the exponent for the time unit (seconds) in the unit definition, or 0 if the item has no unit definition.
unitFactorTemperatureExponent member
The value of the exponent for the temperature unit (Kelvin or degrees Fahrenheit) in the unit definition, or 0 if the item has no unit definition.
unitFactorCurrentExponent member
The value of the exponent for the electrical current unit (Ampere) in the unit definition, or 0 if the item has no unit definition.
unitFactorLuminousIntensityExponent member
The value of the exponent for the luminous intensity unit (Candela) in the unit definition, or 0 if the item has no unit definition.
logicalMinimum member
The minimum extent of this item in logical units. This is the minimum value that a variable or array item will report.
logicalMaximum member
The maximum extent of this item in logical units. This is the maximum value that a variable or array item wll report.
physicalMinimum member
The minimum value for the physical extent of this item. This represents the logicalMinimum with units applied to it.
physicalMaximum member
The maximum value for the physical extent of this item. This represents the logicalMaximum with units applied to it.
strings member
The strings associated with this item, or an empty sequence if no strings are associated with this item.

12. HIDUnitSystem enum

[USBIF-HID-CLASS] section 6.2.2.7 defines four standard unit systems: SI Linear, SI Rotation, English Linear, and English Rotation. Each item uses one of these four unit systems, a vendor-defined unit system, or no unit system.

WebIDLenum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};
"none"
No unit system. Indicates that the item does not have a unit definition.
"si-linear"
The SI Linear unit system uses centimeter, gram, second, Kelvin, Ampere, Candela.
"si-rotation"
The SI Rotation unit system uses radian, gram, second, Kelvin, Ampere, Candela.
"english-linear"
The English Linear unit system uses inch, slug, second, degree Fahrenheit, Ampere, Candela.
"english-rotation"
The English Rotation unit system uses degree, slug, second, degree Fahrenheit, Ampere, Candela.
"vendor-defined"
A vendor-defined unit system.
"reserved"
Indicates that the device used a reserved value for its unit system.

13. Usage Examples

14. The HID Blocklist

This specification relies on a blocklist file in the https://github.com/WICG/webhid repository to restrict the set of HID devices a website can access.

The result of parsing the blocklist at a URL url is a sequence of dictionary objects produced by fetching url and parsing its contents as JSON.

The HID blocklist is the result of parsing the blocklist at https://github.com/WICG/webhid/blob/main/blocklist.txt

A report is a blocked report if the following steps return true:

  1. For each rule of the HID blocklist:
    1. If the report is blocked by a blocklist rule rule then return true.
  2. Return false.

A report is blocked by a blocklist rule rule if the following steps return true:

  1. Let reportId be the report ID of the report, or 0 if the HID interface does not use report IDs.
  2. Let reportType be "input" if the report is an input report, "output" if the report is an output report, or "feature" if the report is a feature report.
  3. Let collection be the top-level collection that contains the report.
  4. If rule contains "vendor" and rule["vendor"] is not device.vendorId, return false.
  5. If rule contains "product" and rule["product"] is not device.productId, return false.
  6. If rule contains "reportId" and rule["reportId"] is not reportId, return false.
  7. If rule contains "reportType" and rule["reportType"] is not reportType, return false.
  8. If rule contains "usagePage" and rule["usagePage"] is not collection["usagePage"], return false.
  9. If rule contains "usage" and rule.["usage"] is not collection["usage"], return false.
  10. Return true.

15. Integrations

15.1 Permissions Policy

This specification defines a feature that controls whether the hid attribute is exposed on the Navigator object.

The feature name for this feature is "hid".

The default allowlist for this feature is 'self'.

16. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

A. Acknowledgements

The following people contributed to the development of this document.

B. References

B.1 Normative references

[dom]
DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
[HTML]
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[permissions-policy]
Permissions Policy. Ian Clelland. W3C. 16 July 2020. W3C Working Draft. URL: https://www.w3.org/TR/permissions-policy-1/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8174
[USBIF-HID-CLASS]
Device Class Definition for Human Interface Devices (HID) version 1.11. Mike Bergman et al. USB Implementers Forum. May 27, 2001. Specification. URL: https://www.usb.org/document-library/device-class-definition-hid-111
[WebIDL]
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

B.2 Informative references

[GAMEPAD]
Gamepad. Steve Agoston; James Hollyer; Matthew Reynolds; Brandon Jones; Scott Graham; Theodore Mielczarek. W3C. 8 April 2021. W3C Working Draft. URL: https://www.w3.org/TR/gamepad/
[pointerevents]
Pointer Events. Jacob Rossi; Matt Brubeck. W3C. 4 April 2019. W3C Recommendation. URL: https://www.w3.org/TR/pointerevents/
[uievents]
UI Events. Gary Kacmarcik; Travis Leithead; Doug Schepers. W3C. 30 May 2019. W3C Working Draft. URL: https://www.w3.org/TR/uievents/
[USBIF-HID-USAGE]
HID Usage Tables for Universal Serial Bus (USB) version 1.22. David Abzarian et al. USB Implementers Forum. April 6, 2021. Specification. URL: https://www.usb.org/document-library/hid-usage-tables-122