Hoe het werkt
Laat zien wat een USB-apparaat over zichzelf opgeeft zodra het wordt aangesloten. De apparaatdescriptor bevat de door het USB-IF toegekende Vendor ID, de door de fabrikant gekozen Product ID, de versie van de USB-specificatie waaraan het zegt te voldoen, de versie van het product zelf en, als het apparaat ze aanbiedt, de teksten voor fabrikant, product en serienummer.
Daaronder verschijnt de volledige boom: elke configuratie met haar interfaces, elke interface met haar drietal van klasse, subklasse en protocol vertaald naar de officiële USB-IF-naam, en elk endpoint met zijn adres, richting, overdrachtstype en maximale pakketgrootte. Interfaces met meerdere alternatieve instellingen —gebruikelijk bij camera's en geluidskaarten— staan apart vermeld.
De tool leest alleen descriptors: er wordt nooit een sessie met het apparaat geopend, nooit een interface geclaimd en nooit één byte verstuurd, dus het stoort het stuurprogramma niet dat het apparaat gebruikt. De hele boom kun je als JSON exporteren om bij een rapport te voegen of te vergelijken met die van een andere computer.
Voorbeelden
046D:C52B0x00 / 0x00 / 0x00 → 3 × HID (0x03)Een draadloze ontvanger voor toetsenbord en muis geeft op apparaatniveau klasse 0x00 op, dus het echte type wordt per interface bepaald: hier drie HID-interfaces met elk één interrupt-endpoint als invoer.0x08 / 0x06 / 0x50Mass Storage · SCSI transparent command set · Bulk-Only TransportHet typische drietal van een USB-stick of een externe schijf: twee bulk-endpoints, één voor invoer en één voor uitvoer, waarover de SCSI-opdrachten reizen.0x02 / 0x02 / 0x01Communications and CDC Control · Abstract Control Model · AT Commands (ITU-T V.250)Dit is de virtuele seriële poort van een ontwikkelbord of een modem: een control-interface met één interrupt-endpoint en een CDC-Data-interface met de twee bulk-endpoints die de gegevens vervoeren.Gebruiksscenario's
- De exacte Vendor ID en Product ID van een apparaat achterhalen om het stuurprogramma te zoeken of om een udev-regel op Linux te schrijven.
- Het serienummer van een USB-stick, een lezer of een adapter zien wanneer het besturingssysteem het niet meteen toont.
- Tijdens de firmware-ontwikkeling controleren of het apparaat de verwachte interfaces, alternatieven en endpoints publiceert, met de juiste klassen.
- Ontdekken op welk endpoint en met welk overdrachtstype je een apparaat moet aanspreken voordat je ervoor programmeert.
- Twee schijnbaar identieke apparaten onderscheiden door hun versie, hun interfaces en hun pakketgroottes te vergelijken.
- De USB-configuratie van een computer documenteren door de hele boom als JSON te exporteren.
Veelgestelde vragen
Waarom werkt het niet op mijn iPhone of in Firefox?
De WebUSB-API is geïmplementeerd in browsers op basis van Chromium —Chrome, Edge en Opera— voor Windows, macOS, Linux, ChromeOS en Android. Firefox en Safari implementeren ze niet, en op iOS gebruiken alle browsers de systeemengine, dus daar is ze ook niet beschikbaar. Bovendien is HTTPS nodig en mag de pagina niet in een andere site ingebed zijn.
Het apparaat is aangesloten maar verschijnt niet in de kiezer.
Misschien is het gekozen filter te smal: probeer de optie die alle apparaten aanbiedt. Verschijnt het dan nog niet, dan staat het waarschijnlijk op de blokkeerlijst van de browser, die bepaalde producten om veiligheidsredenen uitsluit —waaronder FIDO-beveiligingssleutels— zodat geen enkele webpagina eraan kan komen. Op Linux kan ook de systeemtoestemming op de apparaatnode ontbreken.
Waarom meldt het apparaat klasse 0x00?
Klasse 0x00 in de apparaatdescriptor betekent «kijk naar de interfaces». Bijna alle samengestelde apparaten gebruiken die, want ze combineren verschillende functies over dezelfde kabel: een toetsenbord met ingebouwde hub, een camera die ook een microfoon aanbiedt of een multifunctionele printer. In die gevallen zit het echte type van elke functie in de klasse van elke interface, niet in die van het apparaat.
Wat is een endpoint en wat betekent een adres als 0x81?
Een endpoint is elk van de brievenbussen waarlangs gegevens een interface binnenkomen of verlaten. De zeven lage bits van het adres zijn het endpointnummer en het hoogste bit geeft de richting aan, dus 0x81 is endpoint 1 voor invoer —van het apparaat naar de computer— en 0x01 zou endpoint 1 voor uitvoer zijn. Het overdrachtstype bepaalt de behandeling: bulk voor grote hoeveelheden zonder deadline, interrupt voor kleine en frequente gebeurtenissen zoals een toetsaanslag, en isochroon voor audio en video, die liever een pakket verliezen dan te laat komen.
Kan de tool iets wijzigen of kapotmaken aan het apparaat?
Nee. Hij leest alleen de descriptors die de browser al kreeg bij het opsommen van het apparaat; hij opent nooit een sessie, claimt nooit een interface en schrijft nooit. Daarom kun je zelfs een toetsenbord of een USB-stick inspecteren die het besturingssysteem op dat moment gebruikt, ook al mag een webpagina er niet mee communiceren.
Waarom zijn de fabrikant of het product leeg?
Die teksten zijn optionele descriptors: veel goedkope apparaten slaan ze gewoon niet op, en sommige besturingssystemen geven ze niet door aan de browser. Voor die gevallen zoekt de tool de Vendor ID en de Product ID op in de usb.ids-catalogus van het Linux USB-project, die de officiële naam van de fabrikant en vaak ook die van het product wel bijhoudt.
Verlaten de gegevens van het apparaat mijn computer?
De descriptors worden in je browser gelezen en naar geen enkele server gestuurd. De enige uitzondering is de zoekopdracht in de usb.ids-catalogus, die de Vendor ID en de Product ID opvraagt —twee getallen die het model aanduiden, niet je computer of jouw exemplaar— en die je kunt uitschakelen voordat je het apparaat kiest. Het serienummer wordt nooit verstuurd.
Wat zijn de alternatieve instellingen van een interface?
Eén interface kan meerdere sets endpoints opgeven en er maar één actief houden. Camera's en geluidskaarten gebruiken dat om verschillende combinaties van resolutie of kwaliteit aan te bieden: elk alternatief reserveert een andere bandbreedte op de bus, en het besturingssysteem kiest het juiste zodra het gaat streamen. Alternatief 0 is het alternatief dat actief blijft zolang het apparaat niets doet.