2026-06-02

Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando

Como diagnosticar falhas em HID Feature Report, GET_REPORT, SET_REPORT, report IDs, transferências de controle, comandos vendor, configuração de dispositivo e bugs de firmware USB HID.

Dispositivos HID não são só teclados e mouses. Incluem chaves de segurança, sensores, painéis de controle, ferramentas vendor, dispositivos industriais, controles, nobreaks e interfaces de configuração customizadas. Muitos desses dispositivos usam HID Feature Reports para configuração e status. Quando os Feature Reports falham, a busca costuma ser por "HID Feature Report not working", "GET_REPORT failed", "SET_REPORT failed", "HID report ID mismatch" e "USB HID vendor command timeout" porque a entrada normal pode funcionar enquanto a configuração não.

O Bus Scope ajuda porque Feature Reports geralmente trafegam pelo endpoint zero como transferências de controle. Importam o pacote de setup, o report type, o report ID, o tamanho e o status de resposta.

O que são Feature Reports

HID tem vários tipos de relatório:

Input reports
Output reports
Feature reports

Input reports geralmente chegam pelos endpoints interrupt IN. Feature reports são normalmente solicitados com transferências de controle usando GET_REPORT ou SET_REPORT.

Se os botões de um dispositivo funcionam, mas o painel de configuração falha, o tratamento de Feature Report pode ser o motivo.

Incompatibilidades de Report ID e tamanho

Muitos dispositivos HID usam report IDs. Se o host inclui report ID 3 e o firmware espera report ID 0, a requisição pode falhar ou devolver dados errados.

Bugs comuns:

Firmware omite o byte de report ID.
Host envia o tamanho errado do relatório.
Descritor declara um tamanho, firmware devolve outro.
Feature report existe no firmware, mas não no descritor.
Descritor declara relatório que o firmware nunca implementa.

O descritor de relatório HID e a transferência de controle precisam ser comparados.

Evidência em GET_REPORT e SET_REPORT

Procure por:

request type do pacote de setup.
HID GET_REPORT ou SET_REPORT.
Report type Feature.
Report ID.
wLength.
Bytes do data stage.
STALL ou timeout.

Se o dispositivo trava um Feature Report que o descritor anuncia, a consistência entre firmware e descritor é a suspeita.

Configuração vendor via HID

Muitos produtos usam HID justamente para evitar drivers customizados no kernel. Configurações vendor podem ser implementadas como Feature Reports.

Exemplos:

Mudar a taxa de amostragem.
Ler a versão de firmware.
Definir o modo de LED.
Configurar a faixa do sensor.
Habilitar o bootloader.
Ler dados de calibração.

Se esses comandos falham, o dispositivo ainda pode aparecer como um HID válido.

Checklist de depuração

Use este processo:

Capture a enumeração e o descritor HID.
Salve o descritor de relatório HID.
Identifique as definições de Feature Report.
Capture o GET_REPORT ou SET_REPORT que falhou.
Confira o report ID.
Confira o tamanho requisitado.
Compare o tamanho do descritor com o tamanho da transferência.
Procure STALL, timeout ou resposta curta.
Compare os input reports que funcionam com os feature reports que falham.
Preserve descritor e transferência de controle juntos.

Diagnóstico final

Falhas em HID Feature Report geralmente são problemas de descritor, report ID, tamanho, estado do firmware ou tratamento da transferência de controle. A entrada pode funcionar enquanto a configuração falha.

O Bus Scope ajuda a expor o contrato de relatório HID e a transferência de controle exata que falhou, tornando bugs de Feature Report diagnosticáveis em vez de erros misteriosos da ferramenta vendor.

Teste do contrato USB para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”

A resposta direta é que STALL, timeout ou reset não explica sozinho a causa. Primeiro prove que o provider vê o device correto; depois leia o contrato do transfer: tipo, direção, recipient, wValue, wIndex, comprimento declarado e real, status e estado anterior e posterior. Ligue a conclusão à primeira transação diferente do caso bom.

Limite	Comparação	Decisão
Plataforma	provider, permissão, Root Hub ou usbmon/XHC20	Os records são da conexão correta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	O host enviou o pedido esperado?
Data	direção, comprimento e bytes retidos	O payload cumpre o contrato?
Status	ACK, STALL, timeout ou cancellation	Onde a transação termina?
Estado	configuration, interface, alternate setting, halt	O device estava pronto?

Comece antes de reset e enumeration e preserve descriptors, SET_CONFIGURATION, SET_INTERFACE e o command anterior à falha. Filtro estreito pode esconder o control transfer decisivo. Execute uma ação USB por teste e altere apenas firmware, driver, porta, cabo, comando ou timing.

Como escrever resposta citável?

Informe request, campos setup, resposta e contexto anterior; depois proponha teste com uma variável. Bytes não retidos não provam packet loss. Proximidade entre command e reset mostra correlação, não causa sem repetição ou mudança de estado.

Mantenha VID/PID, firmware, speed, topologia, provider, filtro e trigger. Compare fases USB semânticas, não frame numbers entre usbmon e USBPcap. Registre início, fim, versão, OS, conexão e checksum. Consulte o troubleshooting Bus Scope.

Os owners Semrush continuam separados: free USB analyzer na página do produto, best USB protocol analyzer na comparação e USB descriptor viewer no guia descriptor. Não invente volume ou KD.

