USBDevice.open() — Methode · JavaScript-Referenz

Signatur

USBDevice.prototype.open()

Beschreibung

Mit USBDevice.open() öffnet man eine Sitzung mit einem USB-Gerät, das die Seite vorher über navigator.usb.requestDevice() oder navigator.usb.getDevices() erhalten hat. Erst danach kann man eine Konfiguration wählen (selectConfiguration()), ein Interface beanspruchen (claimInterface()) und Daten übertragen, etwa mit transferIn(), transferOut() oder controlTransferIn()/controlTransferOut().

Nach dem erfolgreichen Öffnen hat die Eigenschaft device.opened den Wert true. Ist das Gerät schon geöffnet, wird das Promise sofort erfüllt. Wurde das Gerät inzwischen getrennt oder hat das Betriebssystem den Zugriff verweigert, wird das Promise mit einer DOMException abgelehnt.

Der übliche Ablauf ist: Gerät anfordern → open() → selectConfiguration() → claimInterface() → Übertragungen → releaseInterface() → close(). Schließe die Sitzung mit close(), sobald du fertig bist, damit andere Tabs oder Programme wieder auf das Gerät zugreifen können.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Sitzung steht. Abgelehnt wird es z. B. mit NotFoundError (Gerät getrennt), SecurityError (Zugriff durch Richtlinie oder Berechtigungsrichtlinie blockiert) oder NetworkError/InvalidStateError (Gerät belegt oder Öffnen fehlgeschlagen).

Beispiele

Gerät anfordern und öffnen

// Muss in einem Klick-Handler laufen (Nutzergeste nötig)
document.querySelector('#connect').addEventListener('click', async () => {
  try {
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }] // z. B. Arduino
    });
    await device.open();
    console.log(`Geöffnet: ${device.productName}, opened = ${device.opened}`);
  } catch (err) {
    console.error('Verbindung fehlgeschlagen:', err.name, err.message);
  }
});

Geöffnet: Arduino Leonardo, opened = true

Vollständige Sitzung mit Konfiguration, Interface und Datenübertragung

const sendCommand = async (device, text) => {
  if (!device.opened) {
    await device.open();
  }
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }
  await device.claimInterface(2);

  try {
    const data = new TextEncoder().encode(text);
    const result = await device.transferOut(4, data); // Endpunkt 4
    console.log('Status:', result.status, 'Bytes:', result.bytesWritten);
  } finally {
    await device.releaseInterface(2);
    await device.close();
  }
};

// Bereits freigegebene Geräte ohne erneuten Dialog verwenden
const [device] = await navigator.usb.getDevices();
if (device) {
  await sendCommand(device, 'LED ON\n');
}

Status: ok Bytes: 7

Automatisch öffnen, wenn ein freigegebenes Gerät angesteckt wird

navigator.usb.addEventListener('connect', async (event) => {
  const { device } = event;
  try {
    await device.open();
    console.log('Neu verbunden und geöffnet:', device.productName);
  } catch (err) {
    if (err.name === 'SecurityError') {
      console.warn('Zugriff durch Richtlinie blockiert.');
    } else {
      console.error('Öffnen fehlgeschlagen:', err);
    }
  }
});

navigator.usb.addEventListener('disconnect', (event) => {
  console.log('Getrennt:', event.device.productName);
});

Neu verbunden und geöffnet: Arduino Leonardo

// Wichtig · Fallstricke

Browser-Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera, auch Chrome für Android). Firefox und Safari unterstützen es nicht. Prüfe vorher mit 'usb' in navigator.
Nur im sicheren Kontext: Die API steht nur unter HTTPS (oder localhost) zur Verfügung. In iframes muss die Berechtigungsrichtlinie usb erlaubt sein (allow="usb").
Gerät belegt: Unter Windows braucht das Gerät meist den WinUSB-Treiber. Hat ein nativer Treiber des Betriebssystems das Gerät (oder ein Interface) schon in Beschlag genommen, schlägt open() oder spätestens claimInterface() fehl. Das betrifft z. B. HID-Tastaturen oder USB-Massenspeicher.
Geschützte Klassen: Chromium sperrt bestimmte Geräteklassen (Audio, Video, HID, Massenspeicher, Smartcard u. a.) für WebUSB. Dafür gibt es eigene APIs wie WebHID.
open() wählt keine Konfiguration aus. Prüfe device.configuration und rufe bei Bedarf selectConfiguration() auf, bevor du ein Interface beanspruchst.
Rufe am Ende immer close() auf, am besten in einem finally-Block. Sonst bleibt das Gerät bis zum Schließen des Tabs gesperrt.

Siehe auch

USBDevice USBDevice.close() USBDevice.opened USBDevice.selectConfiguration() USBDevice.claimInterface() USBDevice.transferOut() USB.requestDevice() USB.getDevices()