Hardware & Device APIs¶

Hardware and device APIs let a Progressive Web App talk to physical things: Bluetooth Low Energy peripherals, USB and HID devices, serial ports, NFC tags, motion sensors, game controllers, MIDI instruments, barcode-bearing camera frames and XR headsets. They replace the native helper apps, browser plugins and "download our driver" pages that used to sit between a web page and a device. Most of them ship only in Chromium-based browsers because Mozilla and Apple consider low-level device access too risky, so a production PWA treats each one as a progressive enhancement: detect it, ask for access through a chooser or prompt at the right moment, handle every rejection, and fall back gracefully everywhere else.

Choosing the right device API¶

The first question is not "which API is cool" but "how does the device present itself to the operating system". If the OS already has a class driver for the device (keyboard, mouse, webcam, audio interface, mass storage), a higher-level web API usually exists and the low-level API will refuse to touch it. If the device speaks a vendor protocol over USB, a serial protocol, BLE GATT or NDEF, pick the API that matches the transport.

flowchart TD
    A[Device to integrate] --> B{How is it connected?}
    B -->|Bluetooth Low Energy GATT| BT[Web Bluetooth]
    B -->|Bluetooth Classic SPP| SER[Web Serial - RFCOMM]
    B -->|USB| C{What does the OS see?}
    C -->|Virtual COM port / UART bridge| SER
    C -->|HID class device| HID[WebHID]
    C -->|Vendor-specific interface| USB[WebUSB]
    C -->|Audio, video, storage, keyboard| HL[Use the high-level web API instead]
    B -->|NFC tag, NDEF| NFC[Web NFC - Android only]
    B -->|MIDI instrument| MIDI[Web MIDI]
    B -->|Game controller| GP[Gamepad API]
    B -->|Built-in sensors| S[Geolocation, DeviceOrientation, Generic Sensors]

Several neighboring capabilities have their own pages: files and folders are covered in File System Access, camera-to-share flows in Web Share, and audio, video, clipboard, wake lock and screen capture in Media & System APIs.

The security model all device APIs share¶

Device APIs are among the most dangerous capabilities the web has. A granted USB device can be reflashed. A serial-controlled machine can move physical parts. A HID device can be a keyboard in disguise. The specifications stack several independent defenses, and you need to understand each one because each produces a distinct failure in your code.

Secure context, top-level frames and Permissions Policy¶

Every API on this page is restricted to secure contexts. For the chooser APIs, Web NFC, Web MIDI, the sensor classes and WebXR the interfaces are simply missing on http: origins (other than localhost), so feature detection returns false. Geolocation and the orientation and motion events are older and behave differently: the interfaces stay visible, but position requests fail with PERMISSION_DENIED and the events never fire, so detect isSecureContext as well. Most APIs also declare a Permissions Policy feature whose default allowlist is 'self'. Same-origin iframes inherit access. Cross-origin iframes get nothing unless the embedding page delegates the feature with allow, and a Permissions-Policy response header can switch a feature off for your own origin as defense-in-depth.

Web NFC has no policy token at all: the specification only allows it in the active top-level browsing context, so an iframe can never scan or write tags.

<!-- Delegate serial and USB to a trusted cross-origin tool, nothing else -->
<iframe
  src="https://flasher.example.com/"
  allow="serial https://flasher.example.com; usb https://flasher.example.com">
</iframe>

Permissions-Policy: serial=(self "https://flasher.example.com"), usb=(self "https://flasher.example.com"), hid=(), bluetooth=()

See Permissions for the general permission lifecycle, how the Permissions API reports state and how users revoke grants.

Choosers are not permission prompts¶

Geolocation, Web NFC and Web MIDI use a classic permission prompt: "Allow example.com to use X?" The four low-level transports (Bluetooth, USB, HID, serial) use a chooser instead. The page describes the kind of device it wants with filters, the browser lists matching devices it can see, and the user picks exactly one. That design has consequences you will feel in your code:

• No enumeration before consent. A page cannot list connected USB devices, nearby BLE peripherals or serial ports to decide whether to show a "Connect" button. You can only call getDevices() / getPorts(), which returns devices the user has already granted to your origin.
• Transient user activation is mandatory for requestDevice() / requestPort(). Calling them from load, a timer or after an await that outlived the activation window rejects with SecurityError. Put the call directly in a click handler, before any other await.
• Cancelling is not an error in the usual sense. Web Bluetooth, WebUSB and Web Serial reject with NotFoundError when the user closes the chooser. WebHID resolves with an empty array. Treat both as "user changed their mind", not as a failure to report.
• Grants are per device and per origin. Two PWAs on different origins never share device access, and granting one USB device does not grant a second, identical one.

sequenceDiagram
    participant U as User
    participant P as PWA page
    participant B as Browser
    participant OS as OS / device stack
    U->>P: click "Connect"
    P->>B: requestDevice({ filters }) during transient activation
    B->>OS: enumerate matching devices
    B-->>U: chooser listing only matching devices
    U->>B: selects one device
    B->>B: store grant for origin + device
    B-->>P: resolves with a device object
    P->>OS: open(), claim, transfer (through the browser)
    Note over P,B: On later visits: getDevices() returns granted devices without a chooser

Blocklists and protected device classes¶

Filters decide what the user is offered. Blocklists decide what a page can use even when the user wants to allow it. Each API keeps its list in a public repository so security fixes can ship without spec changes.

The blocklists are why you cannot build a web-based FIDO key manager, keylogger, or mass-storage reader with these APIs. Protected functionality always has a dedicated, safer API: WebAuthn for security keys, getUserMedia() for cameras and microphones, File System Access for storage.

How long access lasts: getDevices(), forget() and revocation¶

forget() matters more than it looks. When the user clicks "Disconnect" in your UI, calling forget() removes the grant so the device disappears from getDevices() and from the browser's site-settings page. That is the honest implementation of "disconnect", and it keeps your origin's list of granted devices from growing forever.

Where Firefox and Safari stand¶

The standards positions explain the support tables better than any list of version numbers. Mozilla and Apple both argue that users cannot meaningfully judge the risk of handing raw device access to a website, and that device firmware is too often unprepared for hostile input.