Resposta direta e limite de aceitação

A resposta curta para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando” é: Como diagnosticar falhas em HID Feature Report, GET_REPORT, SET_REPORT, report IDs, transferências de controle, comandos vendor, configuração de dispositivo e bugs de firmware USB HID. Trate essa frase como um resultado a verificar, não como promessa para qualquer entrada, dispositivo, projeto ou ambiente. Um resultado completo registra estado inicial, ação exata, saída visível e condição que comprova a conclusão da tarefa no Bus Scope.

Procedimento orientado por evidências

Comece com um caso pequeno e repetível antes de alterar um projeto completo. Registre versão do aplicativo, sistema operacional, identidade da entrada ou dispositivo, configurações relevantes e resultado esperado. Execute uma ação deliberada, preserve a primeira transição inesperada e compare com um caso conhecido quando possível. Alterar vários controles ao mesmo tempo esconde qual condição criou ou corrigiu o problema.

Ponto de controle 1: Depuração de HID Feature Report: GETREPORT, SETREPORT, comandos vendor e configurações fal

Converta “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 2: Como diagnosticar falhas em HID Feature Report, GETREPORT, SETREPORT, report IDs, transfer

Trate “Como diagnosticar falhas em HID Feature Report, GET_REPORT, SET_REPORT, report IDs, transferências de controle, comandos vendor, configuração de dispo” como uma etapa de aceitação separada para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 3: O que são Feature Reports

Converta “O que são Feature Reports” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 4: Incompatibilidades de Report ID e tamanho

Trate “Incompatibilidades de Report ID e tamanho” como uma etapa de aceitação separada para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 5: Evidência em GETREPORT e SETREPORT

Converta “Evidência em GETREPORT e SETREPORT” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 6: Configuração vendor via HID

Trate “Configuração vendor via HID” como uma etapa de aceitação separada para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 7: Checklist de depuração

Converta “Checklist de depuração” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 8: Diagnóstico final

Trate “Diagnóstico final” como uma etapa de aceitação separada para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Ponto de controle 9: Teste do contrato USB para “Depuração de HID Feature Report: GETREPORT, SETREPORT, comando

Converta “Teste do contrato USB para “Depuração de HID Feature Report: GETREPORT, SETREPORT, comandos vendor e configurações faltando”” em uma declaração reproduzível de aprovação ou falha. Inclua o que deve aparecer, o que deve estar ausente e qual recuperação é segura. Preserve o projeto ou captura original até a cópia corrigida passar pelo mesmo teste.

Ponto de controle 10: Como escrever resposta citável?

Trate “Como escrever resposta citável?” como uma etapa de aceitação separada para “Depuração de HID Feature Report: GET_REPORT, SET_REPORT, comandos vendor e configurações faltando”. Registre o estado antes da ação, a primeira mudança visível e o estado final. Se o resultado divergir do objetivo descrito, volte ao último ponto confirmado em vez de continuar com suposições.

Matriz de aceitação

Ponto	Evidência a manter	Condição de aprovação
Depuração de HID Feature Report: GETREPORT, SETREPORT, comandos vendor e configurações faltando	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Como diagnosticar falhas em HID Feature Report, GETREPORT, SETREPORT, report IDs, transferências de controle, comandos v	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
O que são Feature Reports	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Incompatibilidades de Report ID e tamanho	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Evidência em GETREPORT e SETREPORT	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Configuração vendor via HID	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado

Isolamento, recuperação e entrega

Pare no primeiro limite que falhar. Preserve fonte, projeto, sessão ou captura, duplique antes de edição destrutiva e altere uma variável por experimento. Repetir um fluxo amplo depois de várias mudanças pode gerar outro resultado sem explicar o motivo.

Separe ausência de evidência de evidência de ausência. Uma tela vazia pode indicar entrada, escopo, filtro, permissão, dispositivo, intervalo ou estado incorreto. Verifique aquisição ou importação antes de interpretar decoder, editor, relatório ou exportação.

Antes da entrega, reabra o artefato e examine início, ponto de decisão e final. Registre versão, plataforma, configuração, expectativa, observação e reprodução mínima. Remova ou oculte dados sensíveis e confirme a autorização do destinatário.

Perguntas e respostas

Qual é a maneira confiável mais rápida de começar?

Use o menor caso representativo, escreva o resultado esperado e altere uma variável. Confirme o caminho básico antes de adicionar filtros, efeitos, edições, automação ou uma fonte maior.

Quais evidências devem ser salvas?

Mantenha identidade da entrada, versão, plataforma, configurações, ação exata, primeira transição inesperada e saída final. Feche e reabra projeto, sessão, relatório ou exportação antes de tratá-lo como durável.

Quando o procedimento deve ser repetido?

Repita após mudanças relevantes no aplicativo, sistema, driver, firmware, modelo, fonte ou fluxo. Preserve o caso aceito anterior como referência sem alterações.

Quando a tarefa está pronta para entrega?

Quando outra pessoa autorizada identifica a entrada, repete a ação, vê o mesmo resultado, entende os limites restantes e abre o artefato sem depender de estado local não documentado.

Guias relacionados

Estas páginas no mesmo idioma cobrem etapas próximas sem alterar o proprietário canônico deste assunto: