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

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.