USB-HID-Feature-Report-Debugging: GET_REPORT, SET_REPORT, Vendor-Kommandos und fehlende Geräte-Settings

HID-Geräte sind nicht nur Tastaturen und Mäuse. Dazu gehören Security-Keys, Sensoren, Bedienfelder, Vendor-Tools, industrielle Geräte, Game-Controller, USV-Geräte und Custom-Konfigurations-Interfaces. Viele dieser Geräte nutzen HID-Feature-Reports für Konfiguration und Status. Wenn Feature-Reports fehlschlagen, suchen Nutzer nach "HID Feature Report not working", "GET_REPORT failed", "SET_REPORT failed", "HID report ID mismatch" und "USB HID vendor command timeout", weil normaler Input laufen kann, während die Konfiguration scheitert.

Bus Scope hilft, weil Feature-Reports oft über Endpoint Null als Control-Transfers laufen. Das tatsächliche Setup-Paket, Report-Typ, Report-ID, Länge und Response-Status zählen.

Was Feature-Reports sind

HID kennt mehrere Report-Typen:

• Input-Reports
• Output-Reports
• Feature-Reports

Input-Reports kommen oft auf Interrupt-IN-Endpoints. Feature-Reports werden üblicherweise mit Control-Transfers über GET_REPORT oder SET_REPORT angefragt.

Funktionieren die Buttons eines Geräts, aber das Settings-Panel nicht, kann das Feature-Report-Handling die Ursache sein.

Report-ID- und Längen-Mismatches

Viele HID-Geräte nutzen Report-IDs. Inkludiert der Host Report-ID 3 und erwartet die Firmware Report-ID 0, kann der Request fehlschlagen oder falsche Daten zurückgeben.

Häufige Bugs:

• Firmware lässt Report-ID-Byte weg.
• Host sendet falsche Report-Länge.
• Deskriptor deklariert eine Länge, Firmware gibt eine andere zurück.
• Feature-Report existiert in Firmware, aber nicht im Deskriptor.
• Deskriptor deklariert Report, den die Firmware nie implementiert.

Der HID-Report-Deskriptor und der Control-Transfer müssen verglichen werden.

GET_REPORT- und SET_REPORT-Evidence

Achten Sie auf:

• Setup-Paket-Request-Typ.
• HID GET_REPORT oder SET_REPORT.
• Report-Typ Feature.
• Report-ID.
• wLength.
• Data-Stage-Bytes.
• STALL oder Timeout.

Stallt das Gerät einen Feature-Report, den sein Deskriptor wirbt, sind Firmware- oder Deskriptor-Konsistenz verdächtig.

Vendor-Konfiguration über HID

Viele Produkte nutzen HID, weil es Custom-Kernel-Treiber vermeidet. Vendor-Settings können als Feature-Reports implementiert sein.

Beispiele:

• Sampling-Rate ändern.
• Firmware-Version lesen.
• LED-Mode setzen.
• Sensor-Bereich konfigurieren.
• Bootloader aktivieren.
• Kalibrier-Daten lesen.

Scheitern diese Kommandos, kann das Gerät trotzdem als valides HID-Gerät erscheinen.

Debug-Checkliste

Nutzen Sie diesen Ablauf:

1. Enumeration und HID-Deskriptor capturen.
2. HID-Report-Deskriptor speichern.
3. Feature-Report-Definitionen identifizieren.
4. Den fehlschlagenden GET_REPORT oder SET_REPORT capturen.
5. Report-ID prüfen.
6. Angefragte Länge prüfen.
7. Deskriptor-Länge mit Transfer-Länge vergleichen.
8. Nach STALL, Timeout oder kurzer Antwort suchen.
9. Funktionierende Input-Reports mit fehlschlagenden Feature-Reports vergleichen.
10. Deskriptor und Control-Transfer zusammen bewahren.

Enddiagnose

HID-Feature-Report-Fehler sind meist Deskriptor-, Report-ID-, Längen-, Firmware-State- oder Control-Transfer-Handling-Probleme. Input kann laufen, während Konfiguration scheitert.

Bus Scope legt den HID-Report-Contract und den exakten Control-Transfer offen, der fehlgeschlagen ist – so werden Feature-Report-Bugs diagnostizierbar statt mysteriöse Vendor-Tool-Fehler.