HID-Report-Deskriptor-Debugging: Warum das Gerät enumeriert, der Host aber die falschen Daten liest

HID ist attraktiv, weil viele Geräte ohne eigene Treiber auskommen. Tastaturen, Sensoren, Drehregler, Barcode-Reader, Bedienfelder und herstellerspezifische HID-Geräte profitieren alle von einem Standard-Host-Stack. Aber HID verlagert die Komplexität in den Report-Deskriptor. Ein Gerät kann korrekt enumerieren und trotzdem Daten senden, die der Host falsch interpretiert.

Das ist eine der häufigsten USB-Firmware-Fallen: Man verwechselt erfolgreiche Enumeration mit HID-Korrektheit.

Der Report-Deskriptor definiert den Datenvertrag

Der HID-Report-Deskriptor sagt dem Host, wie er Bytes interpretieren soll. Er definiert Usages, Report-Größen, Report-Counts, logische Bereiche, physische Bereiche, Collections und Report-IDs. Wenn der Deskriptor das eine sagt und die Firmware etwas anderes sendet, folgt der Host dem Deskriptor.

Häufige Probleme:

• Firmware sendet 8 Bytes, der Deskriptor beschreibt aber 7
• Report-ID fehlt oder ist überflüssig
• Signed-Werte werden als unsigned beschrieben
• Logical Min/Max passt nicht zum tatsächlichen Bereich
• Usage Page ist falsch
• Padding-Bits werden falsch gezählt
• Mehrere Reports teilen sich ein verwirrendes Layout
• Input- und Output-Reports werden verwechselt

Das Symptom zeigt sich in der App als falsche Werte, fehlende Buttons, ignorierte Reports oder sporadisches Leseverhalten.

Erfassen Sie Deskriptor und Reports zusammen

HID-Debugging allein anhand des Report-Deskriptors ist unvollständig. Debugging allein anhand der Payload-Bytes ist ebenfalls unvollständig. Sie brauchen beides.

Ein brauchbarer HID-Capture zeigt:

• Device-Deskriptor
• Konfigurations- und Interface-Deskriptoren
• HID-Deskriptor
• Report-Deskriptor-Anfrage und Antwort
• Interrupt-IN-Reports
• Interrupt-OUT-Reports, falls verwendet
• Control-Transfers für Feature-Reports
• Report-IDs und Payload-Längen

Danach kann der Engineer das deklarierte Layout mit den tatsächlichen Bytes vergleichen. Sagt der Report-Deskriptor Report Count 3, aber die Interrupt-Payload trägt vier Werte, muss der Capture das sichtbar machen.

Host-Verhalten kann korrekt sein, auch wenn es falsch aussieht

Firmware-Entwickler glauben manchmal, der Host lasse Daten fallen. In Wirklichkeit parsed der Host nach dem Deskriptor, den er bekommen hat. Deklariert der Deskriptor Padding oder eine andere Report-ID, wirken die Daten verschoben, abgeschnitten oder ignoriert.

Deshalb sollte ein guter Support-Report Rohbytes enthalten. Eine dekodierte Interpretation ist nützlich, aber Rohbytes schlichten den Streit. Die Frage lautet:

• Was hat die Firmware gesendet?
• Was hat die Firmware deklariert?
• Was hat der Host angefragt?
• Was hat der Host bekommen?

Das ist die richtige Grenze für HID-Debugging.

Composite-HID-Geräte brauchen Extra-Sorgfalt

Composite-Devices können HID plus CDC, Storage oder herstellerspezifische Interfaces bereitstellen. Der HID-Teil kann für sich korrekt sein, wird aber durch Fehler in Interface-Nummerierung, Endpoint-Zuweisung oder Deskriptor-Gesamtlänge beeinflusst.

Für Composite-HID-Debugging prüfen Sie:

• Interface-Association, falls vorhanden
• Interface-Nummer
• Eindeutigkeit der Endpoint-Adresse
• Position des HID-Deskriptors
• Länge des Report-Deskriptors
• Class-specific Request-Routing

Wenn ein Host den Report-Deskriptor vom falschen Interface anfordert oder die falsche Länge bekommt, wird der spätere Report-Traffic irreführend.

Wo Bus Scope passt

Bus Scope ist für Firmware- und Device-Teams gedacht, die beweisorientiertes USB-Debugging brauchen. Für HID-Report-Deskriptor-Fälle soll es Engineers ermöglichen, Deskriptor-Baum, Rohbytes, Endpoint-Traffic und gespeicherte .bscope-Session gemeinsam zu inspizieren.

Das praktische Ergebnis ist ein Report, der sagt:

• HID-Report-Deskriptor wurde angefragt und zurückgegeben
• Vom Deskriptor deklarierte Report-Länge
• Tatsächliche Interrupt-Payload-Länge
• Report-ID-Verhalten
• Mismatch oder Konsistenz zwischen Deklaration und Traffic
• Nächster Schritt in Firmware-Deskriptor, Report-Packing oder Host-Parser-Erwartungen

Das ist nützlicher als "HID-Gerät funktioniert nicht". Es macht aus einem vagen Input-Problem einen konkreten USB-Contract-Mismatch.