Mozilla's compromise for "powerful but useful" device APIs is the site permission add-on: the first call triggers a prompt to install a small, synthetically generated add-on that grants the permission to that one site. Firefox uses it for Web MIDI (since Firefox 108) and for Web Serial (Firefox 151, released May 19, 2026). From your code's point of view it is just a slower permission flow that can still end in a rejection.

Apple's list of APIs it has "decided to not yet implement due to fingerprinting, security, and other concerns" includes Web Bluetooth, Web MIDI, Magnetometer, Web NFC, Ambient Light Sensor, WebHID, Serial API, Web USB and User Idle Detection. Every iOS and iPadOS browser uses WebKit, so on an iPhone none of these APIs exist in any browser, installed PWA or not. See iOS & iPadOS for the full picture.

Feature detection that does not lie¶

Presence of the interface is necessary but not sufficient. Firefox exposes navigator.serial but the first requestPort() may involve an add-on install. Chrome on Windows may expose BarcodeDetector without supporting any formats on that platform. Linux Chrome may expose navigator.bluetooth while getAvailability() reports no usable adapter. Build a capability module that checks the deeper signal where one exists.

// Detect device APIs once, at startup, and expose a frozen capability map.
// Deeper probes (adapter availability, supported barcode formats) are async.

export async function detectDeviceCapabilities() {
  const caps = {
    secureContext: globalThis.isSecureContext === true,
    bluetooth: "bluetooth" in navigator,
    bluetoothAdapter: false,
    usb: "usb" in navigator,
    hid: "hid" in navigator,
    serial: "serial" in navigator,
    nfc: "NDEFReader" in globalThis,
    geolocation: "geolocation" in navigator,
    geolocationElement: "HTMLGeolocationElement" in globalThis,
    orientationEvents: "DeviceOrientationEvent" in globalThis,
    orientationNeedsPermission:
      typeof globalThis.DeviceOrientationEvent?.requestPermission === "function",
    genericSensors: "Accelerometer" in globalThis && "Gyroscope" in globalThis,
    gamepad: typeof navigator.getGamepads === "function",
    midi: typeof navigator.requestMIDIAccess === "function",
    xr: "xr" in navigator,
    barcodeFormats: [],
  };

  if (caps.bluetooth) {
    try {
      // Resolves false when there is no adapter or the platform blocks Bluetooth.
      caps.bluetoothAdapter = await navigator.bluetooth.getAvailability();
    } catch {
      caps.bluetoothAdapter = false;
    }
  }

  if ("BarcodeDetector" in globalThis) {
    try {
      // An empty list means "interface present, nothing usable on this OS".
      caps.barcodeFormats = await BarcodeDetector.getSupportedFormats();
    } catch {
      caps.barcodeFormats = [];
    }
  }

  return Object.freeze(caps);
}

Use the result to show or hide features, not to block the app. A PWA that flashes firmware can still show documentation, logs and a download link for a native flasher when serial is false.

Installed PWAs versus browser tabs¶

Installing a PWA does not change the device permission model: the same chooser appears in the standalone window, grants are keyed by origin rather than by install state, and a grant made in a tab is visible to the installed app on the same origin. Two things do change in practice:

• An installed app window is more likely to stay open for long sessions, so reconnection logic (connect / disconnect events, backoff) matters more than in a tab.
• Isolated Web Apps can declare the usb-unrestricted Permissions Policy feature in their manifest. The WebUSB specification defines it as the only way to reach blocklisted devices and protected interface classes, and it is not available to ordinary PWAs.

Web Bluetooth¶

Web Bluetooth lets a page act as a Bluetooth Low Energy central that connects to a peripheral and uses its GATT (Generic Attribute Profile) server: services, characteristics and descriptors. It covers the large class of BLE devices built on standard or custom GATT profiles: heart-rate straps, cycling power meters, thermometers, glucose meters, smart bulbs, toys, lab equipment and microcontroller boards.

What it does not cover matters just as much:

• No Bluetooth Classic (BR/EDR) profiles. Classic serial (SPP/RFCOMM) is reachable through Web Serial instead.
• No peripheral or advertiser role: the page cannot advertise or act as a GATT server.
• No raw L2CAP channels.
• Scanning for advertisements without connecting (requestLEScan(), BluetoothDevice.watchAdvertisements()) remains experimental and behind flags.

Requesting a device: filters and options¶

navigator.bluetooth.requestDevice(options) takes a RequestDeviceOptions dictionary. The spec enforces that you pass either filters or acceptAllDevices: true, never both and never neither.

Manufacturer-data and service-data filters (Chrome 92) match advertisement bytes with a dataPrefix and an optional mask, so you can target a product line that advertises a model byte:

const device = await navigator.bluetooth.requestDevice({
  filters: [
    {
      // Company identifier assigned by the Bluetooth SIG (example value).
      manufacturerData: [
        {
          companyIdentifier: 0x00e0,
          dataPrefix: new Uint8Array([0x01, 0x02]),
          mask: new Uint8Array([0xff, 0xf0]), // compare the high nibble of byte 2 only
        },
      ],
    },
  ],
  exclusionFilters: [{ namePrefix: "Bootloader" }], // hide devices in DFU mode
  optionalServices: ["battery_service"],
});

Service, characteristic and descriptor identifiers are BluetoothServiceUUID values: a full 128-bit UUID string, a 16- or 32-bit alias number (0x180d), or a name from the GATT assigned numbers registry ("heart_rate"). BluetoothUUID.getService("heart_rate") returns the canonical "0000180d-0000-1000-8000-00805f9b34fb", and BluetoothUUID.canonicalUUID(0x2a37) expands an alias. Custom services on your own hardware always use full 128-bit UUIDs.

The error surface of requestDevice():

Connecting, reading and subscribing to notifications¶

The following module connects to any device exposing the standard Heart Rate service, reads the Body Sensor Location characteristic, subscribes to Heart Rate Measurement notifications and parses them according to the GATT specification. It is complete and uses only standard assigned numbers, so it works with most chest straps and many watches in broadcast mode.

// Connects to a BLE heart-rate sensor and emits parsed measurements.
// Usage: const hr = new HeartRateMonitor(); hr.addEventListener("measurement", ...);
//        button.onclick = () => hr.connect();   // must run inside the click handler

const SENSOR_LOCATIONS = ["Other", "Chest", "Wrist", "Finger", "Hand", "Ear lobe", "Foot"];

