2026-06-02

Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows

Comment diagnostiquer les descripteurs USB BOS, les descripteurs Microsoft OS, WCID, la liaison automatique de pilote WinUSB, les landing pages WebUSB, les stalls de descripteurs et le comportement d'énumération Windows.

Les périphériques USB modernes s'appuient souvent sur des descripteurs au-delà des descripteurs de périphérique et de configuration de base. Les descripteurs BOS, les descripteurs Microsoft OS, WCID, les platform capabilities WebUSB et les ID compatibles WinUSB peuvent contrôler la façon dont Windows lie les pilotes et dont les navigateurs ou outils découvrent les capacités du périphérique. Quand ces descripteurs sont erronés, les utilisateurs voient « WinUSB driver not binding », « WebUSB device not found », « USB BOS descriptor failed », « Microsoft OS descriptor invalid » ou « device works on Linux but not Windows ».

Bus Scope est utile car les problèmes pilotés par les descripteurs surviennent pendant l'énumération. Si vous ne capturez pas les requêtes de descripteurs, vous ne voyez peut-être que le symptôme final dans le Gestionnaire de périphériques ou l'application.

Ce qu'est le descripteur BOS

BOS signifie Binary Object Store. Il permet à un périphérique USB d'annoncer des platform capabilities et des informations additionnelles au niveau périphérique. Pour les appareils modernes, BOS peut inclure des capabilities pour :

USB 2.0 extension
capability SuperSpeed
platform capability WebUSB
platform capability Microsoft OS 2.0

Si le descripteur BOS est mal formé, Windows ou les outils basés navigateur peuvent ignorer les fonctionnalités ou échouer la validation.

Descripteurs Microsoft OS et WinUSB

Les descripteurs Microsoft OS peuvent aider Windows à lier WinUSB automatiquement sans INF personnalisé dans certains cas. Les anciens descripteurs de style WCID et les plus récents descripteurs Microsoft OS 2.0 sont tous deux rencontrés sur des appareils réels.

Les preuves importantes incluent :

requête de descripteur string d'index 0xEE dans les anciens flux
vendor code utilisé pour demander les descripteurs OS
compatible ID tel que WINUSB
propriétés étendues
association de numéro d'interface
fait que le périphérique stall correctement les requêtes de descripteurs non supportées

Si le firmware renvoie des données mal formées, Windows peut ne pas lier WinUSB même si le périphérique s'énumère.

WebUSB

WebUSB utilise les platform capabilities du BOS pour annoncer une landing page et une capability accessible au navigateur. Si l'entrée BOS est erronée, un navigateur peut ne pas exposer le périphérique comme attendu.

Symptômes :

le navigateur ne trouve pas le périphérique
le périphérique apparaît dans l'OS mais pas dans le sélecteur WebUSB
URL de landing page manquante ou fausse
le périphérique marche avec un outil natif mais pas avec un outil web

La trace du bus peut montrer si l'hôte a demandé le BOS et ce que le périphérique a renvoyé.

Comportement STALL valide

Pour certains mécanismes optionnels de descripteurs Microsoft, un périphérique qui ne supporte pas la fonctionnalité doit stall la requête. Un STALL n'est pas toujours un bug. Le bug est de renvoyer des données de descripteur invalides ou de prétendre supporter puis échouer la requête suivante.

C'est pourquoi le contexte du transfert de contrôle compte.

Complications des périphériques composites

Les descripteurs Microsoft OS ciblent souvent une interface précise. Les périphériques composites peuvent échouer si le descripteur pointe vers un mauvais numéro d'interface ou si Windows ne lie qu'une partie du périphérique.

Inspectez :

les numéros d'interface
les descripteurs Interface Association
les sections compatible ID
les en-têtes function subset
si WinUSB est destiné à une interface ou à toutes

Checklist de débogage

Suivez ce flux :

Capturez dès le branchement.
Conservez descripteurs de périphérique, configuration, interface, endpoint et BOS.
Cherchez les requêtes de descripteurs Microsoft OS.
Décodez le vendor code et la longueur du descripteur.
Vérifiez les numéros d'interface dans les données de descripteur.
Vérifiez les valeurs compatible ID comme WINUSB.
Vérifiez si les requêtes non supportées stallent correctement.
Comparez le comportement d'énumération Windows et Linux.
Vérifiez la liaison dans le Gestionnaire de périphériques après énumération.
Conservez les octets de descripteurs pour le débogage firmware.

Diagnostic final

Les échecs de descripteurs USB BOS et Microsoft OS sont des problèmes de contrat de descripteurs. Le périphérique peut s'énumérer mais quand même échouer WinUSB, WebUSB ou la liaison de pilote spécifique à l'interface parce que des descripteurs optionnels sont mal formés, manquants ou mappés à la mauvaise interface.

