USBConfiguration — Schnittstelle · JavaScript-Referenz

Signatur

interface USBConfiguration

Beschreibung

Ein USB-Gerät kann mehrere Konfigurationen anbieten. Jede legt fest, welche Schnittstellen (Interfaces) und Endpunkte das Gerät bereitstellt und wie viel Strom es braucht. Die WebUSB API stellt jede dieser Konfigurationen als USBConfiguration-Objekt dar. Du bekommst diese Objekte über USBDevice.configurations (alle verfügbaren Konfigurationen) und USBDevice.configuration (die aktuell ausgewählte Konfiguration oder null).

Das Interface ist nur lesbar und hat drei Eigenschaften:

configurationValue (number): die Konfigurationsnummer aus dem Deskriptor, bConfigurationValue. Diesen Wert übergibst du an USBDevice.selectConfiguration().
configurationName (string | null): der Name aus dem String-Deskriptor, falls das Gerät einen liefert.
interfaces (USBInterface[]): alle Schnittstellen dieser Konfiguration. Jede davon kann mit claimInterface() reserviert werden.

In der Praxis brauchst du USBConfiguration vor allem, um nach dem Öffnen eines Geräts die richtige Konfiguration zu finden und auszuwählen. Danach suchst du darin die passende Schnittstelle, zum Beispiel eine herstellerspezifische Schnittstelle der Klasse 0xFF, und die dazugehörigen Endpunkte für transferIn() und transferOut().

Parameter

Name	Typ	Default	Beschreibung
$device Pflicht	USBDevice		Nur für den Konstruktor `new USBConfiguration(device, configurationValue)`: das Gerät, zu dem die Konfiguration gehört.
$configurationValue Pflicht	number		Nur für den Konstruktor: die Nummer der Konfiguration, wie sie im Konfigurationsdeskriptor steht (`bConfigurationValue`).

Rückgabewert

Typ

USBConfiguration

Beschreibung

Ein Objekt, das nur gelesen werden kann, mit den Eigenschaften configurationValue, configurationName und interfaces.

Beispiele

Alle Konfigurationen eines Geräts auflisten

// Muss von einer Nutzeraktion ausgelöst werden, z. B. einem Klick
document.querySelector('#connect').addEventListener('click', async () => {
  const device = await navigator.usb.requestDevice({ filters: [{ vendorId: 0x2341 }] });

  for (const config of device.configurations) {
    console.log(
      `Konfiguration ${config.configurationValue}: ${config.configurationName ?? '(ohne Namen)'}`,
      `– ${config.interfaces.length} Schnittstelle(n)`
    );
  }
});

Konfiguration 1: (ohne Namen) – 2 Schnittstelle(n)

Konfiguration auswählen und Schnittstelle reservieren

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

  // Manche Geräte haben nach open() noch keine aktive Konfiguration
  if (device.configuration === null) {
    await device.selectConfiguration(device.configurations[0].configurationValue);
  }

  const config = device.configuration; // USBConfiguration
  // Herstellerspezifische Schnittstelle (Klasse 0xFF) suchen
  const iface = config.interfaces.find(
    (i) => i.alternate.interfaceClass === 0xff
  );
  if (!iface) throw new Error('Keine passende Schnittstelle gefunden');

  await device.claimInterface(iface.interfaceNumber);
  console.log('Schnittstelle', iface.interfaceNumber, 'reserviert');
  return iface;
};

Schnittstelle 2 reserviert

Endpunkte einer Konfiguration analysieren

const describeConfig = (config) =>
  config.interfaces.map((iface) => ({
    nummer: iface.interfaceNumber,
    klasse: iface.alternate.interfaceClass,
    endpunkte: iface.alternate.endpoints.map(
      (ep) => `${ep.direction} #${ep.endpointNumber} (${ep.type})`
    )
  }));

const [device] = await navigator.usb.getDevices();
if (device) {
  console.table(describeConfig(device.configurations[0]));
}

[{ nummer: 0, klasse: 255, endpunkte: ['in #1 (bulk)', 'out #2 (bulk)'] }]

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-basierten Browsern auf dem Desktop und unter Android. Firefox und Safari unterstützen die API nicht. Prüfe deshalb vorher mit 'usb' in navigator, ob sie verfügbar ist.
Die API funktioniert nur in einem sicheren Kontext (HTTPS oder localhost). Die Berechtigungsrichtlinie usb kann sie außerdem sperren, zum Beispiel in iframes.
device.configuration kann null sein, wenn das Gerät noch nicht konfiguriert ist. Rufe dann selectConfiguration() auf, bevor du claimInterface() verwendest.
configurationName ist oft null, weil viele Geräte keinen String-Deskriptor liefern. Verlass dich nicht darauf.
Den Konstruktor brauchst du praktisch nie. Die Objekte liefert der Browser selbst. Schnittstellen, die das Betriebssystem schützt (z. B. HID, Massenspeicher oder Audio), lassen sich trotz Auflistung in interfaces nicht reservieren.
Die Konfiguration zu wechseln setzt alle reservierten Schnittstellen zurück.

Siehe auch

CSSAnimation UserActivation Animation Navigation Notification