export class HeartRateMonitor extends EventTarget {
  #device = null;
  #characteristic = null;
  #reconnectAttempts = 0;
  #userDisconnected = false;

  get connected() {
    return Boolean(this.#device?.gatt?.connected);
  }

  async connect() {
    // requestDevice() MUST be the first awaited call in the click handler,
    // otherwise transient activation may have expired.
    this.#device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ["heart_rate"] }],
      optionalServices: ["battery_service"],
    });
    this.#userDisconnected = false;
    this.#device.addEventListener("gattserverdisconnected", () => this.#onDisconnected());
    await this.#connectGatt();
    return this.#device.name ?? "Unnamed sensor";
  }

  async #connectGatt() {
    const server = await this.#device.gatt.connect();
    const service = await server.getPrimaryService("heart_rate");

    // Body Sensor Location is optional in the profile: tolerate its absence.
    try {
      const location = await service.getCharacteristic("body_sensor_location");
      const value = await location.readValue();
      this.dispatchEvent(
        new CustomEvent("location", { detail: SENSOR_LOCATIONS[value.getUint8(0)] ?? "Unknown" }),
      );
    } catch (error) {
      if (error.name !== "NotFoundError") throw error;
    }

    this.#characteristic = await service.getCharacteristic("heart_rate_measurement");
    this.#characteristic.addEventListener("characteristicvaluechanged", (event) => {
      // event.target.value is a DataView over the notification payload.
      this.dispatchEvent(
        new CustomEvent("measurement", { detail: parseHeartRate(event.target.value) }),
      );
    });
    await this.#characteristic.startNotifications();
    this.#reconnectAttempts = 0;
    this.dispatchEvent(new Event("connected"));
  }

  async #onDisconnected() {
    this.dispatchEvent(new Event("disconnected"));
    if (this.#userDisconnected) return;

    // Exponential backoff: 1s, 2s, 4s ... capped at 30s, max 8 attempts.
    while (!this.#userDisconnected && this.#reconnectAttempts < 8) {
      const delay = Math.min(30_000, 1000 * 2 ** this.#reconnectAttempts++);
      await new Promise((resolve) => setTimeout(resolve, delay));
      try {
        // gatt.connect() does not need a user gesture once the device was granted.
        await this.#connectGatt();
        return;
      } catch (error) {
        console.warn(`Reconnect attempt ${this.#reconnectAttempts} failed`, error);
      }
    }
    this.dispatchEvent(new Event("gaveup"));
  }

  async disconnect() {
    this.#userDisconnected = true;
    try {
      await this.#characteristic?.stopNotifications();
    } catch {
      // The link may already be gone; stopping notifications is best-effort.
    }
    this.#device?.gatt?.disconnect();
  }
}

// Heart Rate Measurement (0x2A37) layout:
// byte 0 flags: bit0 = 16-bit value, bit1 = contact detected, bit2 = contact supported,
//               bit3 = energy expended present, bit4 = RR intervals present
export function parseHeartRate(view) {
  const flags = view.getUint8(0);
  let offset = 1;
  const result = {};

  if (flags & 0x01) {
    result.heartRate = view.getUint16(offset, /* littleEndian */ true);
    offset += 2;
  } else {
    result.heartRate = view.getUint8(offset);
    offset += 1;
  }
  if (flags & 0x04) result.contactDetected = Boolean(flags & 0x02);
  if (flags & 0x08) {
    result.energyExpendedKJ = view.getUint16(offset, true);
    offset += 2;
  }
  if (flags & 0x10) {
    result.rrIntervalsSec = [];
    for (; offset + 1 < view.byteLength; offset += 2) {
      result.rrIntervalsSec.push(view.getUint16(offset, true) / 1024); // 1/1024 s units
    }
  }
  return result;
}

Every GATT value arrives as a DataView. Always pass the endianness flag explicitly: GATT is little-endian, DataView defaults to big-endian, and forgetting the second argument is the most common source of "the numbers are garbage" bug reports.

Writing values and the one-operation-at-a-time rule¶

BluetoothRemoteGATTCharacteristic offers three write methods:

The explicit variants shipped in Chrome 85. Check characteristic.properties.write and .writeWithoutResponse before choosing. A value larger than the negotiated ATT MTU minus 3 bytes fails or is truncated depending on the platform, so chunk large payloads at the protocol level your firmware expects.

Chromium's Bluetooth stack processes one GATT operation per device at a time on several platforms. Two overlapping readValue() or writeValue*() calls fail with NetworkError: GATT operation already in progress. The specification acknowledges this and tells sites to serialize their calls. A tiny promise queue solves it for the whole app:

// Serializes GATT operations: each task starts only after the previous one settles.
export class GattQueue {
  #tail = Promise.resolve();

  run(task) {
    const result = this.#tail.then(task, task); // run even if the previous task failed
    this.#tail = result.catch(() => {}); // keep the chain alive
    return result;
  }
}

// Usage
const queue = new GattQueue();
const encoder = new TextEncoder();
await Promise.all([
  queue.run(() => ledCharacteristic.writeValueWithResponse(Uint8Array.of(0xff, 0x00, 0x00))),
  queue.run(() => nameCharacteristic.writeValueWithResponse(encoder.encode("Kitchen"))),
  queue.run(() => batteryLevel.readValue()),
]);

Handling disconnects¶

BLE links drop constantly: the user walks away, the peripheral sleeps to save power, the OS reclaims the radio. gattserverdisconnected fires on the BluetoothDevice. Your BluetoothDevice object stays valid while the page lives, so reconnecting only needs device.gatt.connect() without a new gesture, which is what the backoff loop above does. Notifications do not resume on their own after reconnecting: call startNotifications() again and re-fetch services and characteristics, because the objects from the previous connection are stale.

After a page reload the BluetoothDevice is gone. Because navigator.bluetooth.getDevices() still requires chrome://flags/#enable-web-bluetooth-new-permissions-backend (chromestatus lists it as a developer trial), a PWA has to show a "Reconnect" button that repeats requestDevice(). Design the UI so that this is one tap, and remember which device the user picked (by device.name or an app-level identifier) so you can pre-fill filters that narrow the chooser to it.

