USBDevice.configuration — Eigenschaft · JavaScript-Referenz

Signatur

USBDevice.configuration

Beschreibung

Die Eigenschaft configuration eines USBDevice-Objekts gibt die derzeit aktive Konfiguration des Geräts als USBConfiguration-Objekt zurück. Eine USB-Konfiguration beschreibt, welche Interfaces und Endpunkte das Gerät gerade bereitstellt. Die meisten Geräte haben nur eine Konfiguration, manche bieten aber mehrere an, zum Beispiel für verschiedene Stromsparmodi oder Betriebsarten.

Ist dem Gerät noch keine Konfiguration zugewiesen, ist der Wert null. Dann rufen Sie USBDevice.selectConfiguration() auf, bevor Sie mit claimInterface() ein Interface belegen oder Daten übertragen. Das übliche Vorgehen ist: open() aufrufen, configuration prüfen, falls nötig eine Konfiguration wählen und danach das gewünschte Interface belegen.

Über das zurückgegebene Objekt kommen Sie an configurationValue (die Nummer der Konfiguration), configurationName (optionaler Klartextname) und interfaces (ein Array aus USBInterface-Objekten). So können Sie zur Laufzeit den passenden Interface- und Endpunkt-Index ermitteln, statt ihn fest in den Code zu schreiben.

Rückgabewert

Typ

USBConfiguration | null

Beschreibung

Die aktive Konfiguration des Geräts oder null, wenn keine Konfiguration ausgewählt ist.

Beispiele

Gerät öffnen und bei Bedarf eine Konfiguration 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();

  if (device.configuration === null) {
    // Noch keine Konfiguration aktiv: die erste auswählen
    await device.selectConfiguration(1);
  }

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

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

Aktive Konfiguration: 1

Interfaces und Endpunkte der aktiven Konfiguration auflisten

const describeConfiguration = (device) => {
  const config = device.configuration;
  if (!config) {
    console.log('Keine Konfiguration ausgewählt');
    return;
  }
  console.log(`Konfiguration ${config.configurationValue} (${config.configurationName ?? 'ohne Namen'})`);
  for (const iface of config.interfaces) {
    const alt = iface.alternate;
    const endpoints = alt.endpoints
      .map(ep => `${ep.direction}:${ep.endpointNumber}/${ep.type}`)
      .join(', ');
    console.log(`  Interface ${iface.interfaceNumber}, Klasse 0x${alt.interfaceClass.toString(16)}: ${endpoints}`);
  }
};

const [device] = await navigator.usb.getDevices();
if (device) {
  await device.open();
  describeConfiguration(device);
}

Konfiguration 1 (ohne Namen) Interface 0, Klasse 0x2: in:1/interrupt Interface 1, Klasse 0xa: out:2/bulk, in:3/bulk

Passenden Bulk-Endpunkt finden und Daten senden

const sendBytes = async (device, bytes) => {
  const iface = device.configuration.interfaces.find(i =>
    i.alternate.endpoints.some(ep => ep.type === 'bulk' && ep.direction === 'out')
  );
  if (!iface) throw new Error('Kein Bulk-OUT-Endpunkt gefunden');

  const outEp = iface.alternate.endpoints.find(
    ep => ep.type === 'bulk' && ep.direction === 'out'
  );
  await device.claimInterface(iface.interfaceNumber);
  const result = await device.transferOut(outEp.endpointNumber, bytes);
  console.log(result.status, result.bytesWritten);
};

await sendBytes(device, new TextEncoder().encode('PING'));

ok 4

// Wichtig · Fallstricke

Kann null sein: Greifen Sie nicht ohne Prüfung auf device.configuration.interfaces zu. Vor dem ersten selectConfiguration() oder bei unkonfigurierten Geräten wird sonst ein TypeError geworfen.
Die MDN-Beschreibung spricht vom „ausgewählten Interface“. Gemeint ist aber die ausgewählte Konfiguration. Die Interfaces stehen in configuration.interfaces.
Die Eigenschaft ist schreibgeschützt. Eine andere Konfiguration wählen Sie nur mit selectConfiguration(), und dafür muss das Gerät vorher mit open() geöffnet sein. Alle verfügbaren Konfigurationen stehen in USBDevice.configurations.
Kompatibilität: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera), und zwar auf dem Desktop und in Chrome für Android. Firefox und Safari unterstützen es nicht. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung, und eine Berechtigungsrichtlinie (usb) kann sie in iframes sperren.
Unter Windows braucht das Gerät einen WinUSB-kompatiblen Treiber. Geräte, die das Betriebssystem schon belegt hat (z. B. HID-Tastaturen oder Massenspeicher), lassen sich oft nicht belegen.

Siehe auch

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