Signatur
USBDevice.deviceProtocol
Beschreibung
Die schreibgeschützte Eigenschaft deviceProtocol eines USBDevice-Objekts liefert den Wert des Felds bDeviceProtocol aus dem USB-Geräte-Deskriptor. Zusammen mit deviceClass (bDeviceClass) und deviceSubclass (bDeviceSubClass) bildet sie das Dreigespann, mit dem das Betriebssystem ein Gerät einordnet und einen passenden Treiber auswählt.
Wie der Wert zu verstehen ist, hängt von Klasse und Unterklasse ab. Die Codes vergibt das USB-IF. Ein paar Beispiele:
0x00: Auf Geräteebene wird kein Protokoll festgelegt. Die Angaben stehen dann meist in den Interface-Deskriptoren (USBAlternateInterface.interfaceProtocol).0xFF: herstellerspezifisches Protokoll.- Bei Klasse
0xEF, Unterklasse0x02bedeutet Protokoll0x01„Interface Association Descriptor“. Das ist typisch für zusammengesetzte Geräte (Composite Devices). - Bei Hubs (Klasse
0x09) unterscheidet das Protokoll zwischen Full-Speed-, Single-TT- und Multi-TT-Hubs.
Die Eigenschaft ist nützlich, um Geräte nach der Auswahl zu prüfen, zur Fehlersuche oder um Geräte in navigator.usb.requestDevice() über den Filterschlüssel protocolCode einzugrenzen. Um sie zu lesen, muss das Gerät nicht geöffnet sein (open() ist nicht nötig).
Rückgabewert
Typ
number
Beschreibung
Ein vorzeichenloser 8-Bit-Wert (
0–255), der dem Feld bDeviceProtocol des Geräte-Deskriptors entspricht.Beispiele
Klasse, Unterklasse und Protokoll eines Geräts auslesen
const button = document.querySelector('#connect');
button.addEventListener('click', async () => {
try {
// requestDevice muss durch eine Nutzeraktion ausgelöst werden
const device = await navigator.usb.requestDevice({ filters: [] });
const hex = (n) => '0x' + n.toString(16).padStart(2, '0');
console.log(`${device.productName}: Klasse ${hex(device.deviceClass)}, ` +
`Unterklasse ${hex(device.deviceSubclass)}, Protokoll ${hex(device.deviceProtocol)}`);
} catch (err) {
console.warn('Kein Gerät ausgewählt:', err.message);
}
});Arduino Leonardo: Klasse 0xef, Unterklasse 0x02, Protokoll 0x01
Geräteauswahl über protocolCode filtern
const connectVendorDevice = async () => {
// Nur herstellerspezifische Geräte (Klasse/Unterklasse/Protokoll 0xFF) anbieten
const device = await navigator.usb.requestDevice({
filters: [{ classCode: 0xff, subclassCode: 0xff, protocolCode: 0xff }]
});
console.log('Protokoll:', device.deviceProtocol);
return device;
};
document.querySelector('#pair').addEventListener('click', connectVendorDevice);Protokoll: 255
Bereits freigegebene Geräte klassifizieren
const describeProtocol = ({ deviceClass, deviceSubclass, deviceProtocol }) => {
if (deviceClass === 0x00 && deviceProtocol === 0x00) return 'auf Interface-Ebene definiert';
if (deviceClass === 0xef && deviceSubclass === 0x02 && deviceProtocol === 0x01)
return 'Composite-Gerät (IAD)';
if (deviceProtocol === 0xff) return 'herstellerspezifisch';
return `Protokoll ${deviceProtocol}`;
};
const devices = await navigator.usb.getDevices();
for (const device of devices) {
console.log(device.productName, '→', describeProtocol(device));
}Arduino Leonardo → Composite-Gerät (IAD)
// Wichtig · Fallstricke
- Browser-Unterstützung: WebUSB gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) auf Desktop und Android. Firefox und Safari unterstützen die API nicht. Prüfe sie deshalb vorher mit
'usb' in navigator. - Sicherer Kontext: Die API funktioniert nur über HTTPS (oder
localhost). Sie kann per Permissions Policy (usb) gesperrt sein, z. B. in iframes. - Ein Wert von
0heißt nicht „unbekannt“, sondern „auf Interface-Ebene festgelegt“. In diesem Fall musst dudevice.configuration.interfaces[i].alternate.interfaceProtocolauswerten. - Die Protokoll-Nummer lässt sich nur zusammen mit
deviceClassunddeviceSubclassdeuten. Derselbe Zahlenwert kann in verschiedenen Klassen etwas völlig anderes bedeuten. - Geräte bestimmter geschützter Klassen (z. B. HID, Massenspeicher, Audio/Video) blockiert WebUSB auf Interface-Ebene. Die Deskriptor-Werte kannst du trotzdem lesen.