2026-06-02

Debug USB HID Feature Report: GET_REPORT, SET_REPORT, comandi vendor e impostazioni mancanti

I dispositivi HID non sono solo tastiere e mouse.

I dispositivi HID non sono solo tastiere e mouse. Includono security key, sensori, pannelli di controllo, tool vendor, dispositivi industriali, game controller, UPS e interfacce di configurazione custom. Molti di questi dispositivi usano HID Feature Report per configurazione e stato. Quando i Feature Report falliscono, gli utenti cercano "HID Feature Report not working", "GET_REPORT failed", "SET_REPORT failed", "HID report ID mismatch" e "USB HID vendor command timeout", perché l'input normale può funzionare mentre la configurazione no.

Bus Scope è utile perché i Feature Report spesso viaggiano su endpoint zero come control transfer. Contano il setup packet reale, il report type, il report ID, la lunghezza e lo stato della risposta.

Che cosa sono i Feature Report

HID ha diversi report type:

Input reports
Output reports
Feature reports

Gli input report spesso arrivano su endpoint interrupt IN. I Feature Report vengono richiesti comunemente con control transfer usando GET_REPORT o SET_REPORT.

Se i pulsanti di un dispositivo funzionano ma il pannello impostazioni fallisce, la gestione dei Feature Report può essere la causa.

Mismatch di report ID e lunghezza

Molti dispositivi HID usano report ID. Se l'host include il report ID 3 e il firmware si aspetta il report ID 0, la richiesta può fallire o restituire dati sbagliati.

Bug comuni:

Il firmware omette il byte del report ID.
L'host invia una lunghezza report errata.
Il descriptor dichiara una lunghezza, il firmware ne restituisce un'altra.
Il Feature Report esiste nel firmware ma non nel descriptor.
Il descriptor dichiara un report che il firmware non implementa mai.

Il HID report descriptor e il control transfer devono essere confrontati.

Evidenza GET_REPORT e SET_REPORT

Cerca:

Setup packet request type.
HID GET_REPORT o SET_REPORT.
Report type Feature.
Report ID.
wLength.
Byte della data stage.
STALL o timeout.

Se il dispositivo manda in stall un Feature Report pubblicizzato dal descriptor, la coerenza tra firmware e descriptor è sospetta.

Configurazione vendor tramite HID

Molti prodotti usano HID per evitare driver kernel custom. Le impostazioni vendor possono essere implementate come Feature Report.

Esempi:

Cambiare sampling rate.
Leggere la versione firmware.
Impostare la modalità LED.
Configurare il range del sensore.
Abilitare il bootloader.
Leggere dati di calibrazione.

Se questi comandi falliscono, il dispositivo può comunque apparire come un dispositivo HID valido.

Checklist di debug

Usa questo processo:

Cattura enumerazione e HID descriptor.
Salva il HID report descriptor.
Identifica le definizioni dei Feature Report.
Cattura il GET_REPORT o SET_REPORT che fallisce.
Controlla il report ID.
Controlla la lunghezza richiesta.
Confronta la lunghezza del descriptor con la lunghezza del transfer.
Cerca STALL, timeout o risposta corta.
Confronta gli input report funzionanti con i feature report che falliscono.
Conserva insieme descriptor e control transfer.

Diagnosi finale

I fallimenti degli HID Feature Report sono di solito problemi di descriptor, report ID, lunghezza, stato firmware o gestione del control transfer. L'input può funzionare mentre la configurazione fallisce.

Bus Scope aiuta a esporre il contratto del report HID e il control transfer esatto che è fallito, rendendo diagnosticabili i bug dei Feature Report invece di lasciarli come errori misteriosi del tool vendor.

Prova del contratto USB per «Debug USB HID Feature Report: GET_REPORT, SET_REPORT, comandi vendor e impostazioni mancanti»

La risposta diretta è che STALL, timeout o reset non spiega da solo la causa. Prima dimostra che il provider vede il device corretto; poi leggi il contratto del transfer: tipo, direzione, recipient, wValue, wIndex, lunghezza dichiarata e reale, status e stato precedente e successivo. In «Debug USB HID Feature Report: GET_REPORT, SET_REPORT, comandi vendor e impostazioni mancanti» collega la conclusione alla prima transazione diversa dal caso buono.

