2026-06-02

Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows

Cómo depurar descriptores USB BOS, descriptores Microsoft OS, WCID, binding automático de WinUSB, landing pages de WebUSB, stalls de descriptores y comportamiento de enumeración en Windows.

Muchos dispositivos USB modernos dependen de descriptores más allá de los clásicos device y configuration. Los descriptores BOS, Microsoft OS, WCID, capacidades de plataforma WebUSB y compatible IDs de WinUSB controlan cómo Windows enlaza drivers y cómo navegadores o herramientas descubren capacidades del dispositivo. Cuando esos descriptores fallan, los usuarios ven "WinUSB driver not binding", "WebUSB device not found", "USB BOS descriptor failed", "Microsoft OS descriptor invalid" o "device works on Linux but not Windows".

Bus Scope ayuda porque los problemas derivados de descriptores ocurren durante la enumeración. Si no capturas las peticiones de descriptor, solo verás el síntoma final en el Administrador de dispositivos o en la aplicación.

Qué es el descriptor BOS

BOS significa Binary Object Store. Permite a un dispositivo USB anunciar capacidades de plataforma e información a nivel de dispositivo adicional. En dispositivos modernos, BOS puede incluir capacidades para:

Extensión USB 2.0.
Capacidad SuperSpeed.
Platform capability WebUSB.
Platform capability Microsoft OS 2.0.

Si el descriptor BOS está mal formado, Windows o las herramientas basadas en navegador pueden ignorar funciones o fallar la validación.

Descriptores Microsoft OS y WinUSB

Los descriptores Microsoft OS pueden ayudar a Windows a enlazar WinUSB de forma automática sin un INF personalizado en algunos casos. Los descriptores antiguos estilo WCID y los más nuevos Microsoft OS 2.0 aparecen en dispositivos reales.

Evidencia importante:

Petición del string descriptor index 0xEE en flujos antiguos.
Vendor code usado para pedir OS descriptors.
Compatible ID como WINUSB.
Extended properties.
Asociación con número de interfaz.
Si el dispositivo hace STALL correctamente ante peticiones de descriptor no soportadas.

Si el firmware devuelve datos mal formados, Windows puede no enlazar WinUSB aunque el dispositivo enumere.

WebUSB

WebUSB usa platform capabilities en BOS para anunciar una landing page y la capacidad accesible desde el navegador. Si la entrada BOS está mal, el navegador puede no exponer el dispositivo como debería.

Síntomas:

El navegador no encuentra el dispositivo.
El dispositivo aparece en el SO pero no en el selector WebUSB.
La URL de la landing page falta o es incorrecta.
El dispositivo funciona con la herramienta nativa pero no con la web.

La traza del bus puede enseñar si el host pidió BOS y qué devolvió el dispositivo.

Comportamiento válido de STALL

Para algunos mecanismos opcionales de descriptores Microsoft, un dispositivo que no soporta la feature debe hacer STALL en la petición. Un STALL no siempre es un bug. El bug es devolver datos de descriptor inválidos o reclamar soporte y fallar después la petición siguiente.

Por eso importa el contexto de la transferencia de control.

Complicaciones en dispositivos compuestos

Los descriptores Microsoft OS suelen apuntar a una interfaz concreta. Los dispositivos compuestos pueden fallar si el descriptor apunta a un número de interfaz equivocado o si Windows solo enlaza parte del dispositivo.

Inspecciona:

Números de interfaz.
Interface Association Descriptors.
Secciones de Compatible ID.
Function subset headers.
Si WinUSB está pensado para una interfaz o para todas.

Checklist de depuración

Usa este flujo:

Captura desde el momento del plug-in.
Conserva los descriptores device, configuration, interface, endpoint y BOS.
Busca peticiones de descriptores Microsoft OS.
Decodifica el vendor code y la longitud del descriptor.
Comprueba los números de interfaz en los datos del descriptor.
Verifica los valores de Compatible ID como WINUSB.
Mira si las peticiones no soportadas hacen STALL correctamente.
Compara el comportamiento de enumeración en Windows y Linux.
Revisa el binding del Administrador de dispositivos tras enumerar.
Conserva los bytes de descriptor para depurar el firmware.

Diagnóstico final

Los fallos en BOS y Microsoft OS son problemas de contrato de descriptor. El dispositivo puede enumerar y aun así fallar WinUSB, WebUSB o el binding de driver específico de interfaz porque los descriptores opcionales están mal formados, faltan o están mapeados a la interfaz incorrecta.