device.id is an opaque, origin-scoped identifier generated by the browser, not the device's Bluetooth address. It is stable for the same origin and device in Chrome but is not guaranteed to be stable across browsers or profiles, and it is useless for identifying the device anywhere else.

The GATT blocklist¶

Some attributes are too dangerous to expose even to a site the user trusts. The GATT blocklist marks UUIDs as fully blocked or blocked for writes (exclude-writes). Selected entries:

Accessing a blocked UUID rejects with SecurityError. Filtering on a blocked service in requestDevice() also throws.

Platform notes¶

• Android: Chrome for Android since version 56. Android also requires Location to be enabled for BLE scanning on older Android versions, and Chrome prompts for the "Nearby devices" or location runtime permission the first time.
• Windows: Chrome 70 and later, on Windows 10 version 1703 (Creators Update) or newer.
• macOS and ChromeOS: supported. macOS asks the user to allow the browser to use Bluetooth the first time.
• Linux: MDN's compatibility data notes that Linux support is not enabled by default; the Web Bluetooth community group's status page says it requires chrome://flags/#enable-experimental-web-platform-features.
• iOS and iPadOS: no support in any browser, because all of them use WebKit.
• Android WebView: not supported, which also affects apps that wrap web content in a WebView rather than a Trusted Web Activity.

Check navigator.bluetooth.getAvailability() and listen for the availabilitychanged event to grey out the "Connect" button when the adapter is off.

WebUSB¶

WebUSB gives a page direct access to USB devices that no operating-system class driver has claimed. It is how browser-based firmware flashers, programmable keyboards with vendor configuration interfaces, lab instruments, receipt printers with vendor protocols and hardware wallets' vendor interfaces work without installing native software.

The USB model in five objects¶

WebUSB mirrors the USB descriptor hierarchy one-to-one:

Transfers map to the four USB transfer types:

A control transfer's setup object has requestType ("standard", "class" or "vendor"), recipient ("device", "interface", "endpoint" or "other"), request, value and index. A "stall" status is a protocol-level refusal from the device, not an exception; clear it with device.clearHalt(direction, endpointNumber) before retrying on that endpoint.

Requesting a device¶

navigator.usb.requestDevice({ filters, exclusionFilters }): filters is required (pass [] to list everything, which you should avoid in production). A device matches a USBDeviceFilter when every present member matches:

exclusionFilters (Chrome 117) removes devices from the chooser, for example a bootloader product ID you handle elsewhere.

A complete vendor-interface driver¶

This class drives a device that exposes a vendor-specific interface (class 0xFF) with one bulk IN and one bulk OUT endpoint, which is the pattern used by most microcontroller WebUSB firmware. It claims the right interface by inspecting descriptors instead of hard-coding numbers, reads in a loop, recovers from stalls and cleans up on disconnect.

// Bulk-endpoint link to a vendor-specific USB interface.
const VENDOR_CLASS = 0xff;

export class UsbLink extends EventTarget {
  #device;
  #interfaceNumber;
  #endpointIn;
  #endpointOut;
  #reading = false;

  constructor(device) {
    super();
    this.#device = device;
    navigator.usb.addEventListener("disconnect", (event) => {
      if (event.device === this.#device) {
        this.#reading = false;
        this.dispatchEvent(new Event("disconnected"));
      }
    });
  }

  // Call from a click handler. Filters are examples: use your own vendor/product IDs.
  static async request(filters = [{ vendorId: 0x2341 }]) {
    const device = await navigator.usb.requestDevice({ filters });
    return new UsbLink(device);
  }

  // Reconnect to previously granted devices without a chooser.
  static async restore(vendorId) {
    const devices = await navigator.usb.getDevices();
    const device = devices.find((d) => d.vendorId === vendorId);
    return device ? new UsbLink(device) : null;
  }

  async open() {
    const device = this.#device;
    if (!device.opened) await device.open();
    // Some devices arrive unconfigured; configuration values start at 1.
    if (device.configuration === null) await device.selectConfiguration(1);

    const { iface, alternate } = findVendorInterface(device.configuration);
    this.#interfaceNumber = iface.interfaceNumber;
    await device.claimInterface(this.#interfaceNumber); // fails if an OS driver owns it
    if (alternate.alternateSetting !== 0) {
      await device.selectAlternateInterface(this.#interfaceNumber, alternate.alternateSetting);
    }

    for (const endpoint of alternate.endpoints) {
      if (endpoint.type !== "bulk") continue;
      if (endpoint.direction === "in") this.#endpointIn = endpoint;
      else this.#endpointOut = endpoint;
    }
    if (!this.#endpointIn || !this.#endpointOut) {
      throw new Error("Vendor interface lacks bulk IN/OUT endpoints");
    }

    // Many CDC-like firmwares wait for a "host connected" signal. This mirrors
    // SET_CONTROL_LINE_STATE (0x22) with DTR set; adapt to your firmware's protocol.
    await device.controlTransferOut({
      requestType: "class",
      recipient: "interface",
      request: 0x22,
      value: 0x01,
      index: this.#interfaceNumber,
    });

    this.#readLoop();
  }

  async #readLoop() {
    this.#reading = true;
    const { endpointNumber, packetSize } = this.#endpointIn;
    while (this.#reading) {
      try {
        // Request a multiple of the max packet size to avoid "babble" overflows.
        const result = await this.#device.transferIn(endpointNumber, packetSize * 8);
        if (result.status === "stall") {
          await this.#device.clearHalt("in", endpointNumber);
          continue;
        }
        if (result.data?.byteLength) {
          this.dispatchEvent(new CustomEvent("data", { detail: new Uint8Array(result.data.buffer) }));
        }
      } catch (error) {
        // NetworkError here usually means the device was unplugged.
        this.#reading = false;
        if (error.name !== "NetworkError" && error.name !== "AbortError") {
          this.dispatchEvent(new CustomEvent("error", { detail: error }));
        }
      }
    }
  }

  async write(bytes) {
    const result = await this.#device.transferOut(this.#endpointOut.endpointNumber, bytes);
    if (result.status === "stall") {
      await this.#device.clearHalt("out", this.#endpointOut.endpointNumber);
      throw new Error("Device stalled the OUT endpoint");
    }
    return result.bytesWritten;
  }

  async close({ forget = false } = {}) {
    this.#reading = false;
    try {
      await this.#device.controlTransferOut({
        requestType: "class", recipient: "interface", request: 0x22, value: 0x00,
        index: this.#interfaceNumber,
      });
      await this.#device.releaseInterface(this.#interfaceNumber);
      await this.#device.close();
    } finally {
      if (forget) await this.#device.forget(); // revoke the grant entirely
    }
  }
}