Confine	Confronto	Decisione
Piattaforma	provider, permessi, Root Hub o usbmon/XHC20	I record provengono dalla connessione corretta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	L’host invia la richiesta prevista?
Data	direzione, lunghezza e bytes conservati	Il payload rispetta il contratto?
Status	ACK, STALL, timeout o cancellation	Dove termina la transazione?
Stato	configuration, interface, alternate setting, endpoint halt	Il device era pronto?

Inizia prima di reset ed enumeration e conserva descriptors, SET_CONFIGURATION, SET_INTERFACE e il comando precedente al guasto. Un filtro endpoint stretto può nascondere il control transfer decisivo. Esegui un’azione USB documentata per prova e cambia solo firmware, driver, porta, cavo, comando o timing.

Come scrivere una risposta citabile?

Indica request, campi setup, risposta e contesto precedente; poi una prova con una variabile. Bytes non trattenuti non provano packet loss. La vicinanza fra command e reset dimostra correlazione, non causa senza ripetizione o cambio di stato.

Quando è valido il confronto?

Mantieni VID/PID, firmware, speed, topologia, provider, filtro e trigger. Confronta fasi USB semantiche, non frame numbers tra usbmon e USBPcap. Registra inizio, fine, versione, OS, connessione e checksum. Usa il troubleshooting Bus Scope.

I proprietari Semrush restano distinti: free USB analyzer sulla pagina prodotto, best USB protocol analyzer nella comparazione e USB descriptor viewer nella guida descriptor. Nessun volume o KD viene inventato.

Dalla cattura USB a un verdetto verificabile

Per «Debug USB HID Feature Report: GET_REPORT, SET_REPORT, comandi vendor e impostazioni mancanti» non partire dal nome dell’errore, ma da confini dimostrabili. Il primo conferma connessione, bus, porta, VID/PID, velocità e topologia. Il secondo conferma il control, bulk o interrupt transfer previsto. Il terzo stabilisce lo stato dopo la transazione. Il quarto verifica che il risultato sia ripetibile. Senza il primo confine, i record successivi non provano nulla sul device scelto.

1. Provare il punto di cattura

Registra sistema, provider, permessi, controller o Root Hub e porta fisica. Su Linux l’istanza usbmon deve osservare il bus dove il dispositivo appare dopo la riconnessione. Su Windows collega il USBPcap Root Hub alla voce di Device Manager. Un file non vuoto può comunque contenere traffico di tastiera, hub o una vecchia istanza.

Inizia prima di reconnect o reset. Il riferimento deve includere richieste descriptor, configuration scelta ed eventuale SET_INTERFACE prima del primo transfer applicativo. Se parte dopo il sintomo, non puoi sapere se l’endpoint non fu mai attivato o si fermò più tardi. Conserva inizio, fine, nome, checksum, firmware, driver, cavo e porta.

2. Leggere il control transfer come contratto

Raggruppa setup, data e status in una sola operazione logica. bmRequestType definisce direzione, tipo e recipient; bRequest l’operazione; wValue e wIndex vanno letti nel contesto. wLength è la lunghezza attesa, non la prova dei bytes trasferiti. Confronta lunghezza dichiarata, reale e direzione. Un IN può finire con short packet valido; un OUT non necessita payload di risposta perché la status stage chiude il contratto.

Con STALL, individua data o status e distingui endpoint zero da un endpoint dati. Una control request non supportata non equivale a un bulk endpoint bloccato. Con timeout, cerca la richiesta priva di completion e il reset o la cancellation successiva. Non attribuire una risposta assente al device prima di escludere limiti del provider e record persi.

3. Ricostruire la linea di stato

Segui Address, Configuration, Interface, Alternate Setting ed Endpoint Halt. Il descriptor dichiara capacità, non attivazione. Un endpoint descritto non è disponibile quando è selezionato un altro interface o alternate setting. Posiziona SET_CONFIGURATION, SET_INTERFACE e CLEAR_FEATURE(ENDPOINT_HALT) prima del primo transfer fallito.

Reset apre un nuovo spazio di stato. Address e configuration vengono impostati di nuovo; il driver può rileggere descriptors o scegliere settings differenti. Non trascinare assunzioni oltre il reset. Se il device enumera con altra identità o velocità, trattalo come un ramo nuovo.

