Navigator.usb — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.usb

Beschreibung

navigator.usb ist der Einstieg in die WebUSB API. Das zurückgegebene USB-Objekt erbt von EventTarget. Mit ihm kann eine Webanwendung USB-Geräte finden, eine Berechtigung dafür anfordern und direkt mit ihnen kommunizieren. Einen nativen Treiber oder eine Zusatzsoftware braucht man dafür nicht.

Wichtige Bestandteile des USB-Objekts:

requestDevice(options): öffnet einen Auswahldialog des Browsers. Der Aufruf muss durch eine Nutzeraktion ausgelöst werden, zum Beispiel einen Klick.
getDevices(): liefert die Geräte, für die die Seite bereits eine Berechtigung hat.
Die Events connect und disconnect: melden, wenn ein berechtigtes Gerät angesteckt oder abgezogen wird.

Typische Einsatzfälle sind die Konfiguration und das Firmware-Update von Mikrocontrollern (z. B. Arduino oder micro:bit), Messgeräte, Kassen- und Etikettendrucker sowie eigene Hardware in Industrie und Bildung. Die Datenübertragung selbst läuft über USBDevice, und zwar mit open(), selectConfiguration(), claimInterface(), transferIn() und transferOut().

Die Eigenschaft ist nur in einem sicheren Kontext verfügbar, also unter HTTPS oder localhost. In nicht unterstützten Browsern ist sie undefined. Deshalb sollte man die Unterstützung immer vorab prüfen.

Rückgabewert

Typ

USB

Beschreibung

Das USB-Objekt des aktuellen Dokuments. Es stellt requestDevice(), getDevices() sowie die Events connect und disconnect bereit. Ohne Browser-Unterstützung ist der Wert undefined.

Beispiele

Unterstützung prüfen und bereits freigegebene Geräte auflisten

if (!('usb' in navigator)) {
  console.warn('WebUSB wird von diesem Browser nicht unterstützt.');
} else {
  const devices = await navigator.usb.getDevices();
  console.log(`${devices.length} freigegebene(s) Gerät(e)`);
  for (const device of devices) {
    console.log(device.productName, device.vendorId.toString(16), device.productId.toString(16));
  }
}

1 freigegebene(s) Gerät(e) Arduino Leonardo 2341 8036

Gerät per Klick anfordern und Daten senden

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

button.addEventListener('click', async () => {
  try {
    // Nur Geräte eines bestimmten Herstellers anzeigen (Arduino = 0x2341)
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }]
    });

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

    const data = new TextEncoder().encode('LED ON\n');
    const result = await device.transferOut(4, data);
    console.log('Gesendet:', result.bytesWritten, 'Bytes');
  } catch (err) {
    // NotFoundError, wenn der Nutzer den Dialog abbricht
    console.error('USB-Fehler:', err.name, err.message);
  }
});

Gesendet: 7 Bytes

Auf Anstecken und Abziehen reagieren

const onConnect = (event) => {
  console.log('Verbunden:', event.device.productName);
};
const onDisconnect = (event) => {
  console.log('Getrennt:', event.device.productName);
};

navigator.usb.addEventListener('connect', onConnect);
navigator.usb.addEventListener('disconnect', onDisconnect);

// Alternativ über die on-Property:
// navigator.usb.onconnect = onConnect;

// Später wieder abmelden
// navigator.usb.removeEventListener('connect', onConnect);

Verbunden: Arduino Leonardo Getrennt: Arduino Leonardo

// Wichtig · Fallstricke

Browser-Unterstützung: Nur in Chromium-basierten Browsern wie Chrome, Edge und Opera, jeweils auf dem Desktop und unter Android. Firefox und Safari unterstützen WebUSB aus Sicherheits- und Datenschutzgründen nicht. Vor der Nutzung immer mit 'usb' in navigator prüfen.
Sicherer Kontext: Die Eigenschaft ist nur unter HTTPS oder localhost verfügbar.
Nutzeraktion erforderlich: requestDevice() wirft einen SecurityError, wenn der Aufruf nicht durch eine Nutzeraktion wie einen Klick ausgelöst wurde. Bricht der Nutzer den Dialog ab, folgt ein NotFoundError.
Permissions Policy: In iframes muss die Funktion ausdrücklich erlaubt sein, zum Beispiel mit <iframe allow="usb">. Über den HTTP-Header Permissions-Policy: usb=() lässt sich WebUSB sperren.
Gesperrte Geräteklassen: Geräte mit geschützten Klassen wie HID (Tastatur, Maus), Massenspeicher, Audio und Video sowie Geräte auf der Blockliste des Browsers sind nicht zugänglich. Für sie gibt es eigene APIs wie WebHID oder Web Serial.
Betriebssystem: Unter Windows muss für das Gerät oft der WinUSB-Treiber geladen sein. Unter Linux können udev-Regeln nötig sein. Belegt ein anderer Treiber das Interface bereits, schlägt claimInterface() fehl.
Sicherheit: Direkter Hardwarezugriff ist sehr mächtig. Daten, die an das Gerät gehen, sollten nur aus vertrauenswürdigen Quellen stammen, und Firmware sollte nur signiert übertragen werden.

Siehe auch

USB Navigator.serial Navigator.hid Navigator.bluetooth Navigator.gpu