function findVendorInterface(configuration) {
  for (const iface of configuration.interfaces) {
    for (const alternate of iface.alternates) {
      if (alternate.interfaceClass === VENDOR_CLASS) return { iface, alternate };
    }
  }
  throw new Error("No vendor-specific (0xFF) interface found");
}

Note the pending transferIn() that sits in the read loop: close() aborts it, which is why the loop swallows AbortError. Never call transferIn() twice concurrently on the same endpoint unless your protocol expects multiple outstanding reads.

Protected interface classes¶

The WebUSB specification defines interface classes that pages may not claim, because a higher-level, better-protected API or OS driver owns them:

A composite device can still be opened: you may claim its vendor interface while its HID interface stays with the OS. claimInterface() on a protected interface rejects with SecurityError. On top of the class rules, Chromium keeps a device-level blocklist for specific products whose firmware can be abused (for example some security keys).

Operating-system drivers: the most common deployment problem¶

When open() or claimInterface() fails on a customer machine but works on yours, the cause is almost always the OS, not your code:

• Windows: the browser can only reach an interface that is bound to the generic WinUSB driver. Ship Microsoft OS 2.0 descriptors in your firmware so Windows binds WinUSB automatically; otherwise users need a driver-install tool.
• Linux: the device node must be accessible to the user. Ship a udev rule granting access for your vendor/product IDs, or open() rejects with SecurityError: Access denied.
• macOS: if a kernel driver (for example the CDC-ACM serial driver) has claimed an interface, claimInterface() rejects with NetworkError: Unable to claim interface. Use Web Serial for interfaces the OS turns into serial ports.
• Android: Chrome for Android supports WebUSB since version 61 for devices that Android itself does not claim. Android asks for USB access for the browser app on first use.

Workers and debugging¶

navigator.usb is exposed in dedicated workers (MDN records this since Chrome 70), so you can move a chatty transfer loop off the main thread. requestDevice() is window-only: obtain the grant in the page, then call getDevices() in the worker. Normal service workers do not get WebUSB; only extension service workers do (Chrome 118).

Chrome's about://usb-internals page lists devices with their descriptors and lets you simulate test devices. about://device-log shows low-level errors (driver claims, permission failures) that the JavaScript exception message omits.

WebHID¶

The Human Interface Device class covers far more than keyboards and mice: game controllers with non-standard features, stream decks and macro pads, LED controllers, barcode scanners in HID mode, scales, foot pedals, VR accessories and telephony headsets all use HID reports. WebHID gives a page access to those devices' reports without a native driver, while keeping keyboards, mice and security keys off limits.

Reports, collections and usages¶

A HID device describes itself with a report descriptor. What matters to your code:

• The descriptor defines top-level collections, each identified by a usage page and a usage (for example Generic Desktop 0x01 / Joystick 0x04, or vendor-defined page 0xFF00). WebHID exposes them as device.collections.
• Data moves in reports: input reports (device to host, delivered as inputreport events), output reports (sendReport()) and feature reports (sendFeatureReport() / receiveFeatureReport()), each optionally prefixed by a report ID. When a device does not use report IDs, pass 0.
• One physical device can expose several HID interfaces. The chooser shows it once, and granting it grants all of its HID interfaces, so requestDevice() resolves with an array of HIDDevice objects.

Requesting a device¶

navigator.hid.requestDevice({ filters, exclusionFilters }) requires filters. Each HIDDeviceFilter can contain vendorId, productId (needs vendorId), usagePage and usage (needs usagePage). A filter must not be empty. A device matches when its IDs match and at least one of its collections matches the usage rules. exclusionFilters, if present, must be non-empty.

Unlike the other chooser APIs, cancelling the chooser resolves with [] rather than rejecting. Check the length.

A complete HID device controller¶

// Generic controller for a vendor-defined HID device.
// Report IDs and payload layouts below are illustrative; take real values from
// your device's report descriptor (about://device-log or a USB descriptor dump).

const FILTERS = [{ vendorId: 0x1234, usagePage: 0xff00 }]; // example values
const REPORT_ID_STATUS = 0x01;   // input report: status updates
const REPORT_ID_COMMAND = 0x02;  // output report: commands
const FEATURE_ID_CONFIG = 0x03;  // feature report: persistent configuration

export async function connectHidDevice() {
  // Must run inside a user gesture.
  const devices = await navigator.hid.requestDevice({ filters: FILTERS });
  if (devices.length === 0) return null; // user cancelled: not an error
  return openHid(pickVendorInterface(devices));
}

export async function restoreHidDevice() {
  const devices = await navigator.hid.getDevices();
  const candidates = devices.filter((d) => d.vendorId === FILTERS[0].vendorId);
  return candidates.length ? openHid(pickVendorInterface(candidates)) : null;
}

function pickVendorInterface(devices) {
  // Choose the interface whose collections include the vendor usage page.
  return (
    devices.find((d) => d.collections.some((c) => c.usagePage === 0xff00)) ?? devices[0]
  );
}

async function openHid(device) {
  if (!device.opened) await device.open();

  device.addEventListener("inputreport", (event) => {
    const { reportId, data } = event; // data is a DataView WITHOUT the report ID byte
    if (reportId !== REPORT_ID_STATUS) return;
    const status = {
      battery: data.getUint8(0),
      buttons: data.getUint16(1, true),
      temperatureC: data.getInt16(3, true) / 100,
    };
    device.dispatchEvent(new CustomEvent("status", { detail: status }));
  });

  return {
    device,
    async setLed(r, g, b) {
      await device.sendReport(REPORT_ID_COMMAND, Uint8Array.of(0x10, r, g, b));
    },
    async readConfig() {
      // The returned DataView INCLUDES the report ID as its first byte.
      const view = await device.receiveFeatureReport(FEATURE_ID_CONFIG);
      return { brightness: view.getUint8(1), mode: view.getUint8(2) };
    },
    async writeConfig({ brightness, mode }) {
      await device.sendFeatureReport(FEATURE_ID_CONFIG, Uint8Array.of(brightness, mode));
    },
    async close({ forget = false } = {}) {
      await device.close();
      if (forget) await device.forget();
    },
  };
}