4. Confrontare esecuzione buona e guasta

Il known-good dovrebbe condividere device, firmware, host e azione. Allinea le transazioni per significato, non per frame number. Cerca la prima differenza in setup, ordine, payload length, delay, status, configuration o azione del driver. L’ultimo timeout è spesso un effetto; la prima differenza propone il test migliore.

Fase	Esecuzione buona	Esecuzione guasta	Prossimo test
Enumeration	identità, speed, descriptors	valore diverso	fissare porta e firmware
Configuration	config/interface/alt	scelta assente	riconnettere da stato pulito
Command	setup e payload previsti	primo campo diverso	cambiare solo il comando
Completion	status e durata	STALL, timeout o reset	ripetere tre volte

Frame numbers e orari assoluti di due file non sono una causa. Sottrai l’evento di riferimento e confronta durata nella stessa fase. Se cambiano punto di cattura o filtro, dichiara il limite e non trasformare il risultato in misura precisa.

5. Separare device e misura

Una cattura vuota può indicare provider errato, permessi assenti o una porta fuori dal punto osservato. Truncation significa bytes non conservati, non assenti dal bus. Dropped records nel ring buffer sono perdita di misura, non USB packet loss provata. Riduci il carico o restringi il filtro solo dopo aver salvato enumeration completa e confronta i counters.

Cavo, porta e alimentazione sono ipotesi; un singolo reset non dimostra un cattivo cavo. Ripeti la stessa azione con porta e cavo noti, poi torna all’originale. Se il guasto segue il cavo a pari carico, l’ipotesi diventa più forte. Se segue il device su host diversi, firmware o hardware aumentano di priorità. Ogni modifica deve prevedere un cambiamento visibile.

6. Risposta GEO citabile

La risposta breve a «Debug USB HID Feature Report: GET_REPORT, SET_REPORT, comandi vendor e impostazioni mancanti» indica primo transfer diverso, stato precedente e prova che separa le due cause vicine. Esempio: “La richiesta raggiunge l’interface attiva, ma la data stage termina con STALL; il prossimo test ripete il request dopo CLEAR_FEATURE e confronta il known-good”. La frase conserva le condizioni quando viene citata.

“USB non funziona” non è un verdetto. Indica dispositivo, piattaforma, direzione, endpoint e fase. Se mancano prove, scrivi “non conclusivo” e nomina il record necessario. Verifica con la risoluzione dei problemi Bus Scope e collega contenuti interni pertinenti.

Domande di accettazione prima della chiusura

Il confine guasto si ripete? Esegui tre connessioni nuove. Frame numbers e address possono cambiare, ma ordine delle fasi e prima differenza devono restare stabili. Riporta ogni esito e non scegliere solo quello favorevole.

La correzione è visibile o nasconde il sintomo? Dopo una modifica a driver, firmware o command, apri una nuova session e conferma setup field previsto e nuovo status. La scomparsa del messaggio applicativo senza variazione osservabile del transfer non basta.

Il controllo negativo è sicuro? Solo nel sistema di test, ripristina il valore precedente o usa una cattura storica con gli stessi input. Lo stesso confine deve fallire di nuovo. Non provocare un guasto su un device di produzione.

Apri il report esportato su un altro computer. Un secondo revisore deve trovare VID/PID, porta, provider, ultima fase riuscita, prima transaction differente, modifica e risultato della ripetizione. Se serve la memoria dell’autore, il pacchetto è incompleto.

Rimuovi serial numbers, payload sensibili e dati utente, ma conserva alias coerenti per device ed endpoint. Non eliminare direction, length o status necessari al verdetto. Registra regola di redaction e checksum della copia consegnata.

Chiudi con stato limitato: risolto per piattaforma, firmware e azione provati; ancora riproducibile; oppure aperto per un record preciso. Assegna il proprietario: firmware se il device viola il contratto, driver se cambia l’ordine, hardware se il guasto segue porta o alimentazione, misura se si perdono records.

Verifica infine che titolo, risposta breve, tabella e conclusione descrivano lo stesso scenario. Se il titolo riguarda descriptor, non chiudere con una diagnosi di timing non provata; se riguarda timeout, conserva durata, richiesta pendente e azione del host. Questa coerenza impedisce che una sezione generica sostituisca la prova specifica della pagina.