USBConfiguration.configurationValue — Eigenschaft · JavaScript-Referenz

Signatur

USBConfiguration.configurationValue

Beschreibung

Die schreibgeschützte Eigenschaft configurationValue eines USBConfiguration-Objekts enthält die Nummer, mit der das USB-Gerät diese Konfiguration kennzeichnet. Das ist das Feld bConfigurationValue aus dem Konfigurationsdeskriptor des Geräts, eine Ganzzahl zwischen 1 und 255.

Diesen Wert brauchst du vor allem für USBDevice.selectConfiguration(configurationValue). Erst wenn eine Konfiguration aktiv ist, kannst du Schnittstellen mit claimInterface() belegen und Daten übertragen. Die meisten Geräte haben nur eine Konfiguration mit dem Wert 1. Manche Geräte bieten aber mehrere an, zum Beispiel für verschiedene Stromsparmodi oder Funktionsprofile.

Der Wert ist kein Index im Array USBDevice.configurations. Er ist eine vom Gerät selbst vergebene Kennung. Suche die gewünschte Konfiguration deshalb immer über diese Eigenschaft und verlasse dich nicht auf die Position im Array.

Beispiele

Alle Konfigurationen eines Geräts auflisten

// Muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [] });

  for (const config of device.configurations) {
    console.log(
      `Wert: ${config.configurationValue}, Name: ${config.configurationName ?? '(ohne Namen)'}`
    );
  }
});

Wert: 1, Name: (ohne Namen)

Aktive Konfiguration prüfen und bei Bedarf auswählen

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

  // configuration ist null, solange keine Konfiguration aktiv ist
  if (device.configuration === null) {
    const first = device.configurations[0];
    await device.selectConfiguration(first.configurationValue);
  }

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

Aktive Konfiguration: 1

Bestimmte Konfiguration über ihren Wert suchen

const selectByValue = async (device, wantedValue) => {
  const config = device.configurations.find(
    (c) => c.configurationValue === wantedValue
  );

  if (!config) {
    throw new Error(`Konfiguration ${wantedValue} nicht vorhanden`);
  }

  await device.open();
  await device.selectConfiguration(config.configurationValue);
  return config;
};

// Aufruf, z. B.: await selectByValue(device, 2);

// Wichtig · Fallstricke

Kein Array-Index: configurationValue beginnt meist bei 1. Wenn du den Wert als Index für device.configurations verwendest, bekommst du einen Off-by-one-Fehler oder undefined.
Schreibgeschützt: Eine Zuweisung hat keine Wirkung (im Strict Mode wirft sie einen TypeError). Die Konfiguration wechselst du nur mit selectConfiguration().
Browser-Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Prüfe vorher mit 'usb' in navigator, ob die API verfügbar ist.
Sicherheit: Die API funktioniert nur in sicheren Kontexten (HTTPS) und nach ausdrücklicher Zustimmung des Nutzers über requestDevice(). Eine Permissions-Policy (usb) kann sie sperren, z. B. in iframes.
selectConfiguration() funktioniert nur bei geöffnetem Gerät (device.open()). Unter manchen Betriebssystemen blockieren Systemtreiber den Wechsel der Konfiguration.

Siehe auch

USBConfiguration USBConfiguration.configurationName USBConfiguration.interfaces USBDevice.selectConfiguration() USBDevice.configuration USBDevice.configurations PerformanceTimingConfidence.value