navigator.hid?.addEventListener("disconnect", ({ device }) => {
  console.info(`HID device removed: ${device.productName}`);
});

The asymmetry in the comments is real and bites everyone once: inputreport events give you reportId separately and data without it, while receiveFeatureReport() returns a DataView that starts with the report ID byte. sendReport() and sendFeatureReport() take the ID as a separate argument and the payload without it.

Report sizes are fixed by the descriptor. What happens with a wrong-sized payload depends on the operating system's HID stack: Chromium zero-pads short output reports on some platforms, while a write the OS refuses rejects with NotAllowedError ("Failed to write the report"). Build every report at exactly the declared size so the behavior is the same everywhere.

What WebHID blocks¶

The WebHID blocklist is short and targeted:

Reports inside blocked collections cannot be sent or received. A gaming keyboard with an extra vendor-defined collection for RGB lighting is still usable: you get the vendor collection, never the keystrokes.

WebHID support¶

WebHID ships in Chromium-based browsers on Windows, macOS, Linux and ChromeOS since Chrome 89. There is no support in Chrome for Android. Dedicated workers gained navigator.hid in Chrome 131 (extension service workers earlier, in Chrome 117). Mozilla's position is negative, and WebKit lists WebHID among APIs it has decided not to implement.

Web Serial¶

Web Serial reads and writes serial ports with WHATWG Streams. It is the workhorse of web-based maker and industrial tooling: microcontroller IDEs and flashers, 3D-printer and CNC control panels, GPS and modem configuration, oscilloscopes and data loggers.

What counts as a serial port¶

• USB CDC-ACM devices (most microcontroller boards with native USB).
• USB-to-UART bridges, which the OS turns into COM ports or /dev/tty* devices.
• Built-in platform UARTs.
• Bluetooth Classic devices offering an RFCOMM service such as the Serial Port Profile (desktop Chrome 117 and later).

Requesting a port¶

navigator.serial.requestPort(options) accepts:

The method needs transient activation and the serial policy. If the user closes the chooser it rejects with NotFoundError. port.getInfo() tells you what was picked: { usbVendorId, usbProductId } or { bluetoothServiceClassId }.

Opening a port: every option¶

open() rejects with InvalidStateError if the port is already open in this page and with NetworkError if the OS fails to open it, typically because another program (a serial monitor, a slicer, another tab) holds it.

bufferSize of 255 is small for high-baud data loggers. At 921600 baud a device can deliver around 90 KB per second, and if your read loop stalls for a moment the OS buffer overruns and the readable stream errors with BufferOverrunError. Raise bufferSize (for example to 64 KB) for bursty devices.

Reading, writing and closing correctly¶

port.readable is a byte ReadableStream of Uint8Array chunks and port.writable a WritableStream. Chunk boundaries are arbitrary: a 40-byte message can arrive as 1 + 39 bytes. Framing is your job. The class below handles framing by line, backpressure, recoverable errors and the close sequence the specification requires (cancel the reader, abort or close the writer, then close the port).

// Line-oriented serial connection with correct error recovery and shutdown.

class LineBreakTransformer {
  #buffer = "";
  transform(chunk, controller) {
    this.#buffer += chunk;
    const lines = this.#buffer.split(/\r?\n/);
    this.#buffer = lines.pop(); // keep the incomplete tail
    for (const line of lines) controller.enqueue(line);
  }
  flush(controller) {
    if (this.#buffer) controller.enqueue(this.#buffer);
  }
}

const RECOVERABLE = new Set(["BufferOverrunError", "BreakError", "FramingError", "ParityError"]);

export class SerialConnection extends EventTarget {
  #port;
  #reader = null;
  #keepReading = false;
  #readLoopDone = Promise.resolve();
  #writeQueue = Promise.resolve();

  constructor(port) {
    super();
    this.#port = port;
    port.addEventListener("disconnect", () => this.dispatchEvent(new Event("disconnected")));
  }

  static async request(filters) {
    const port = await navigator.serial.requestPort(filters ? { filters } : {});
    return new SerialConnection(port);
  }

  async open(options = { baudRate: 115200, bufferSize: 64 * 1024 }) {
    await this.#port.open(options);
    this.#keepReading = true;
    this.#readLoopDone = this.#readLoop();
  }

  async #readLoop() {
    // Outer loop: a recoverable error (parity, framing, overrun, break) errors the
    // current readable; port.readable returns a NEW stream afterwards.
    while (this.#port.readable && this.#keepReading) {
      const decoder = new TextDecoderStream();
      // Keep the pipe promise: port.readable stays locked until it settles.
      const pipeDone = this.#port.readable.pipeTo(decoder.writable).catch(() => {});
      this.#reader = decoder.readable
        .pipeThrough(new TransformStream(new LineBreakTransformer()))
        .getReader();
      try {
        for (;;) {
          const { value, done } = await this.#reader.read();
          if (done) break; // reader.cancel() was called
          this.dispatchEvent(new CustomEvent("line", { detail: value }));
        }
      } catch (error) {
        if (!RECOVERABLE.has(error.name)) {
          // NetworkError = device unplugged: port.readable becomes null, loop exits.
          this.dispatchEvent(new CustomEvent("error", { detail: error }));
        }
      } finally {
        this.#reader.releaseLock();
        this.#reader = null;
        await pipeDone; // port.readable is unlocked only after this
      }
    }
  }

  // Writes are serialized: port.writable allows one writer at a time, and a
  // second getWriter() while the first is held throws TypeError.
  writeLine(text) {
    const task = async () => {
      const writer = this.#port.writable.getWriter();
      try {
        // Awaiting write() applies backpressure from the transmit buffer.
        await writer.write(new TextEncoder().encode(`${text}\r\n`));
      } finally {
        writer.releaseLock();
      }
    };
    const result = this.#writeQueue.then(task, task);
    this.#writeQueue = result.catch(() => {}); // keep the chain alive after a failure
    return result;
  }

