WebUSB

WebUSB is a browser API, exposed as navigator.usb, that lets a web page send commands to and read data from a USB device the user has chosen. It is a Web Platform Incubator Community Group draft, not a W3C Recommendation, and it is aimed at devices with no existing high-level web API. It works only in secure contexts, and MDN marks it experimental and not Baseline.

How it works

A page cannot scan the USB bus. It must call navigator.usb.requestDevice({ filters }) from a user gesture. A call without transient activation rejects with SecurityError. The browser shows a chooser limited to devices that match the filters, such as a vendorId, a productId or a classCode. If the user closes the chooser without selecting anything, the promise rejects with NotFoundError.

Once the user has granted access, navigator.usb.getDevices() lists the already-permitted devices without a prompt. That lets a page reconnect on the next visit. Plugging and unplugging fires connect and disconnect events on navigator.usb.

The usual calls on a USBDevice are:

• open() to start a session, then selectConfiguration(1)
• claimInterface(n) to take exclusive ownership of an interface
• controlTransferIn() and controlTransferOut() for control requests
• transferIn(endpoint, length) and transferOut(endpoint, data) for bulk and interrupt data

Only one execution context can claim an interface at a time, so a second claim fails. This mirrors how operating systems allow a single driver per interface.

The spec also protects sensitive device classes. An interface whose class code is in a protected list cannot be claimed. The list holds 0x01 Audio, 0x03 HID, 0x08 Mass Storage, 0x09 Hub, 0x0B Smart Card, 0x0E Video, 0x10 Audio/Video Devices and 0xE0 Wireless Controller. Those classes already have higher-level, safer APIs. A blocklist adds further devices. A separate policy-controlled feature named usb-unrestricted governs access to blocklisted devices and protected classes. The sample checks class codes against the protected list.

const PROTECTED = { 0x01: "Audio", 0x03: "HID", 0x08: "Mass Storage", 0x09: "Hub",
  0x0B: "Smart Card", 0x0E: "Video", 0x10: "Audio/Video Devices", 0xE0: "Wireless Controller" };
const hex = n => "0x" + n.toString(16).toUpperCase().padStart(2, "0");
for (const cls of [0xFF, 0x03, 0x08, 0x02]) {
  console.log(hex(cls), cls in PROTECTED ? "protected: " + PROTECTED[cls] : "not in the protected list");
}

Output:

0xFF not in the protected list
0x03 protected: HID
0x08 protected: Mass Storage
0x02 not in the protected list

Can WebUSB access a USB keyboard or flash drive?

WebUSB cannot claim a USB keyboard, mouse or flash drive interface. Keyboards and mice use the HID class (0x03) and flash drives use Mass Storage (0x08), and both are protected classes. A composite device can still expose a separate vendor-specific interface (class 0xFF) that the page is allowed to claim.

Common pitfalls

• Calling requestDevice() on load: without a click it rejects with SecurityError. Wire it to a button.
• Mixing up hex and decimal: vendorId and productId are unsigned shorts, and device listings usually print them in hex. Write 0xABCD in code, because the decimal literal 2000 is a different ID.
• Claiming a protected interface: a HID or Mass Storage interface is refused. Target the vendor-specific interface instead.
• Interface already in use: if another process or tab holds the interface, claimInterface() fails. Close the other program and try again.
• Skipping selectConfiguration(): a device with no active configuration cannot be used until you choose one.
• Forgetting the iframe policy: the usb feature can be blocked in embedded frames by Permissions-Policy.

Related terms

• HTTPS — the secure context the API requires
• Permissions-Policy header — can block the usb feature in frames
• Web Bluetooth — the sibling API for wireless Bluetooth Low Energy devices
• DOM — the document model that dispatches the connect and disconnect events
• Service worker — a different worker type; the WebUSB draft exposes the API to windows and dedicated workers, not service workers

See also

• Term: Web Bluetooth — the closest alternative when the device is wireless