USBDevice.deviceVersionMajor — Eigenschaft · JavaScript-Referenz

Signatur

USBDevice.deviceVersionMajor

Beschreibung

USBDevice.deviceVersionMajor ist Teil der WebUSB-API. Die Eigenschaft gibt den Hauptteil der vom Hersteller festgelegten Geräteversion zurück. Der Wert stammt aus dem Feld bcdDevice des USB-Gerätedeskriptors, das die Version im Format Major.Minor.Subminor ablegt. Das obere Byte ergibt deviceVersionMajor, das obere und das untere Halbbyte (Nibble) des unteren Bytes ergeben deviceVersionMinor und deviceVersionSubminor.

In der Praxis entspricht die Geräteversion oft der Firmware- oder Hardware-Revision des Geräts. Damit kann eine Webanwendung prüfen, ob ein Gerät ein bestimmtes Protokoll unterstützt, ob ein Firmware-Update nötig ist oder ob für ältere Revisionen ein anderer Codepfad gebraucht wird.

Die Eigenschaft ist schreibgeschützt und kann gelesen werden, sobald ein USBDevice-Objekt vorliegt, etwa über navigator.usb.requestDevice() oder navigator.usb.getDevices(). Das Gerät muss dafür nicht mit open() geöffnet sein, denn die Deskriptordaten stehen schon vorher bereit.

Rückgabewert

Typ

number

Beschreibung

Eine Ganzzahl zwischen 0 und 255: das obere Byte des Feldes bcdDevice, also die Hauptversion des Geräts.

Beispiele

Geräteversion nach Auswahl durch den Nutzer anzeigen

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

button.addEventListener('click', async () => {
  try {
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }] // Beispiel: Arduino
    });
    const version = `${device.deviceVersionMajor}.${device.deviceVersionMinor}.${device.deviceVersionSubminor}`;
    console.log(`${device.productName}: Geräteversion ${version}`);
  } catch (err) {
    console.warn('Kein Gerät ausgewählt:', err.message);
  }
});

Arduino Uno: Geräteversion 1.0.0

Mindestversion der Firmware prüfen

const MIN_MAJOR = 2;

const checkFirmware = async () => {
  const devices = await navigator.usb.getDevices();
  for (const device of devices) {
    if (device.deviceVersionMajor < MIN_MAJOR) {
      console.warn(`${device.productName ?? 'Unbekanntes Gerät'} braucht ein Firmware-Update (aktuell v${device.deviceVersionMajor}).`);
    } else {
      console.log(`${device.productName}: Firmware ist aktuell.`);
    }
  }
};

checkFirmware();

Mein Gerät braucht ein Firmware-Update (aktuell v1).

Protokollvariante abhängig von der Hauptversion wählen

const selectProtocol = (device) => {
  switch (device.deviceVersionMajor) {
    case 1:
      return 'legacy';
    case 2:
    case 3:
      return 'v2';
    default:
      return 'unknown';
  }
};

navigator.usb.addEventListener('connect', ({ device }) => {
  console.log('Neues Gerät, Protokoll:', selectProtocol(device));
});

Neues Gerät, Protokoll: v2

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, Chrome für Android). Firefox und Safari unterstützen die API nicht. Prüfe die Verfügbarkeit mit 'usb' in navigator.
Nur in sicheren Kontexten: Die API steht nur über HTTPS oder auf localhost zur Verfügung. Mit einer Permissions-Policy (usb) lässt sie sich in iframes sperren.
BCD-Kodierung: bcdDevice ist laut USB-Spezifikation als BCD (binär kodierte Dezimalzahl) gedacht. Viele Hersteller halten sich aber nicht daran. Der Wert von deviceVersionMajor sagt deshalb nur so viel aus, wie die Versionsangabe des jeweiligen Herstellers.
Nicht verwechseln mit usbVersionMajor: Dieser Wert gibt die unterstützte USB-Spezifikation an (z. B. 2 für USB 2.0), nicht die Version des Geräts.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird stillschweigend ignoriert und löst im Strict Mode einen TypeError aus.

Siehe auch

USBDevice USBDevice.deviceVersionMinor USBDevice.deviceVersionSubminor USBDevice.usbVersionMajor USB.requestDevice() USB.getDevices() XRView.isFirstPersonObserver