  async close() {
    this.#keepReading = false;
    // Cancelling propagates back through both pipes and cancels port.readable.
    await this.#reader?.cancel().catch(() => {});
    await this.#readLoopDone; // waits for pipeDone, i.e. for port.readable to unlock
    await this.#writeQueue; // no writer may hold port.writable
    // port.close() rejects if either stream is still locked.
    await this.#port.close();
  }

  async forget() {
    if (this.#port.readable || this.#port.writable) await this.close();
    await this.#port.forget();
  }
}

A pipe keeps its source locked until the pipe promise settles, and pipeThrough() hides that promise. That is why the read loop pipes port.readable into the decoder with pipeTo() and keeps the returned promise: close() cancels the outermost reader, cancellation travels back up the chain and cancels port.readable, and only when pipeDone settles is the stream unlocked. Calling port.close() before that point rejects with a TypeError about a locked stream, which is the most common Web Serial shutdown bug. The write queue exists for the same reason on the writable side.

Read errors: recoverable versus fatal¶

The specification defines which errors keep the port usable:

Writes reject with NetworkError when the device disappears and with UnknownError for other OS failures.

Control signals: resetting boards from the browser¶

setSignals() drives output lines and getSignals() reads input lines:

Many development boards wire DTR and RTS to the microcontroller's reset and boot-mode pins through a transistor pair, which is how desktop flashing tools reset a board into its bootloader. The same trick works from a PWA. The sequence below matches the "classic reset" used by common ESP32 tooling; boards with different auto-reset circuits need different timing, so treat it as an example to verify against your hardware.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Reset an ESP32-style board with the common two-transistor auto-reset circuit
// into its serial bootloader. The port must already be open.
export async function resetIntoBootloader(port) {
  await port.setSignals({ dataTerminalReady: false, requestToSend: true }); // hold EN low
  await sleep(100);
  await port.setSignals({ dataTerminalReady: true, requestToSend: false }); // IO0 low, EN high
  await sleep(50);
  await port.setSignals({ dataTerminalReady: false }); // release IO0
}

Connection state, BYOB reads and workers¶

• connect and disconnect events fire on navigator.serial and bubble from each SerialPort. Since Chrome 130, port.connected reports the logical connection state, and Bluetooth RFCOMM ports also fire these events when the remote device connects or drops, without the port being opened.

• Since Chrome 106 port.readable supports BYOB ("bring your own buffer") readers, useful for fixed-size binary frames without extra copies:

  byob-read.js

