Comment ça marche
Montre ce qu’un périphérique USB déclare de lui-même dès qu’il est branché. Le descripteur de périphérique contient le Vendor ID attribué par l’USB-IF, le Product ID choisi par le fabricant, la version de la spécification USB qu’il prétend respecter, la version du produit lui-même et, si le périphérique les expose, les chaînes de fabricant, de produit et de numéro de série.
En dessous apparaît l’arborescence complète : chaque configuration avec ses interfaces, chaque interface avec son triplet classe, sous-classe et protocole traduit en nom officiel de l’USB-IF, et chaque endpoint avec son adresse, son sens, son type de transfert et la taille maximale de paquet. Les interfaces comportant plusieurs configurations alternatives —courant sur les caméras et les cartes son— sont listées à part.
L’outil se contente de lire les descripteurs : il n’ouvre jamais de session avec le périphérique, ne réserve jamais d’interface et ne lui envoie jamais un octet, il n’interfère donc pas avec le pilote qui l’utilise. Tout le parcours peut être exporté en JSON pour le joindre à un rapport ou le comparer à celui d’une autre machine.
Exemples
046D:C52B0x00 / 0x00 / 0x00 → 3 × HID (0x03)Un récepteur sans fil de clavier et de souris déclare la classe 0x00 au niveau du périphérique, le type réel se définit donc interface par interface : ici, trois interfaces HID avec chacune un endpoint d’entrée par interruption.0x08 / 0x06 / 0x50Mass Storage · SCSI transparent command set · Bulk-Only TransportLe triplet typique d’une clé USB ou d’un disque externe : deux endpoints en masse, un d’entrée et un de sortie, sur lesquels circulent les commandes SCSI.0x02 / 0x02 / 0x01Communications and CDC Control · Abstract Control Model · AT Commands (ITU-T V.250)C’est le port série virtuel d’une carte de développement ou d’un modem : une interface de contrôle avec un endpoint par interruption et une interface CDC-Data avec les deux endpoints en masse qui transportent les données.Cas d'usage
- Connaître le Vendor ID et le Product ID exacts d’un périphérique pour chercher son pilote ou pour écrire une règle udev sous Linux.
- Voir le numéro de série d’une clé USB, d’un lecteur ou d’un adaptateur quand le système d’exploitation ne l’affiche pas d’emblée.
- Vérifier pendant le développement d’un firmware que le périphérique publie les interfaces, les alternatives et les endpoints attendus, avec les bonnes classes.
- Découvrir sur quel endpoint et avec quel type de transfert il faut parler à un périphérique avant de programmer pour lui.
- Distinguer deux périphériques apparemment identiques en comparant leur version, leurs interfaces et leurs tailles de paquet.
- Documenter la configuration USB d’une machine en exportant toute l’arborescence en JSON.
Questions fréquentes
Pourquoi cela ne marche-t-il pas sur mon iPhone ni dans Firefox ?
L’API WebUSB est implémentée dans les navigateurs basés sur Chromium —Chrome, Edge et Opera— pour Windows, macOS, Linux, ChromeOS et Android. Firefox et Safari ne l’implémentent pas, et sous iOS tous les navigateurs utilisent le moteur du système, elle n’y est donc pas disponible non plus. Il faut également du HTTPS et que la page ne soit pas intégrée dans un autre site.
Le périphérique est branché mais il n’apparaît pas dans le sélecteur.
Le filtre choisi est peut-être trop étroit : essayez l’option qui propose tous les périphériques. S’il n’apparaît toujours pas, il figure probablement sur la liste de blocage du navigateur, qui exclut par sécurité certains produits —dont les clés de sécurité FIDO— pour qu’aucune page web ne puisse y toucher. Sous Linux, l’autorisation système sur le nœud du périphérique peut aussi manquer.
Pourquoi le périphérique indique-t-il la classe 0x00 ?
La classe 0x00 dans le descripteur de périphérique signifie « regardez les interfaces ». Presque tous les périphériques composites l’utilisent, en combinant des fonctions différentes sur le même câble : un clavier avec un concentrateur intégré, une caméra qui expose aussi un microphone ou une imprimante multifonction. Dans ces cas le type réel de chaque fonction se trouve dans la classe de chaque interface, pas dans celle du périphérique.
Qu’est-ce qu’un endpoint et que signifie une adresse comme 0x81 ?
Un endpoint est chacune des boîtes aux lettres par lesquelles les données entrent ou sortent d’une interface. Les sept bits de poids faible de l’adresse sont le numéro de l’endpoint et le bit de poids fort indique le sens : 0x81 est donc l’endpoint 1 d’entrée —du périphérique vers la machine— et 0x01 serait l’endpoint 1 de sortie. Le type de transfert définit le traitement qu’il reçoit : en masse pour de gros volumes sans délai, par interruption pour de petits événements fréquents comme une touche, et isochrone pour l’audio et la vidéo, qui préfèrent perdre un paquet plutôt que d’arriver en retard.
L’outil peut-il modifier ou casser quelque chose sur le périphérique ?
Non. Il lit uniquement les descripteurs que le navigateur a déjà obtenus en énumérant le périphérique ; il n’ouvre jamais de session, ne réserve jamais d’interface et n’écrit jamais. C’est pourquoi vous pouvez inspecter même un clavier ou une clé USB que le système d’exploitation utilise à cet instant, alors qu’une page web n’a pas le droit de communiquer avec eux.
Pourquoi le fabricant ou le produit apparaissent-ils vides ?
Ces chaînes sont des descripteurs optionnels : beaucoup de périphériques bon marché ne les enregistrent tout simplement pas, et certains systèmes d’exploitation ne les transmettent pas au navigateur. Dans ces cas, l’outil cherche le Vendor ID et le Product ID dans le catalogue usb.ids du projet Linux USB, qui enregistre bien le nom officiel du fabricant et, souvent, celui du produit.
Les données du périphérique sortent-elles de ma machine ?
Les descripteurs sont lus dans votre navigateur et ne sont envoyés à aucun serveur. La seule exception est la recherche dans le catalogue usb.ids, qui interroge le Vendor ID et le Product ID —deux nombres qui identifient le modèle, pas votre machine ni votre exemplaire— et que vous pouvez désactiver avant de choisir le périphérique. Le numéro de série n’est jamais envoyé.
Que sont les configurations alternatives d’une interface ?
Une même interface peut déclarer plusieurs jeux d’endpoints et n’en garder qu’un seul actif. Les caméras et les cartes son s’en servent pour proposer différentes combinaisons de résolution ou de qualité : chaque alternative réserve une bande passante différente sur le bus, et le système d’exploitation choisit celle qui convient au début de la transmission. L’alternative 0 est celle qui reste active tant que le périphérique est inactif.