USBDevice.configurations — Eigenschaft · JavaScript-Referenz

Signatur

USBDevice.configurations

Beschreibung

Die schreibgeschützte Eigenschaft configurations der Schnittstelle USBDevice liefert ein Array von USBConfiguration-Objekten. Jedes davon steht für eine Konfiguration, die das Gerät in seinen Konfigurationsdeskriptoren meldet. Eine Konfiguration legt fest, welche Schnittstellen (USBInterface) und Endpunkte (USBEndpoint) verfügbar sind, und bestimmt zum Beispiel auch die Stromaufnahme.

Die meisten Geräte bieten nur eine Konfiguration an. Einige Geräte haben aber mehrere, etwa einen Modus mit Busversorgung und einen mit eigenem Netzteil oder verschiedene Funktionsprofile. Mit configurations sehen Sie sich alle Möglichkeiten an, bevor Sie mit USBDevice.selectConfiguration() eine davon auswählen und mit claimInterface() eine Schnittstelle belegen.

Die Eigenschaft steht sofort zur Verfügung, wenn Sie das USBDevice über navigator.usb.requestDevice() oder navigator.usb.getDevices() erhalten. Das Gerät muss dafür nicht geöffnet sein. Die gerade aktive Konfiguration steht dagegen in USBDevice.configuration (Einzahl).

Rückgabewert

Typ

USBConfiguration[]

Beschreibung

Ein eingefrorenes Array von USBConfiguration-Objekten. Jedes Objekt hat die Eigenschaften configurationValue, configurationName und interfaces.

Beispiele

Alle Konfigurationen eines Geräts auflisten

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
document.querySelector('#verbinden').addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [] });

  console.log(`${device.productName}: ${device.configurations.length} Konfiguration(en)`);
  for (const config of device.configurations) {
    console.log(`#${config.configurationValue} – ${config.configurationName ?? '(ohne Namen)'}`);
    console.log(`  Schnittstellen: ${config.interfaces.length}`);
  }
});

Arduino Uno: 1 Konfiguration(en) #1 – (ohne Namen) Schnittstellen: 2

Konfiguration mit einer bestimmten Schnittstellenklasse auswählen

const VENDOR_CLASS = 0xff; // herstellerspezifische Klasse

const connect = async (device) => {
  // passende Konfiguration über die Alternates der Schnittstellen suchen
  const config = device.configurations.find((c) =>
    c.interfaces.some((iface) =>
      iface.alternates.some((alt) => alt.interfaceClass === VENDOR_CLASS)
    )
  );
  if (!config) throw new Error('Keine passende Konfiguration gefunden');

  await device.open();
  if (device.configuration?.configurationValue !== config.configurationValue) {
    await device.selectConfiguration(config.configurationValue);
  }

  const iface = config.interfaces.find((i) =>
    i.alternates.some((alt) => alt.interfaceClass === VENDOR_CLASS)
  );
  await device.claimInterface(iface.interfaceNumber);
  return iface.interfaceNumber;
};

const [device] = await navigator.usb.getDevices();
if (device) console.log('Belegte Schnittstelle:', await connect(device));

Belegte Schnittstelle: 2

Endpunkte aller Konfigurationen tabellarisch ausgeben

const [device] = await navigator.usb.getDevices();

const rows = device.configurations.flatMap((config) =>
  config.interfaces.flatMap((iface) =>
    iface.alternate.endpoints.map((ep) => ({
      config: config.configurationValue,
      interface: iface.interfaceNumber,
      endpoint: ep.endpointNumber,
      direction: ep.direction,
      type: ep.type,
      packetSize: ep.packetSize
    }))
  )
);
console.table(rows);

┌─────────┬────────┬───────────┬──────────┬───────────┬────────┬────────────┐ │ (index) │ config │ interface │ endpoint │ direction │ type │ packetSize │ │ 0 │ 1 │ 0 │ 1 │ 'in' │ 'bulk' │ 64 │ │ 1 │ 1 │ 0 │ 2 │ 'out' │ 'bulk' │ 64 │ └─────────┴────────┴───────────┴──────────┴───────────┴────────┴────────────┘

// Wichtig · Fallstricke

Nicht mit configuration verwechseln: configurations enthält alle verfügbaren Konfigurationen. configuration ist die gerade aktive Konfiguration und ist null, solange keine ausgewählt wurde.
iface.alternate gibt es erst, wenn das Gerät geöffnet ist und die Konfiguration aktiv ist. Bei inaktiven Konfigurationen verwenden Sie besser iface.alternates.
configurationName kann null sein, wenn das Gerät keinen String-Deskriptor mitliefert.
Browser-Unterstützung: Die WebUSB-API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera), nicht in Firefox und Safari. Sie setzt einen sicheren Kontext (HTTPS) voraus. requestDevice() muss durch eine Nutzeraktion ausgelöst werden, und die Permissions-Policy usb kann die API in iframes sperren. Prüfen Sie vorher mit 'usb' in navigator, ob die API vorhanden ist.
Geräte mit geschützten Klassen (z. B. HID, Massenspeicher, Audio) blockiert der Browser. Deren Schnittstellen können Sie nicht belegen, auch wenn sie in configurations auftauchen.

Siehe auch

USBDevice USBDevice.configuration USBDevice.selectConfiguration() USBDevice.claimInterface() USBConfiguration USB.requestDevice() PushSubscription.options