Bus Scope aide en montrant directement l'énumération et les requêtes de descripteurs, pour que les échecs de liaison de pilote soient débogués à partir des preuves USB plutôt que des seuls symptômes OS.

Test du contrat USB pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows »

La réponse directe est qu’un STALL, timeout ou reset n’explique pas seul la cause. Prouvez d’abord que le fournisseur voit le bon périphérique, puis lisez le contrat du transfer : type, direction, recipient, wValue, wIndex, longueur annoncée et réelle, status et état avant/après. Pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows », reliez la conclusion à la première transaction différente d’un cas nominal.

Limite	Comparaison	Décision
Plateforme	fournisseur, droits, Root Hub ou usbmon/XHC20	Les records viennent-ils de la bonne connexion ?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	L’hôte envoie-t-il la requête prévue ?
Data	direction, longueur et bytes conservés	Le payload respecte-t-il le contrat ?
Status	ACK, STALL, timeout ou cancellation	Où finit réellement la transaction ?
État	configuration, interface, alternate setting, endpoint halt	Le périphérique était-il prêt ?

Commencez avant reset et énumération et gardez descriptors, SET_CONFIGURATION, SET_INTERFACE et la commande avant défaut. Un filtre endpoint étroit peut masquer le control transfer décisif. Exécutez une seule action USB documentée par essai et ne changez que firmware, driver, port, câble, commande ou timing.

Comment rédiger une réponse réutilisable ?

Nommez requête, champs setup, réponse et contexte précédent, puis un test à variable unique. Des bytes non retenus ne prouvent pas packet loss. La proximité entre command et reset établit une corrélation, pas la cause sans répétition ou transition d’état.

Quand la comparaison est-elle valide ?

Gardez VID/PID, firmware, speed, topologie, fournisseur, filtre et trigger. Comparez les phases USB sémantiques, pas les frame numbers entre usbmon et USBPcap. Notez début, fin, version, OS, connexion et checksum. Consultez le dépannage Bus Scope.

Les propriétaires Semrush restent distincts : free USB analyzer sur la page produit, best USB protocol analyzer dans la comparaison et USB descriptor viewer dans le guide descriptor. Aucun volume ou KD n’est inventé pour cette page de support.

Réponse directe et limite d’acceptation

La réponse courte à « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows » est la suivante : Comment diagnostiquer les descripteurs USB BOS, les descripteurs Microsoft OS, WCID, la liaison automatique de pilote WinUSB, les landing pages WebUSB, les stalls de descripteurs et le comportement d'énumération Windows. Considérez cette phrase comme un résultat à vérifier, et non comme une promesse valable pour toute entrée, tout appareil, tout projet ou tout environnement. Un résultat complet consigne l’état initial, l’action exacte, la sortie visible et la condition qui prouve la fin de la tâche dans Bus Scope.

Procédure fondée sur les preuves

Commencez par un cas petit et répétable avant de modifier un projet complet. Notez version de l’application, système, identité de l’entrée ou de l’appareil, réglages pertinents et résultat attendu. Exécutez une action volontaire, conservez la première transition inattendue et comparez-la à un cas nominal si possible. Plusieurs changements simultanés masquent la condition qui a créé ou corrigé le problème.

Point de contrôle 1 : Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pil

Traitez « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows » comme une porte d’acceptation distincte pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows ». Consignez l’état avant l’action, le premier changement visible et l’état final. Si le résultat diffère de l’objectif décrit, revenez au dernier point confirmé au lieu de poursuivre sur des hypothèses.

Point de contrôle 2 : Comment diagnostiquer les descripteurs USB BOS, les descripteurs Microsoft OS, WCID, la li

Transformez « Comment diagnostiquer les descripteurs USB BOS, les descripteurs Microsoft OS, WCID, la liaison automatique de pilote WinUSB, les landing pages WebUSB » en critère réussite/échec reproductible. Indiquez ce qui doit être présent, absent et quelle reprise reste sûre. Conservez le projet ou la capture d’origine jusqu’à ce que la copie corrigée réussisse le même contrôle.

Point de contrôle 3 : Ce qu'est le descripteur BOS

Traitez « Ce qu'est le descripteur BOS » comme une porte d’acceptation distincte pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows ». Consignez l’état avant l’action, le premier changement visible et l’état final. Si le résultat diffère de l’objectif décrit, revenez au dernier point confirmé au lieu de poursuivre sur des hypothèses.

Point de contrôle 4 : Descripteurs Microsoft OS et WinUSB

Transformez « Descripteurs Microsoft OS et WinUSB » en critère réussite/échec reproductible. Indiquez ce qui doit être présent, absent et quelle reprise reste sûre. Conservez le projet ou la capture d’origine jusqu’à ce que la copie corrigée réussisse le même contrôle.

