USB.requestDevice() — Methode · JavaScript-Referenz

Signatur

USB.prototype.requestDevice(options)

Beschreibung

navigator.usb.requestDevice() ist der Einstiegspunkt der WebUSB-API. Die Methode zeigt dem Nutzer einen Auswahldialog mit allen angeschlossenen USB-Geräten, die zu den übergebenen filters passen. Wählt der Nutzer ein Gerät aus, erhält die Seite dauerhaft die Berechtigung dafür, und das Promise wird mit einem USBDevice-Objekt erfüllt.

Gebraucht wird die Methode immer dann, wenn eine Webanwendung direkt mit USB-Hardware sprechen soll, für die es keinen Standard-Treiber des Betriebssystems gibt, zum Beispiel Mikrocontroller-Boards, Messgeräte, Firmware-Flasher oder spezielle Eingabegeräte. Nach der Auswahl muss das Gerät noch mit open() geöffnet, per selectConfiguration() konfiguriert und mit claimInterface() belegt werden, bevor Daten per transferIn()/transferOut() fließen.

Die Methode muss durch eine Nutzeraktion (transiente Aktivierung, z. B. ein Klick) ausgelöst werden und funktioniert nur in einem sicheren Kontext (HTTPS oder localhost). Geräte, für die bereits eine Berechtigung erteilt wurde, erreicht man ohne erneuten Dialog über navigator.usb.getDevices().

Parameter

Name	Typ	Beschreibung
$options Pflicht	Object	Konfigurationsobjekt für den Auswahldialog.
$options.filters Pflicht	Array<USBDeviceFilter>	Liste von Filtern; ein Gerät wird angezeigt, wenn es zu mindestens einem Filter passt. Jeder Filter kann `vendorId`, `productId` (nur zusammen mit `vendorId`), `classCode`, `subclassCode`, `protocolCode` und `serialNumber` enthalten. Ein leeres Array `[]` zeigt alle Geräte an.
$options.exclusionFilters	Array<USBDeviceFilter>	Filter für Geräte, die trotz passender `filters` nicht angezeigt werden sollen (neuer, Chrome 119+).

Rückgabewert

Typ

Promise<USBDevice>

Beschreibung

Ein Promise, das mit dem vom Nutzer ausgewählten USBDevice erfüllt wird. Es wird mit einer NotFoundError-DOMException abgelehnt, wenn der Nutzer den Dialog abbricht oder kein passendes Gerät vorhanden ist, mit SecurityError ohne Nutzeraktion bzw. bei blockierender Permissions-Policy, und mit TypeError bei ungültigen Filtern.

Beispiele

Gerät per Klick auswählen (Arduino-Filter)

const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  if (!('usb' in navigator)) {
    console.warn('WebUSB wird von diesem Browser nicht unterstützt.');
    return;
  }
  try {
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }] // Arduino
    });
    console.log(`Ausgewählt: ${device.productName} (${device.manufacturerName})`);
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.log('Kein Gerät ausgewählt.');
    } else {
      console.error(err);
    }
  }
});

Ausgewählt: Arduino Leonardo (Arduino LLC)

Gerät öffnen, Interface belegen und Daten senden

const connectAndSend = async () => {
  const device = await navigator.usb.requestDevice({
    filters: [
      { vendorId: 0x2341, productId: 0x8036 },
      { classCode: 0xff } // herstellerspezifische Klasse
    ]
  });

  await device.open();
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }
  await device.claimInterface(2);

  const data = new TextEncoder().encode('LED an\n');
  const result = await device.transferOut(4, data);
  console.log('Status:', result.status, '| Bytes:', result.bytesWritten);

  await device.close();
};

document.querySelector('#send').addEventListener('click', connectAndSend);

Status: ok | Bytes: 7

Bereits erlaubte Geräte wiederverwenden, sonst Dialog

const getDevice = async () => {
  const known = await navigator.usb.getDevices();
  const match = known.find((d) => d.vendorId === 0x2341);
  if (match) return match; // kein Dialog nötig

  // Muss innerhalb eines Klick-Handlers aufgerufen werden
  return navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341 }],
    exclusionFilters: [{ vendorId: 0x2341, productId: 0x0043 }]
  });
};

document.querySelector('#connect').addEventListener('click', async () => {
  const device = await getDevice();
  console.log('Seriennummer:', device.serialNumber);
});

Seriennummer: 8573631353735171C1A1

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser (Chrome, Edge, Opera) auf Desktop und Android. Firefox und Safari setzen WebUSB bewusst nicht um. Immer per 'usb' in navigator prüfen.
Nutzeraktion erforderlich: Ohne transiente Aktivierung (z. B. direkt beim Laden der Seite oder nach einem langen await im Handler) wird das Promise mit SecurityError abgelehnt. Rufe requestDevice() möglichst als erstes im Klick-Handler auf.
Sicherer Kontext & Permissions-Policy: Nur über HTTPS/localhost. In iframes muss allow="usb" gesetzt sein.
Geschützte Geräteklassen: Geräte wie Tastaturen, Mäuse, Massenspeicher, Audio/Video oder Smartcard-Leser (bzw. deren Interfaces) sind aus Sicherheitsgründen blockiert. Für HID bzw. serielle Geräte gibt es WebHID und Web Serial.
Filter: filters ist Pflicht; ein leeres Array zeigt alle Geräte, ist aber für Nutzer unübersichtlich. productId ohne vendorId erzeugt einen TypeError.
Treiberkonflikte: Unter Windows kann ein vom Betriebssystem belegter Treiber open() bzw. claimInterface() mit SecurityError/NetworkError scheitern lassen; ggf. ist ein WinUSB-Treiber nötig.

Siehe auch

USB USBDevice USBDevice.open() USB.getDevices() HID.requestDevice()