2026-06-02

Depuración de descriptores USB para dispositivos HID y CDC

Cómo los equipos de firmware pueden diagnosticar dispositivos USB HID y CDC inspeccionando evidencia de descriptores y transferencias en lugar de adivinar a partir de errores de driver.

Los dispositivos HID y CDC son populares porque permiten a los equipos de firmware lanzar interfaces USB útiles sin escribir un driver a medida para cada host. Esa comodidad depende de que los descriptores sean precisos. Cuando un teclado HID, un sensor, un bridge serie o un dispositivo compuesto falla, la causa raíz suele ser visible en la evidencia de descriptores antes de aparecer en la aplicación.

Depurar descriptores no es glamuroso, pero es una de las formas más rápidas de cerrar casos de soporte USB.

HID: el report descriptor es el contrato

Para dispositivos HID, el host necesita más que información de endpoints. Necesita el HID report descriptor. Ese descriptor define los report IDs, usages, tamaños, recuentos, rangos lógicos y cómo se deben interpretar los bytes.

Errores HID frecuentes:

La longitud del report no encaja con los payloads reales del endpoint interrupt.
El report ID se usa en firmware pero no se declara de forma consistente.
Los valores logical min y max no coinciden con la representación de los datos.
El usage page o el usage no coinciden con lo que espera el host.
El endpoint interval no es realista para el comportamiento del dispositivo.
Las suposiciones de boot protocol entran en conflicto con el comportamiento de report protocol.

Un error del host puede sonar vago. Una captura que enseñe los bytes del descriptor y las transferencias de interrupt puede hacer evidente el desajuste.

CDC: el layout de interfaces importa

Los dispositivos CDC ACM suelen exponer una interfaz de comunicación y una interfaz de datos. El host espera un conjunto coherente de descriptores y class-specific requests. Un functional descriptor que falta, un interface association equivocado o un desajuste de endpoint pueden impedir que aparezca el puerto serie virtual.

Evidencia a inspeccionar:

Interface class y subclass.
Descriptores CDC header, ACM, union y call management.
Notification endpoint.
Endpoints bulk IN y OUT.
SET_LINE_CODING.
SET_CONTROL_LINE_STATE.
Transferencias de datos tras la configuración.

Si el puerto serie aparece pero no se mueven bytes, el problema puede estar en el comportamiento del endpoint o en el protocolo de aplicación. Si el puerto serie nunca aparece, descriptores y class requests son lo primero que hay que mirar.

Los dispositivos compuestos exigen disciplina extra

Los dispositivos compuestos pueden combinar HID, CDC, mass storage, interfaces vendor-specific y más. Es útil, pero multiplica los modos de fallo. Un error de descriptor en una interfaz puede afectar al binding de host para todo el dispositivo.

Para depurar compuestos, inspecciona:

Longitud total de la configuración.
Números de interfaz.
Interface Association Descriptors.
Unicidad de endpoints.
Posición de los class-specific descriptors.
Peticiones del host por interfaz.

No des por sentado que "el firmware manda los bytes correctos" hasta que la captura demuestre que el host vio la estructura correcta.

Por qué importan tanto los bytes en crudo como la interpretación de clase

Los bytes en crudo son la verdad de los hechos. La interpretación de clase los hace útiles. Una buena herramienta de diagnóstico USB debería enseñar ambas. Los ingenieros necesitan ver los bytes exactos del descriptor cuando algo va mal, pero también necesitan campos decodificados para no tener que contar offsets a mano en cada caso.

El mejor flujo es:

Inspeccionar el árbol de descriptores decodificado.
Saltar a los bytes en crudo para los campos sospechosos.
Comparar las peticiones del host con las respuestas del firmware.
Inspeccionar las transferencias de endpoint tras la configuración.
Guardar la sesión para reproducción o entrega a soporte.

Ese flujo mantiene el diagnóstico atado a la evidencia.

Dónde encaja Bus Scope

Bus Scope está pensado para equipos de firmware, laboratorios de hardware y fabricantes de dispositivos que necesitan una respuesta repetible a por qué falla el tráfico USB. Mantiene el contexto del explorador de dispositivos, el detalle de paquetes, los bytes en crudo, los descriptores, las observaciones de clase, los filtros y las sesiones .bscope guardadas en un único banco de trabajo.

Para casos HID y CDC, Bus Scope debería ayudar a responder:

¿La enumeración terminó?
¿Los descriptores coincidían con la clase objetivo?
¿Mandó el host las class requests esperadas?
¿Las transferencias de endpoint coincidieron con las expectativas del report o del line coding?
¿Es esto un problema de firmware, driver del host o protocolo de aplicación?

Esa es la diferencia entre ver "driver failed" y entender qué contrato USB se rompió.

