USBDevice.reset() — Methode · JavaScript-Referenz

Signatur

USBDevice.prototype.reset()

Beschreibung

Die Methode reset() der USBDevice-Schnittstelle (WebUSB-API) löst ein USB-Reset des angeschlossenen Geräts aus. Alle laufenden Operationen der Seite, etwa transferIn(), transferOut() oder controlTransferIn(), werden abgebrochen, und ihre Promises werden zurückgewiesen. Das von reset() gelieferte Promise wird erst erfüllt, wenn das Zurücksetzen abgeschlossen ist.

Sinnvoll ist das vor allem, wenn ein Gerät nicht mehr antwortet, ein Endpunkt blockiert ist (Stall) oder die Firmware in einem unklaren Zustand hängt. Statt den Nutzer zu bitten, das Kabel ab- und wieder anzustecken, lässt sich das Gerät per Software neu initialisieren.

Voraussetzung ist ein geöffnetes Gerät (await device.open()). Nach dem Reset muss man die Konfiguration meist erneut auswählen (selectConfiguration()) und das Interface neu beanspruchen (claimInterface()), denn der Gerätezustand wird auf den Ausgangszustand zurückgesetzt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Gerät zurückgesetzt ist. Es wird mit einer DOMException zurückgewiesen, z. B. InvalidStateError, wenn das Gerät nicht geöffnet ist, oder NetworkError, wenn das Zurücksetzen fehlschlägt oder das Gerät getrennt wurde.

Beispiele

Gerät auswählen, öffnen und zurücksetzen

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

button.addEventListener('click', async () => {
  try {
    // requestDevice() braucht eine Nutzeraktion (Klick)
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }]
    });
    await device.open();
    await device.reset();
    console.log(`${device.productName} wurde zurückgesetzt`);
  } catch (err) {
    console.error('Reset fehlgeschlagen:', err.name, err.message);
  }
});

Arduino Uno wurde zurückgesetzt

Wiederherstellung nach blockierter Übertragung

const readWithRecovery = async (device, endpoint, length) => {
  try {
    return await device.transferIn(endpoint, length);
  } catch (err) {
    console.warn('Übertragung fehlgeschlagen, setze Gerät zurück …', err.name);
    await device.reset();
    // Nach dem Reset Konfiguration und Interface neu einrichten
    if (device.configuration === null) {
      await device.selectConfiguration(1);
    }
    await device.claimInterface(0);
    return device.transferIn(endpoint, length);
  }
};

const [device] = await navigator.usb.getDevices();
if (device) {
  await device.open();
  await device.selectConfiguration(1);
  await device.claimInterface(0);
  const result = await readWithRecovery(device, 1, 64);
  console.log('Status:', result.status, 'Bytes:', result.data?.byteLength);
}

Status: ok Bytes: 64

Laufende Übertragungen werden abgebrochen

const [device] = await navigator.usb.getDevices();
await device.open();
await device.selectConfiguration(1);
await device.claimInterface(0);

// Wartet auf Daten, die vielleicht nie kommen
const pending = device.transferIn(1, 64)
  .then(() => console.log('Daten empfangen'))
  .catch(err => console.log('Abgebrochen:', err.name));

await device.reset();
await pending;
console.log('Reset abgeschlossen');

Abgebrochen: AbortError Reset abgeschlossen

// Wichtig · Fallstricke

Browser-Kompatibilität: WebUSB gilt als experimentell und steht nur in Chromium-Browsern (Chrome, Edge, Opera) zur Verfügung. Firefox und Safari unterstützen WebUSB nicht. Die API funktioniert nur in sicheren Kontexten (HTTPS) und lässt sich per Permissions-Policy usb sperren.
Das Gerät muss vorher mit open() geöffnet sein, sonst wird das Promise mit InvalidStateError zurückgewiesen.
Manche Geräte trennen sich beim Reset kurz vom Bus und melden sich neu an (Re-Enumeration). Dann wird das USBDevice-Objekt ungültig, und es feuert ein disconnect-Ereignis auf navigator.usb. Deshalb sollte man connect/disconnect abfangen und bei Bedarf ein neues Geräteobjekt verwenden.
Unter Windows kann reset() je nach Treiber (z. B. WinUSB) eingeschränkt sein oder fehlschlagen. Unter Android erlaubt nicht jede Plattform einen Reset.
Ein Reset betrifft das ganze Gerät, also auch alle anderen Interfaces. Einzelne blockierte Endpunkte sollte man besser mit clearHalt() freigeben.

Siehe auch

USBDevice USBDevice.open() USBDevice.close() USBDevice.clearHalt() USBDevice.selectConfiguration() USBDevice.claimInterface() USBDevice.transferIn() USB.requestDevice()