Point de contrôle 5 : WebUSB

Traitez « WebUSB » comme une porte d’acceptation distincte pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows ». Consignez l’état avant l’action, le premier changement visible et l’état final. Si le résultat diffère de l’objectif décrit, revenez au dernier point confirmé au lieu de poursuivre sur des hypothèses.

Point de contrôle 6 : Comportement STALL valide

Transformez « Comportement STALL valide » en critère réussite/échec reproductible. Indiquez ce qui doit être présent, absent et quelle reprise reste sûre. Conservez le projet ou la capture d’origine jusqu’à ce que la copie corrigée réussisse le même contrôle.

Point de contrôle 7 : Complications des périphériques composites

Traitez « Complications des périphériques composites » comme une porte d’acceptation distincte pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows ». Consignez l’état avant l’action, le premier changement visible et l’état final. Si le résultat diffère de l’objectif décrit, revenez au dernier point confirmé au lieu de poursuivre sur des hypothèses.

Point de contrôle 8 : Checklist de débogage

Transformez « Checklist de débogage » en critère réussite/échec reproductible. Indiquez ce qui doit être présent, absent et quelle reprise reste sûre. Conservez le projet ou la capture d’origine jusqu’à ce que la copie corrigée réussisse le même contrôle.

Point de contrôle 9 : Diagnostic final

Traitez « Diagnostic final » comme une porte d’acceptation distincte pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows ». Consignez l’état avant l’action, le premier changement visible et l’état final. Si le résultat diffère de l’objectif décrit, revenez au dernier point confirmé au lieu de poursuivre sur des hypothèses.

Point de contrôle 10 : Test du contrat USB pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, Win

Transformez « Test du contrat USB pour « Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows » » en critère réussite/échec reproductible. Indiquez ce qui doit être présent, absent et quelle reprise reste sûre. Conservez le projet ou la capture d’origine jusqu’à ce que la copie corrigée réussisse le même contrôle.

Matrice d’acceptation

Point	Preuve à conserver	Critère de réussite
Débogage des descripteurs USB BOS et Microsoft OS : WebUSB, WinUSB, WCID et liaison de pilotes Windows	État initial, une action et état obtenu	Une seconde personne reproduit le résultat
Comment diagnostiquer les descripteurs USB BOS, les descripteurs Microsoft OS, WCID, la liaison automatique de pilote Wi	État initial, une action et état obtenu	Une seconde personne reproduit le résultat
Ce qu'est le descripteur BOS	État initial, une action et état obtenu	Une seconde personne reproduit le résultat
Descripteurs Microsoft OS et WinUSB	État initial, une action et état obtenu	Une seconde personne reproduit le résultat
WebUSB	État initial, une action et état obtenu	Une seconde personne reproduit le résultat
Comportement STALL valide	État initial, une action et état obtenu	Une seconde personne reproduit le résultat

Isolation, reprise et transmission

Arrêtez-vous à la première limite en échec. Conservez source, projet, session ou capture, dupliquez avant toute modification destructive et changez une variable par essai. Rejouer un flux entier après plusieurs changements peut modifier le résultat sans expliquer pourquoi.

Distinguez absence de preuve et preuve d’absence. Une vue vide peut signaler mauvaise entrée, portée, filtre, permission, appareil, période ou état du projet. Vérifiez acquisition ou import avant d’interpréter décodeur, éditeur, rapport ou export.

Avant transmission, rouvrez l’artefact durable et inspectez début, point de décision et fin. Notez version, plateforme, configuration, attente, observation et reproduction minimale. Retirez ou masquez les données sensibles et confirmez l’autorisation du destinataire.

Questions et réponses

Quelle est la manière fiable la plus rapide de commencer ?

Utilisez le plus petit cas représentatif, écrivez le résultat attendu et ne changez qu’une variable. Validez le parcours de base avant d’ajouter filtres, effets, modifications, automatisation ou grande source.

Quelles preuves faut-il conserver ?

Gardez identité de l’entrée, version, plateforme, réglages, action exacte, première transition inattendue et sortie finale. Fermez puis rouvrez projet, session, rapport ou export avant de le considérer durable.

Quand faut-il répéter la procédure ?

Répétez-la après un changement pertinent d’application, système, pilote, firmware, modèle, source ou processus. Conservez le cas accepté précédent comme référence non modifiée.

Quand le résultat est-il transmissible ?

Lorsqu’une seconde personne autorisée identifie l’entrée, répète l’action, obtient le même résultat, comprend les limites et ouvre l’artefact sans état local non documenté.

Guides associés

Ces pages dans la même langue couvrent les étapes voisines sans changer le propriétaire canonique du sujet :