Prueba del contrato USB para «Depuración de descriptores USB para dispositivos HID y CDC»

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 de descriptores USB para dispositivos HID y CDC», 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 de descriptores USB para dispositivos HID y CDC» es: Cómo los equipos de firmware pueden diagnosticar dispositivos USB HID y CDC inspeccionando evidencia de descriptores y transferencias en lugar de adivinar a partir de errores de driver. 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 de descriptores USB para dispositivos HID y CDC

Si «Depuración de descriptores USB para dispositivos HID y CDC» es ambiguo, compare un caso bueno y otro fallido bajo condiciones equivalentes. Marque la primera diferencia significativa en vez de enumerar todos los síntomas posteriores. Ese límite suele producir una consulta más clara y un experimento más seguro.

Punto de control 2: Cómo los equipos de firmware pueden diagnosticar dispositivos USB HID y CDC inspeccionando

Compruebe «Cómo los equipos de firmware pueden diagnosticar dispositivos USB HID y CDC inspeccionando evidencia de descriptores y transferencias en lugar de adiv» con la entrada representativa más pequeña. Mantenga iguales los ajustes no relacionados, repita la misma acción y revise el resultado después de reabrir o reconectar. Una captura aislada es más débil que un registro con entrada, ajuste, acción, salida y hora.

Punto de control 3: HID: el report descriptor es el contrato

Si «HID: el report descriptor es el contrato» es ambiguo, compare un caso bueno y otro fallido bajo condiciones equivalentes. Marque la primera diferencia significativa en vez de enumerar todos los síntomas posteriores. Ese límite suele producir una consulta más clara y un experimento más seguro.

Punto de control 4: CDC: el layout de interfaces importa

Compruebe «CDC: el layout de interfaces importa» con la entrada representativa más pequeña. Mantenga iguales los ajustes no relacionados, repita la misma acción y revise el resultado después de reabrir o reconectar. Una captura aislada es más débil que un registro con entrada, ajuste, acción, salida y hora.

Punto de control 5: Los dispositivos compuestos exigen disciplina extra

Si «Los dispositivos compuestos exigen disciplina extra» es ambiguo, compare un caso bueno y otro fallido bajo condiciones equivalentes. Marque la primera diferencia significativa en vez de enumerar todos los síntomas posteriores. Ese límite suele producir una consulta más clara y un experimento más seguro.

Punto de control 6: Por qué importan tanto los bytes en crudo como la interpretación de clase

Compruebe «Por qué importan tanto los bytes en crudo como la interpretación de clase» con la entrada representativa más pequeña. Mantenga iguales los ajustes no relacionados, repita la misma acción y revise el resultado después de reabrir o reconectar. Una captura aislada es más débil que un registro con entrada, ajuste, acción, salida y hora.

Punto de control 7: Dónde encaja Bus Scope

Si «Dónde encaja Bus Scope» es ambiguo, compare un caso bueno y otro fallido bajo condiciones equivalentes. Marque la primera diferencia significativa en vez de enumerar todos los síntomas posteriores. Ese límite suele producir una consulta más clara y un experimento más seguro.

Punto de control 8: Prueba del contrato USB para «Depuración de descriptores USB para dispositivos HID y CDC»

Compruebe «Prueba del contrato USB para «Depuración de descriptores USB para dispositivos HID y CDC»» con la entrada representativa más pequeña. Mantenga iguales los ajustes no relacionados, repita la misma acción y revise el resultado después de reabrir o reconectar. Una captura aislada es más débil que un registro con entrada, ajuste, acción, salida y hora.

Punto de control 9: ¿Cómo se escribe una respuesta citable?

Si «¿Cómo se escribe una respuesta citable?» es ambiguo, compare un caso bueno y otro fallido bajo condiciones equivalentes. Marque la primera diferencia significativa en vez de enumerar todos los síntomas posteriores. Ese límite suele producir una consulta más clara y un experimento más seguro.

Punto de control 10: ¿Cuándo vale una comparación?

Compruebe «¿Cuándo vale una comparación?» con la entrada representativa más pequeña. Mantenga iguales los ajustes no relacionados, repita la misma acción y revise el resultado después de reabrir o reconectar. Una captura aislada es más débil que un registro con entrada, ajuste, acción, salida y hora.

Matriz de aceptación

Punto	Evidencia que conservar	Condición de aprobado
Depuración de descriptores USB para dispositivos HID y CDC	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Cómo los equipos de firmware pueden diagnosticar dispositivos USB HID y CDC inspeccionando evidencia de descriptores y t	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
HID: el report descriptor es el contrato	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
CDC: el layout de interfaces importa	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Los dispositivos compuestos exigen disciplina extra	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Por qué importan tanto los bytes en crudo como la interpretación de clase	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: