USBDevice.serialNumber — Eigenschaft · JavaScript-Referenz

Signatur

USBDevice.serialNumber

Beschreibung

Die schreibgeschützte Eigenschaft serialNumber des USBDevice-Interfaces enthält die Seriennummer, die der Hersteller für genau dieses eine Gerät festgelegt hat. Der Wert stammt aus dem String-Deskriptor, auf den das Feld iSerialNumber im USB-Gerätedeskriptor verweist. Gibt das Gerät keine Seriennummer an, ist der Wert null.

Anders als vendorId und productId, die ein ganzes Modell beschreiben, gehört die Seriennummer zu einem einzelnen Exemplar. Damit lassen sich mehrere baugleiche Geräte auseinanderhalten, zum Beispiel wenn zwei gleiche Messgeräte oder Mikrocontroller-Boards am selben Rechner hängen. Außerdem kann eine Anwendung ein bestimmtes Gerät wiedererkennen, das der Nutzer früher schon freigegeben hat.

Die Eigenschaft steht sofort nach navigator.usb.requestDevice() oder navigator.usb.getDevices() zur Verfügung. Das Gerät muss dafür nicht mit open() geöffnet sein. Außerdem kann man die Seriennummer als Filterkriterium an requestDevice() übergeben, damit die Geräteauswahl nur ein bestimmtes Exemplar anbietet.

Rückgabewert

Typ

string | null

Beschreibung

Die Seriennummer des Geräts als String oder null, wenn das Gerät keinen Seriennummer-Deskriptor hat.

Beispiele

Seriennummer nach der Geräteauswahl auslesen

const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  try {
    // Arduino-Vendor-ID als Beispiel
    const device = await navigator.usb.requestDevice({
      filters: [{ vendorId: 0x2341 }]
    });
    console.log(`Gerät: ${device.productName}`);
    console.log(`Seriennummer: ${device.serialNumber ?? '(keine)'}`);
  } catch (err) {
    console.error('Keine Auswahl getroffen:', err.message);
  }
});

Gerät: Arduino Uno Seriennummer: 85736323838351F0C1A1

Früher freigegebenes Gerät anhand der Seriennummer wiederfinden

const STORAGE_KEY = 'bevorzugtesGeraet';

const findPreferredDevice = async () => {
  const saved = localStorage.getItem(STORAGE_KEY);
  if (!saved) return null;

  const devices = await navigator.usb.getDevices();
  return devices.find((d) => d.serialNumber === saved) ?? null;
};

const rememberDevice = (device) => {
  if (device.serialNumber) {
    localStorage.setItem(STORAGE_KEY, device.serialNumber);
  }
};

const device = await findPreferredDevice();
console.log(device ? `Gefunden: ${device.serialNumber}` : 'Kein gespeichertes Gerät verbunden');

Gefunden: 85736323838351F0C1A1

Geräteauswahl auf ein bestimmtes Exemplar einschränken

const connectToUnit = async (serial) => {
  const device = await navigator.usb.requestDevice({
    filters: [{ vendorId: 0x2341, serialNumber: serial }]
  });
  await device.open();
  console.log(`Verbunden mit ${device.serialNumber}, geöffnet: ${device.opened}`);
  return device;
};

// muss in einem Nutzer-Ereignis (z. B. click) aufgerufen werden
document.querySelector('#unit-a').addEventListener('click', () => {
  connectToUnit('85736323838351F0C1A1').catch(console.error);
});

Verbunden mit 85736323838351F0C1A1, geöffnet: true

// Wichtig · Fallstricke

Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen es nicht. Die API funktioniert nur in einem sicheren Kontext (HTTPS oder localhost) und kann per Permissions-Policy usb gesperrt werden. Deshalb vorher mit 'usb' in navigator prüfen.
Nicht immer vorhanden: Viele günstige Geräte haben keine Seriennummer (dann ist der Wert null) oder melden eine Seriennummer, die bei allen Exemplaren gleich ist. Als eindeutige Kennung ist sie deshalb nur eingeschränkt verlässlich. Am besten mit vendorId und productId kombinieren.
Datenschutz: Die Seriennummer ist eine dauerhafte Hardware-Kennung. Die Seite sieht sie erst, nachdem der Nutzer das Gerät ausdrücklich freigegeben hat. Trotzdem sollte man sie nicht ohne Grund an Server schicken oder zur Nachverfolgung von Nutzern verwenden.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird im nicht-strikten Modus stillschweigend ignoriert und löst im strikten Modus einen TypeError aus.

Siehe auch

USBDevice USBDevice.productName USBDevice.manufacturerName USBDevice.vendorId USBDevice.productId USB.requestDevice() USB.getDevices()