USBDevice.selectConfiguration() — Methode · JavaScript-Referenz

Signatur

USBDevice.prototype.selectConfiguration(configurationValue)

Beschreibung

Ein USB-Gerät kann mehrere Konfigurationen anbieten. Jede legt eigene Interfaces, Endpunkte und Stromanforderungen fest. Mit selectConfiguration() aktivierst du eine davon. Erst danach kannst du mit claimInterface() ein Interface belegen und Daten per transferIn() und transferOut() übertragen.

Das Gerät muss vorher mit open() geöffnet sein. Welche Konfigurationen es gibt, steht in device.configurations. Die gerade aktive Konfiguration liefert device.configuration. Dort steht null, wenn noch keine ausgewählt ist. Als Argument übergibst du den Wert configurationValue eines USBConfiguration-Objekts, nicht seinen Index im Array.

Die meisten Geräte haben nur eine Konfiguration mit dem Wert 1. Deshalb ruft man die Methode oft nur auf, wenn device.configuration === null ist. So vermeidest du ein unnötiges Zurücksetzen des Geräts.

Parameter

Name	Typ	Default	Beschreibung
$configurationValue Pflicht	number		Der `bConfigurationValue` der gewünschten Konfiguration (Wert aus `USBConfiguration.configurationValue`, meist `1`). Es ist nicht der Index im Array.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das sich ohne Wert auflöst, sobald die Konfiguration aktiv ist. Es wird abgelehnt mit InvalidStateError, wenn das Gerät nicht geöffnet ist, mit NotFoundError, wenn es keine Konfiguration mit diesem Wert gibt, und mit NetworkError, wenn die Übertragung scheitert oder das Gerät getrennt wurde.

Beispiele

Gerät öffnen und Standardkonfiguration wählen

const connectDevice = async () => {
  // Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
  const device = await navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341 }]
  });
  await device.open();

  // Nur wählen, wenn noch keine Konfiguration aktiv ist
  if (device.configuration === null) {
    await device.selectConfiguration(1);
  }

  await device.claimInterface(0);
  console.log('Aktive Konfiguration:', device.configuration.configurationValue);
  return device;
};

document.querySelector('#connect').addEventListener('click', connectDevice);

Aktive Konfiguration: 1

Konfiguration anhand ihrer Interfaces auswählen

const selectVendorConfig = async (device) => {
  await device.open();

  // Konfiguration suchen, die ein herstellerspezifisches Interface (Klasse 0xFF) enthält
  const config = device.configurations.find((cfg) =>
    cfg.interfaces.some((iface) =>
      iface.alternates.some((alt) => alt.interfaceClass === 0xff)
    )
  );

  if (!config) throw new Error('Keine passende Konfiguration gefunden');

  await device.selectConfiguration(config.configurationValue);
  console.log(`Gewählt: ${config.configurationName ?? config.configurationValue}`);
};

Gewählt: 1

Fehlerbehandlung

const safeSelect = async (device, value) => {
  try {
    if (!device.opened) await device.open();
    await device.selectConfiguration(value);
    return true;
  } catch (err) {
    // z. B. NotFoundError bei ungültigem Wert
    console.error(`${err.name}: ${err.message}`);
    return false;
  }
};

const [device] = await navigator.usb.getDevices();
if (device) await safeSelect(device, 5);

NotFoundError: The configuration value provided is not supported by the device.

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB funktioniert nur in Chromium-Browsern (Chrome, Edge, Opera) und nur in einem sicheren Kontext (HTTPS oder localhost). Firefox und Safari unterstützen es nicht. Prüfe die Unterstützung vorher mit 'usb' in navigator.
Rufst du die Methode vor open() auf, wird das Promise mit InvalidStateError abgelehnt.
Übergib den configurationValue, nicht den Array-Index. Der Wert ist in der Regel 1-basiert.
Ein Konfigurationswechsel gibt alle belegten Interfaces frei. Du musst claimInterface() danach erneut aufrufen.
Unter Windows kann der Betriebssystem-Treiber (z. B. nicht WinUSB) den Wechsel verhindern. Das äußert sich meist als NetworkError oder SecurityError.
Geräte bestimmter geschützter Klassen (z. B. HID, Massenspeicher) blockiert Chrome in WebUSB.

Siehe auch

USBDevice USBDevice.open() USBDevice.claimInterface() USBDevice.configuration USBDevice.configurations USBConfiguration USB.requestDevice()