USB.getDevices() — Methode · JavaScript-Referenz

Signatur

USB.prototype.getDevices()

Beschreibung

Die Methode navigator.usb.getDevices() gehört zur WebUSB-API. Sie gibt alle aktuell angeschlossenen USB-Geräte zurück, für die der Nutzer dem aktuellen Ursprung (Origin) bereits früher den Zugriff erlaubt hat, meist über navigator.usb.requestDevice(). Es erscheint dabei kein Auswahldialog.

Typischer Einsatzzweck: Beim Laden einer Seite stellt man automatisch wieder eine Verbindung zu einem Gerät her, das schon gekoppelt ist, zum Beispiel einem Mikrocontroller, einem Kartenleser oder einem Messgerät. Der Nutzer muss es dann nicht erneut auswählen. Neue Geräte ohne Berechtigung tauchen in der Liste nicht auf. Dafür braucht man immer requestDevice() mit einer Nutzerinteraktion.

Die zurückgegebenen USBDevice-Objekte sind noch nicht geöffnet. Bevor man Daten überträgt, ruft man open() auf, wählt mit selectConfiguration() eine Konfiguration und reserviert mit claimInterface() ein Interface. Wenn ein Gerät später an- oder abgesteckt wird, erfährt man das über die Events connect und disconnect an navigator.usb.

Rückgabewert

Typ

Promise<USBDevice[]>

Beschreibung

Ein Promise, das mit einem Array von USBDevice-Objekten auflöst. Das Array ist leer, wenn kein berechtigtes Gerät angeschlossen ist.

Beispiele

Gekoppelte Geräte auflisten

const listDevices = async () => {
  if (!('usb' in navigator)) {
    console.warn('WebUSB wird nicht unterstützt');
    return;
  }
  const devices = await navigator.usb.getDevices();
  console.log(`Gefundene Geräte: ${devices.length}`);
  for (const d of devices) {
    console.log(`${d.productName} (VID 0x${d.vendorId.toString(16)}, PID 0x${d.productId.toString(16)})`);
  }
};

listDevices();

Gefundene Geräte: 1 Arduino Leonardo (VID 0x2341, PID 0x8036)

Beim Seitenladen automatisch wieder verbinden

const VENDOR_ID = 0x2341;

const connect = async (device) => {
  await device.open();
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }
  await device.claimInterface(2);
  console.log('Verbunden mit', device.productName);
  return device;
};

window.addEventListener('load', async () => {
  const devices = await navigator.usb.getDevices();
  const known = devices.find((d) => d.vendorId === VENDOR_ID);
  if (known) {
    await connect(known);
  } else {
    console.log('Kein gekoppeltes Gerät – bitte Button „Verbinden“ klicken');
  }
});

// Erstes Koppeln nur per Nutzerinteraktion
document.querySelector('#connect').addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [{ vendorId: VENDOR_ID }] });
  await connect(device);
});

Verbunden mit Arduino Leonardo

Geräteliste bei An- und Abstecken aktualisieren

const render = async () => {
  const devices = await navigator.usb.getDevices();
  const list = document.querySelector('#devices');
  list.replaceChildren(...devices.map((d) => {
    const li = document.createElement('li');
    li.textContent = d.productName ?? 'Unbekanntes Gerät';
    return li;
  }));
};

navigator.usb.addEventListener('connect', render);
navigator.usb.addEventListener('disconnect', render);
render();

// Wichtig · Fallstricke

Browser-Unterstützung: Nur Chromium-Browser auf dem Desktop und unter Android (Chrome, Edge, Opera). Firefox und Safari unterstützen WebUSB nicht. Prüfen Sie daher immer vorher mit 'usb' in navigator.
Sicherer Kontext: Die API steht nur über HTTPS oder localhost zur Verfügung. In iframes muss die Permissions-Policy usb erlaubt sein, sonst wird das Promise mit einem SecurityError abgelehnt.
Die Methode findet keine neuen Geräte. Ohne vorheriges requestDevice() ist das Array leer. Nutzer können Berechtigungen jederzeit in den Website-Einstellungen widerrufen. Programmatisch geht das mit USBDevice.forget().
Die Geräte werden geschlossen zurückgegeben (device.opened === false). Vor jeder Übertragung ist open() nötig.
Geräteklassen, die das Betriebssystem oder der Browser schützt (z. B. HID-Tastaturen, Massenspeicher, Audio/Video), sind über WebUSB nicht zugänglich. Unter Windows braucht das Gerät außerdem einen WinUSB-kompatiblen Treiber.
Die Methode steht auch in Dedicated Workern und Service Workern (Erweiterungen) über navigator.usb zur Verfügung. requestDevice() gibt es dort dagegen nicht.

Siehe auch

USB USBDevice USBDevice.open() PushMessageData.json() USB.requestDevice()