Bus Scope ayuda enseñando la enumeración y las peticiones de descriptor directamente, para que los fallos de binding de driver se depuren desde la evidencia USB en lugar de solo a partir de síntomas del SO.

Prueba del contrato USB para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows»

La respuesta directa es que STALL, timeout o reset no explica por sí solo la causa. Primero demuestra que el proveedor observa el dispositivo correcto; después lee el contrato de transferencia: tipo, dirección, recipient, wValue, wIndex, longitud declarada y real, status y estado anterior y posterior. En «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows», relaciona la conclusión con la primera transacción que difiere de un caso bueno.

Límite	Qué comparar	Decisión útil
Plataforma	proveedor, permiso, Root Hub o usbmon/XHC20	¿Llegan records de la conexión correcta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	¿El host envía la petición prevista?
Data	dirección, longitud y bytes retenidos	¿El payload cumple el contrato?
Status	ACK, STALL, timeout o cancellation	¿Dónde termina la transacción?
Estado	configuration, interface, alternate setting, endpoint halt	¿El dispositivo estaba preparado?

Empieza antes de reset y enumeración y conserva descriptors, SET_CONFIGURATION, SET_INTERFACE y el comando previo al fallo. Un filtro estrecho de endpoint puede ocultar el control transfer decisivo. Ejecuta una sola acción USB documentada por prueba y cambia solo firmware, driver, puerto, cable, comando o timing.

¿Cómo se escribe una respuesta citable?

Indica la petición observada, sus campos setup, la respuesta y el contexto anterior; propone después una prueba con un solo cambio. Bytes no retenidos por el límite de captura no prueban packet loss. La proximidad entre command y reset demuestra correlación, no causa sin repetición o transición de estado.

¿Cuándo vale una comparación?

Mantén VID/PID, firmware, speed, topología, proveedor, filtro y trigger. Compara fases USB semánticas y no frame numbers entre usbmon y USBPcap. Anota inicio, final, versión, OS, conexión y checksum. Revisa la solución de problemas de Bus Scope.

Los propietarios Semrush siguen separados: free USB analyzer en la página de producto, best USB protocol analyzer en la comparación y USB descriptor viewer en la guía de descriptors. Esta página de soporte no recibe volumen o KD inventado.

Respuesta directa y límite de aceptación

La respuesta breve a «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows» es: Cómo depurar descriptores USB BOS, descriptores Microsoft OS, WCID, binding automático de WinUSB, landing pages de WebUSB, stalls de descriptores y comportamiento de enumeración en Windows. Trate esa frase como un resultado que debe comprobarse, no como una promesa para cualquier entrada, dispositivo, proyecto o entorno. Un resultado completo registra estado inicial, acción exacta, salida visible y condición que demuestra que la tarea terminó en Bus Scope.

Procedimiento basado en evidencia

Empiece con un caso pequeño y repetible antes de cambiar un proyecto completo. Anote versión de la aplicación, sistema operativo, identidad de entrada o dispositivo, ajustes relevantes y resultado esperado. Ejecute una acción deliberada, conserve la primera transición inesperada y compárela con un caso conocido cuando exista. Cambiar varios controles a la vez oculta qué condición creó o corrigió el problema.

Punto de control 1: Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de driver

Trate «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows» como una puerta de aceptación independiente para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows». Registre el estado inicial, el primer cambio visible y el estado final. Si el resultado no coincide con el objetivo descrito, vuelva al último punto confirmado en lugar de continuar sobre suposiciones.

Punto de control 2: Cómo depurar descriptores USB BOS, descriptores Microsoft OS, WCID, binding automático de

Convierta «Cómo depurar descriptores USB BOS, descriptores Microsoft OS, WCID, binding automático de WinUSB, landing pages de WebUSB, stalls de descriptores y co» en una afirmación de aprobado o fallo que otra persona pueda repetir. Incluya qué debe aparecer, qué debe estar ausente y qué recuperación es segura. Mantenga intacto el proyecto o captura original hasta que la copia corregida pase la misma prueba.

Punto de control 3: Qué es el descriptor BOS

Trate «Qué es el descriptor BOS» como una puerta de aceptación independiente para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows». Registre el estado inicial, el primer cambio visible y el estado final. Si el resultado no coincide con el objetivo descrito, vuelva al último punto confirmado en lugar de continuar sobre suposiciones.

Punto de control 4: Descriptores Microsoft OS y WinUSB