  const reader = port.readable.getReader({ mode: "byob" });
  // Fill exactly 64 bytes, looping until the view is full.
  let view = new Uint8Array(64);
  let filled = 0;
  while (filled < view.byteLength) {
    const { value, done } = await reader.read(view.subarray(filled));
    if (done) break;
    filled += value.byteLength;
    view = new Uint8Array(value.buffer); // the buffer was transferred; re-wrap it
  }
  reader.releaseLock();
  

• navigator.serial is exposed in dedicated workers. requestPort() is window-only, but getPorts() works in the worker, so the pattern is: grant in the page, then run the whole protocol in a worker.

Web Serial support in 2026¶

Web Serial has the broadest reach of the four transport APIs:

• Chromium desktop (Chrome, Edge, Opera) since version 89. Bluetooth RFCOMM ports since Chrome 117.
• Chrome for Android: from Chrome 138 limited to Bluetooth RFCOMM serial ports. MDN's compatibility data records full support, including wired ports, from Chrome 148, matching the "Web Serial API on Android" chromestatus entry.
• Firefox 151 and later on desktop: supported, with access gated by a synthetically generated site-permission add-on, the same mechanism Firefox uses for Web MIDI. Firefox for Android does not support it.
• Safari: not supported; WebKit opposes the API.

The specification document is published at wicg.github.io/serial (MDN's compatibility data now references serial.spec.whatwg.org, which serves the same document).

Web NFC¶

Web NFC reads and writes NDEF (NFC Data Exchange Format) messages on NFC tags held a few centimeters from the back of an Android phone. That covers the practical NFC use cases for a PWA: asset and inventory tags, equipment provisioning (writing a configuration or a deep link onto a tag), event check-in and access badges that carry an identifier, museum and retail "tap for details" tags, smart posters and physical game cards.

It deliberately stops at NDEF. Low-level tag technologies (ISO-DEP, NFC-A/B, NFC-F), peer-to-peer mode and host-based card emulation are not exposed, so a PWA cannot read payment cards, transit cards or passports, and cannot make the phone behave like a tag.

NDEF messages, records and record types¶

A tag stores one NDEF message. A message is a list of records, and each record has a type and a payload. Web NFC represents them as NDEFMessage (with a records array) and NDEFRecord objects. On reading, record.data is a DataView over the payload (or null), so text encoded in UTF-16 survives intact.

Every record can also carry an id (a URL used as the record identifier). record.toRecords() parses a nested message out of a smart poster or external-type record and returns null when the payload is not a valid NDEF message. Nesting is limited to a depth of 32; deeper structures throw TypeError when you write.

The write() method also accepts shortcuts: a plain string becomes a single text record and a BufferSource becomes a single MIME record of type application/octet-stream.

scan(), write() and makeReadOnly()¶

NDEFReader is the only entry point. The same object scans, writes and locks tags, and all three methods require the "nfc" permission.

Three behaviors shape how you build the UI:

• Reads arrive as events, not return values. After scan() resolves, each tap fires reading (an NDEFReadingEvent with serialNumber and message). A tag that is in range but not NDEF-readable fires readingerror instead.
• write() waits for a tap indefinitely. The promise stays pending until the user holds a tag to the phone, so always pass a signal (for example AbortSignal.timeout(30_000)) and show a cancel button. When a timeout signal aborts the call, the rejection is the signal's reason: a TimeoutError DOMException, not an AbortError.
• One pending write per document. Calling write() again aborts the previous pending write with AbortError. When the page becomes hidden, the browser suspends NFC and aborts pending writes and lock operations that have not started transferring.

serialNumber is the tag's UID as a string of hex bytes, or an empty string when the tag has none. The specification warns that not all tags have a stable UID and some generate a random one on every read, so never treat it as a secure identifier.

Permission model and visibility¶

Web NFC uses a normal permission prompt, not a chooser. The first scan(), write() or makeReadOnly() must run inside a user gesture so the browser can show the prompt; once the user grants "nfc", later calls work without a gesture, which lets you start scanning on page load for returning users. The same permission covers reading and writing.

Beyond the permission, the platform limits when NFC works:

• Only the top-level document can use it. There is no Permissions Policy token to delegate, and calls from an iframe reject with InvalidStateError.
• The page must be visible and the screen on and unlocked. Hidden pages have NFC suspended and it resumes automatically when the page becomes visible again.
• When no scan is active, Android handles a tapped tag itself (for example by opening a URL record in the default browser), which is why an NFC screen in your PWA should keep a scan running while it is open.

A complete NFC tag module¶

// Web NFC helper: scanning with typed record decoding, guarded writes and locking.
// Chrome for Android only. The first call to startScan()/write() must run inside a
// user gesture unless permissionState() already reports "granted".

const bytesOf = (view) =>
  view ? new Uint8Array(view.buffer, view.byteOffset, view.byteLength) : new Uint8Array();

export function decodeRecord(record) {
  switch (record.recordType) {
    case "empty":
      return { type: "empty" };
    case "text":
      // encoding is "utf-8" or "utf-16be" on read; TextDecoder understands both labels.
      return {
        type: "text",
        lang: record.lang,
        text: new TextDecoder(record.encoding ?? "utf-8").decode(record.data),
      };
    case "url":
    case "absolute-url":
      return { type: "url", url: new TextDecoder().decode(record.data) };
    case "mime":
      if (record.mediaType === "application/json") {
        return { type: "json", value: JSON.parse(new TextDecoder().decode(record.data)) };
      }
      return { type: "mime", mediaType: record.mediaType, bytes: bytesOf(record.data) };
    case "smart-poster":
      return { type: "smart-poster", records: (record.toRecords() ?? []).map(decodeRecord) };
    default: {
      // External types ("example.com:asset") may contain a nested message or raw bytes.
      let nested = null;
      try {
        nested = record.toRecords(); // null when the payload is not an NDEF message
      } catch {
        nested = null; // NotSupportedError for types that cannot nest
      }
      return {
        type: record.recordType.includes(":") ? "external" : "unknown",
        recordType: record.recordType,
        records: nested ? nested.map(decodeRecord) : null,
        bytes: bytesOf(record.data),
      };
    }
  }
}

// Translate DOMException names into messages a user can act on.
function explain(error) {
  const messages = {
    NotAllowedError: "NFC permission was denied, or the tag already holds data.",
    NotSupportedError: "This device has no NFC reader, or the tag cannot store NDEF data.",
    NotReadableError: "NFC is turned off. Enable it in Android settings and try again.",
    InvalidStateError: "NFC is only available in the top-level page.",
    NetworkError: "The tag moved away during the transfer. Hold it still and retry.",
    TimeoutError: "No tag was detected in time.",
    AbortError: "The NFC operation was canceled.",
  };
  return new Error(messages[error.name] ?? error.message, { cause: error });
}

export class NfcSession extends EventTarget {
  #reader = new NDEFReader();
  #scanController = null;
  #writing = false;

  static get supported() {
    return "NDEFReader" in globalThis;
  }

  static async permissionState() {
    try {
      return (await navigator.permissions.query({ name: "nfc" })).state;
    } catch {
      return "prompt"; // engines that do not know the "nfc" permission name reject
    }
  }

  constructor() {
    super();
    this.#reader.addEventListener("reading", ({ serialNumber, message }) => {
      // A tap during a pending write also runs the reading steps: the event would
      // carry the tag's OLD content, so suppress it while writing.
      if (this.#writing) return;
      this.dispatchEvent(
        new CustomEvent("tag", {
          detail: { serialNumber, records: message.records.map(decodeRecord) },
        }),
      );
    });
    this.#reader.addEventListener("readingerror", () => {
      // In range but not NDEF-readable, for example a bank card.
      this.dispatchEvent(new Event("unreadable"));
    });
  }

  async startScan() {
    if (this.#scanController) return; // a second scan() on this reader would reject
    const controller = new AbortController();
    try {
      await this.#reader.scan({ signal: controller.signal });
      this.#scanController = controller;
    } catch (error) {
      throw explain(error);
    }
  }

  stopScan() {
    this.#scanController?.abort();
    this.#scanController = null;
  }

  // records: NDEFRecordInit[]; lock: make the tag permanently read-only afterwards.
  async write(records, { overwrite = true, lock = false, timeoutMs = 30_000 } = {}) {
    const signal = AbortSignal.timeout(timeoutMs);
    this.#writing = true;
    try {
      await this.#reader.write({ records }, { overwrite, signal });
      // Irreversible. makeReadOnly() waits for a tag in range just like write(), so keep
      // the "hold the tag" prompt visible; the shared signal bounds both waits.
      if (lock) await this.#reader.makeReadOnly({ signal });
    } catch (error) {
      throw explain(error);
    } finally {
      this.#writing = false;
    }
  }
}

Wiring it up shows the gesture rule and the "resume for returning users" pattern:

import { NfcSession } from "./nfc-tags.js";

const nfc = NfcSession.supported ? new NfcSession() : null;
const encoder = new TextEncoder();

if (!nfc) {
  showManualEntryFallback(); // desktop, iOS, Firefox
} else {
  nfc.addEventListener("tag", ({ detail }) => renderTag(detail));
  nfc.addEventListener("unreadable", () => showToast("That tag is not supported."));

  // Permission already granted: scanning may start without a gesture.
  if ((await NfcSession.permissionState()) === "granted") await nfc.startScan();

  document.querySelector("#scan").addEventListener("click", async () => {
    try {
      await nfc.startScan(); // first call shows the permission prompt
      showToast("Hold a tag against the back of your phone.");
    } catch (error) {
      showToast(error.message);
    }
  });

  document.querySelector("#provision").addEventListener("click", async () => {
    try {
      await nfc.write(
        [
          { recordType: "url", data: "https://assets.example.com/a/4711" },
          {
            recordType: "example.com:asset", // external type under a domain you control
            data: encoder.encode(JSON.stringify({ id: 4711, rev: 3 })),
          },
        ],
        { overwrite: false }, // refuse to clobber a tag that already holds data
      );
      showToast("Tag written.");
    } catch (error) {
      showToast(error.message);
    }
  });
}