2026-06-02

Depuración del report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos

Cómo diagnosticar errores del report descriptor HID que hacen que un dispositivo USB se enumere sin problemas pero se comporte mal en el host.

HID es atractivo porque muchos dispositivos funcionan sin drivers a medida. Teclados, sensores, knobs, lectores de códigos de barras, paneles de control e HID específicos del fabricante se apoyan en la pila estándar del host. Pero HID mueve la complejidad al report descriptor. Un dispositivo puede enumerar correctamente y aun así enviar datos que el host interpreta mal.

Esta es una de las trampas más comunes del firmware USB: confundir una enumeración exitosa con un HID correcto.

El report descriptor define el contrato de datos

El HID report descriptor le dice al host cómo interpretar los bytes. Define usages, tamaños de informe, recuentos, rangos lógicos, rangos físicos, collections y report IDs. Si el descriptor dice una cosa y el firmware envía otra, el host hace caso al descriptor.

Errores típicos:

El firmware envía 8 bytes pero el descriptor describe 7.
Falta un report ID o sobra.
Valores con signo declarados como sin signo.
Logical min/max que no coincide con el rango real.
Usage page equivocada.
Bits de padding contados mal.
Varios reports compartiendo un layout confuso.
Input reports y output reports mezclados.

El síntoma puede aparecer en la aplicación como valores raros, botones que no responden, reports ignorados o lecturas intermitentes.

Captura el descriptor y los reports juntos

Depurar HID solo con el report descriptor no basta. Depurar solo con los bytes de payload tampoco. Necesitas las dos cosas.

Una captura HID útil muestra:

Device descriptor.
Configuration e interface descriptors.
HID descriptor.
Petición y respuesta del report descriptor.
Interrupt IN reports.
Interrupt OUT reports, si se usan.
Transferencias de control para feature reports.
Report IDs y longitudes de payload.

Entonces puedes comparar el layout declarado con los bytes reales. Si el report descriptor dice "Report Count 3" y el payload del endpoint lleva cuatro valores, la captura debería hacer evidente esa diferencia.

El host puede estar haciendo lo correcto aunque parezca que no

A veces el desarrollador de firmware cree que el host está perdiendo datos. En realidad, el host está parseando según el descriptor que recibió. Si el descriptor declara padding o un report ID distinto, los datos aparecen desplazados, truncados o simplemente ignorados.

Por eso un buen informe de soporte debería incluir los bytes en crudo. La interpretación decodificada ayuda, pero los bytes en bruto zanjan la discusión. La pregunta se convierte en:

¿Qué envió el firmware?
¿Qué declaró el firmware?
¿Qué pidió el host?
¿Qué recibió el host?

Ese es el límite correcto de la depuración HID.

Los HID compuestos necesitan mimo extra

Un dispositivo compuesto puede exponer HID junto con CDC, almacenamiento o interfaces vendor. La parte HID puede ser correcta por sí sola, pero quedar afectada por errores de numeración de interfaz, asignación de endpoints o por una suma de longitudes de descriptor mal calculada.

Para depurar HID compuesto, revisa:

Interface Association, cuando aplique.
Número de interfaz.
Unicidad de direcciones de endpoint.
Ubicación del HID descriptor.
Longitud del report descriptor.
Enrutamiento de peticiones class-specific.

Si el host pide el report descriptor desde la interfaz que no es o recibe una longitud incorrecta, el tráfico de reports posterior se vuelve engañoso.

Dónde encaja Bus Scope

Bus Scope está pensado para equipos de firmware y dispositivo que necesitan depuración USB guiada por evidencia. Para casos de report descriptor HID, debería permitir inspeccionar juntos el árbol de descriptores, los bytes en bruto, el tráfico de endpoints y la sesión .bscope guardada.

El resultado práctico debería ser un informe que diga:

El HID report descriptor se pidió y se devolvió.
Longitud de report declarada por el descriptor.
Longitud real del payload de interrupt.
Comportamiento del report ID.
Coherencia o discrepancia entre la declaración y el tráfico.
Siguiente acción en el descriptor del firmware, el empaquetado de reports o las expectativas del parser del host.

Eso es mucho más útil que "el HID no va". Convierte un problema de input difuso en una discrepancia concreta del contrato USB.

Prueba del contrato USB para «Depuración del report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos»

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 report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos», 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 report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos» es: Cómo diagnosticar errores del report descriptor HID que hacen que un dispositivo USB se enumere sin problemas pero se comporte mal en el host. 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 report descriptor HID: por qué el dispositivo enumera pero el host lee dato

Compruebe «Depuración del report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos» 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 2: Cómo diagnosticar errores del report descriptor HID que hacen que un dispositivo USB se en

Si «Cómo diagnosticar errores del report descriptor HID que hacen que un dispositivo USB se enumere sin problemas pero se comporte mal en el host.» 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 3: El report descriptor define el contrato de datos

Compruebe «El report descriptor define el contrato de datos» 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 4: Captura el descriptor y los reports juntos

Si «Captura el descriptor y los reports juntos» 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 5: El host puede estar haciendo lo correcto aunque parezca que no

Compruebe «El host puede estar haciendo lo correcto aunque parezca que no» 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 6: Los HID compuestos necesitan mimo extra

Si «Los HID compuestos necesitan mimo 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 7: Dónde encaja Bus Scope

Compruebe «Dónde encaja Bus Scope» 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 8: Prueba del contrato USB para «Depuración del report descriptor HID: por qué el dispositivo

Si «Prueba del contrato USB para «Depuración del report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos»» 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 9: ¿Cómo se escribe una respuesta citable?

Compruebe «¿Cómo se escribe una respuesta citable?» 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 10: ¿Cuándo vale una comparación?

Si «¿Cuándo vale una comparación?» 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.

Matriz de aceptación

Punto	Evidencia que conservar	Condición de aprobado
Depuración del report descriptor HID: por qué el dispositivo enumera pero el host lee datos incorrectos	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Cómo diagnosticar errores del report descriptor HID que hacen que un dispositivo USB se enumere sin problemas pero se co	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
El report descriptor define el contrato de datos	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Captura el descriptor y los reports juntos	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
El host puede estar haciendo lo correcto aunque parezca que no	Estado inicial, una acción y estado resultante	Otra persona reproduce el resultado declarado
Los HID compuestos necesitan mimo extra	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: