USB — Schnittstelle · JavaScript-Referenz

Signatur

interface USB extends EventTarget

Beschreibung

Die Schnittstelle USB ist der Einstieg in die WebUSB API. Eine Instanz wird nicht selbst erzeugt, sondern steht als navigator.usb bereit (in Dedicated Workern auch als WorkerNavigator.usb). Damit kann eine Webseite direkt mit USB-Geräten sprechen, für die es keinen Standardtreiber gibt, etwa Mikrocontroller-Boards, Messgeräte, Kassensysteme oder Programmiergeräte für Firmware.

Die wichtigsten Bestandteile:

requestDevice(options): Öffnet eine Geräteauswahl des Browsers. Der Aufruf muss durch eine Nutzeraktion (z. B. einen Klick) ausgelöst werden. Die Filter legen fest, welche Geräte in der Auswahl erscheinen. Das Ergebnis ist ein Promise<USBDevice>.
getDevices(): Liefert ein Promise<USBDevice[]> mit allen angeschlossenen Geräten, für die die Seite bereits eine Berechtigung hat. Eine Nutzeraktion ist dafür nicht nötig.
Das Event connect bzw. die Eigenschaft onconnect: Wird ausgelöst, wenn ein berechtigtes Gerät angeschlossen wird.
Das Event disconnect bzw. die Eigenschaft ondisconnect: Wird ausgelöst, wenn ein solches Gerät getrennt wird.

Typischer Ablauf: Zuerst prüft man mit getDevices(), ob schon ein berechtigtes Gerät vorhanden ist. Falls nicht, ruft man per Button-Klick requestDevice() auf. Danach folgen am zurückgegebenen USBDevice die Schritte open(), selectConfiguration(), claimInterface() und schließlich transferIn()/transferOut().

Parameter

Name	Typ	Default	Beschreibung
$options.filters Pflicht	Array<USBDeviceFilter>		Nur für `requestDevice()`: Liste von Filtern mit den optionalen Schlüsseln `vendorId`, `productId`, `classCode`, `subclassCode`, `protocolCode` und `serialNumber`. Ein leeres Array `[]` zeigt alle Geräte an.
$options.exclusionFilters	Array<USBDeviceFilter>	[]	Nur für `requestDevice()`: Geräte, die trotz passender Filter nicht angezeigt werden sollen (neuere Chromium-Versionen).

Rückgabewert

Typ

USB

Beschreibung

navigator.usb liefert das USB-Objekt. Seine Methoden geben Promise<USBDevice> (requestDevice) bzw. Promise<USBDevice[]> (getDevices) zurück.

Beispiele

Unterstützung prüfen und Gerät per Klick anfordern

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

button.addEventListener('click', async () => {
  if (!('usb' in navigator)) {
    console.log('WebUSB wird nicht unterstützt.');
    return;
  }
  try {
    // Nur Arduino-Geräte (Hersteller-ID 0x2341) anzeigen
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }]
    });
    console.log(`Ausgewählt: ${device.manufacturerName} ${device.productName}`);
  } catch (err) {
    // NotFoundError, wenn der Nutzer den Dialog abbricht
    console.log('Kein Gerät gewählt:', err.name);
  }
});

Ausgewählt: Arduino LLC Arduino Leonardo

Bereits berechtigte Geräte beim Laden wiederverwenden

const init = async () => {
  const devices = await navigator.usb.getDevices();
  console.log(`${devices.length} berechtigte(s) Gerät(e) gefunden`);
  devices.forEach((d) => {
    console.log(d.productName, d.vendorId.toString(16), d.productId.toString(16));
  });
};

init();

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

Anschließen und Trennen überwachen

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

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

// Alternativ über die on-Eigenschaft
navigator.usb.ondisconnect = (event) => {
  console.log('Getrennt:', event.device.productName);
};

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

Angeschlossen: Arduino Leonardo Getrennt: Arduino Leonardo

Gerät öffnen und Daten senden

const sendeBefehl = async (device, text) => {
  await device.open();
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }
  await device.claimInterface(2);
  const data = new TextEncoder().encode(text);
  const result = await device.transferOut(4, data); // Endpunkt 4
  console.log('Status:', result.status, 'Bytes:', result.bytesWritten);
  await device.close();
};

document.querySelector('#senden').addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [{ vendorId: 0x2341 }] });
  await sendeBefehl(device, 'LED:ON\n');
});

Status: ok Bytes: 7

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) am Desktop und in Chrome für Android. Firefox und Safari unterstützen die API nicht. Deshalb vor der Nutzung immer mit 'usb' in navigator prüfen.
Sicherer Kontext: Die API steht nur über HTTPS oder localhost zur Verfügung. In iframes muss die Berechtigungsrichtlinie usb erlaubt sein, z. B. mit allow="usb".
Nutzeraktion: requestDevice() ohne vorherige Nutzeraktion wird mit einem SecurityError abgelehnt. Bricht der Nutzer die Auswahl ab, wird das Promise mit einem NotFoundError abgelehnt.
Geschützte Geräteklassen: Tastaturen, Mäuse und andere HID-Geräte, Massenspeicher, Audio- und Videogeräte sowie Smartcards sind gesperrt. Für diese Geräte gibt es eigene APIs wie WebHID oder Web Serial.
Treiberkonflikte: Hat das Betriebssystem bereits einen Treiber für das Gerät geladen (unter Windows häufig), schlägt claimInterface() mit einem NetworkError fehl. Unter Windows kann ein WinUSB-Treiber nötig sein.
Sicherheit: Direkter USB-Zugriff ist heikel. Deshalb nur Geräte-Filter anfordern, die wirklich gebraucht werden. Mit device.forget() kann eine Berechtigung wieder entzogen werden.

Siehe auch

Serial HID Navigator CSS URL