Convierta «Descriptores Microsoft OS y WinUSB» en una afirmación de aprobado o fallo que otra persona pueda repetir. Incluya qué debe aparecer, qué debe estar ausente y qué recuperación es segura. Mantenga intacto el proyecto o captura original hasta que la copia corregida pase la misma prueba.

Punto de control 5: WebUSB

Trate «WebUSB» como una puerta de aceptación independiente para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows». Registre el estado inicial, el primer cambio visible y el estado final. Si el resultado no coincide con el objetivo descrito, vuelva al último punto confirmado en lugar de continuar sobre suposiciones.

Punto de control 6: Comportamiento válido de STALL

Convierta «Comportamiento válido de STALL» en una afirmación de aprobado o fallo que otra persona pueda repetir. Incluya qué debe aparecer, qué debe estar ausente y qué recuperación es segura. Mantenga intacto el proyecto o captura original hasta que la copia corregida pase la misma prueba.

Punto de control 7: Complicaciones en dispositivos compuestos

Trate «Complicaciones en dispositivos compuestos» como una puerta de aceptación independiente para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows». Registre el estado inicial, el primer cambio visible y el estado final. Si el resultado no coincide con el objetivo descrito, vuelva al último punto confirmado en lugar de continuar sobre suposiciones.

Punto de control 8: Checklist de depuración

Convierta «Checklist de depuración» en una afirmación de aprobado o fallo que otra persona pueda repetir. Incluya qué debe aparecer, qué debe estar ausente y qué recuperación es segura. Mantenga intacto el proyecto o captura original hasta que la copia corregida pase la misma prueba.

Punto de control 9: Diagnóstico final

Trate «Diagnóstico final» como una puerta de aceptación independiente para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows». Registre el estado inicial, el primer cambio visible y el estado final. Si el resultado no coincide con el objetivo descrito, vuelva al último punto confirmado en lugar de continuar sobre suposiciones.

Punto de control 10: Prueba del contrato USB para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, Wi

Convierta «Prueba del contrato USB para «Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows»» en una afirmación de aprobado o fallo que otra persona pueda repetir. Incluya qué debe aparecer, qué debe estar ausente y qué recuperación es segura. Mantenga intacto el proyecto o captura original hasta que la copia corregida pase la misma prueba.

Matriz de aceptación

Punto	Evidencia que conservar	Condición de aprobado
Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Cómo depurar descriptores USB BOS, descriptores Microsoft OS, WCID, binding automático de WinUSB, landing pages de WebUS	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Qué es el descriptor BOS	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Descriptores Microsoft OS y WinUSB	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
WebUSB	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Comportamiento válido de STALL	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado

Aislamiento, recuperación y entrega

Deténgase en el primer límite que falla. Conserve fuente, proyecto, sesión o captura, duplíquelo antes de una edición destructiva y cambie una variable por experimento. Repetir un flujo amplio después de varios cambios puede dar otro resultado sin explicar la causa.

Separe ausencia de evidencia de evidencia de ausencia. Una vista vacía puede indicar entrada, alcance, filtro, permiso, dispositivo, intervalo o estado equivocado. Verifique adquisición o importación antes de interpretar el decoder, editor, informe o exportación.

Antes de entregar, reabra el artefacto y revise inicio, punto de decisión y final. Registre versión, plataforma, configuración, expectativa, observación y reproducción mínima. Elimine o redacte datos sensibles y confirme que el destinatario está autorizado.

Preguntas y respuestas

¿Cuál es la forma fiable más rápida de empezar?

Use el caso representativo más pequeño, escriba el resultado esperado y cambie una variable. Confirme el recorrido básico antes de añadir filtros, efectos, ediciones, automatización o una fuente mayor.

¿Qué evidencia debe guardarse?

Conserve identidad de entrada, versión, plataforma, ajustes, acción exacta, primera transición inesperada y salida final. Cierre y reabra cualquier proyecto, sesión, informe o exportación antes de considerarlo duradero.

¿Cuándo debe repetirse el procedimiento?

Repítalo después de cambios relevantes en aplicación, sistema, driver, firmware, modelo, fuente o flujo. Preserve el caso aceptado anterior como referencia sin modificar.

¿Cuándo está listo para entregar?

Cuando otra persona autorizada identifica la entrada, repite la acción, obtiene el mismo resultado, entiende los límites restantes y abre el artefacto sin depender de estado local no documentado.

Guías relacionadas

Estas páginas en el mismo idioma cubren etapas contiguas sin cambiar el propietario canónico del tema: