Solução de problemas de tela de toque USB no Linux: Um fluxo de trabalho prático com evtest e libinput

Um ecrã tátil USB pode aparecer na lista de dispositivos USB enquanto a aplicação continua a não receber qualquer entrada tátil utilizável. Para identificar a camada com falha, teste o percurso por ordem: identidade do dispositivo, nó de eventos do kernel, eventos de contacto, libinput e a aplicação. Mantenha o mesmo ecrã tátil e os mesmos movimentos de teste ao longo de todo o processo, para que cada comparação responda a uma questão específica.

Este fluxo de trabalho de resolução de problemas de ecrãs táteis USB em Linux abrange controladores táteis que expõem uma interface evdev. Utiliza comandos de diagnóstico apenas de leitura e propõe um procedimento de bancada repetível. Nenhum ecrã tátil alvo foi ligado durante a elaboração; os comandos foram verificados com base na documentação, e o procedimento não constitui uma qualificação de hardware concluída.

1. Registar o ambiente e localizar o dispositivo USB

Comece, sempre que possível, com um ecrã tátil conhecido. Separe a ligação do ecrã da ligação tátil nas suas notas. Uma imagem de vídeo funcional não prova que o controlador tátil USB foi enumerado.

uname -r

Registe a versão do kernel e quais ferramentas estão disponíveis. Os nomes dos pacotes, as permissões de acesso e as versões das ferramentas variam consoante a distribuição. Se faltar um comando, obtenha a ferramenta adequada através do processo documentado da sua distribuição antes de prosseguir com essa parte do teste.

lsusb lista os dispositivos USB.^[8] Faça corresponder uma entrada de controlador plausível à documentação do hardware ou a um registo de dispositivo existente. Um nome de produto pode ser genérico, pelo que deve também preservar os identificadores de fabricante e de produto. A enumeração USB por si só não prova que o kernel criou um nó de eventos táteis nem que a interface gráfica o consegue utilizar.

Em /proc/bus/input/devices, procure um dispositivo de entrada candidato e o respetivo handler de eventos. O Linux expõe os eventos de entrada do kernel ao espaço de utilizador através de nós evdev como /dev/input/event7.^[1] Um controlador pode expor mais do que uma interface de entrada. Não selecione um nó apenas porque o seu nome inclui “USB”.”

Se a identidade USB esperada estiver ausente, resolva primeiro essa questão de enumeração. Registe a disposição da ligação e se o dispositivo aparece de forma consistente. Os testes de eventos posteriores não conseguem diagnosticar um dispositivo que não tem um percurso de entrada identificado.

2. Confirmar o nó de eventos antes de capturar o toque

Em todos os comandos abaixo, N é um marcador de posição. Substitua-o pelo número de evento identificado na sua máquina; não escreva a letra N literalmente.

udevadm info --query=property --name=/dev/input/eventN

udevadm info lê informações da base de dados de dispositivos. Quando disponíveis, os identificadores USB, um número de série ou o caminho do dispositivo ajudam a ligar o nó ao controlador.^[7] As propriedades podem variar ou estar ausentes. Guarde a saída juntamente com a captura, em vez de assumir que um número de evento identificará o mesmo dispositivo após uma reconexão.

evtest imprime as capacidades do dispositivo e depois monitoriza eventos. A leitura do nó requer frequentemente permissões elevadas.^[2] Utilize as permissões adequadas ao seu sistema de teste. Não altere o nó para acesso gravável por todos. Prima Ctrl+C para terminar cada sessão de monitorização.

Comece com todos os dedos levantados. Toque uma vez no centro com um dedo e depois levante-o. Confirme que esta ação produz eventos no nó candidato. Leia as capacidades relativas a eixos absolutos e a quaisquer campos multi-toque. Um nó que expõe apenas controlos não relacionados não é a interface tátil de que necessita.

Se vários nós continuarem a ser plausíveis, termine uma sessão e inspecione o próximo candidato. Mantenha uma nota que associe cada nó à sua identidade e à resposta observada. Isto evita interpretar o silêncio da interface errada como uma falha do controlador.

Não adicione --grab. Um grab exclusivo altera quais os clientes que recebem entrada e interferiria com a comparação posterior da aplicação.

3. Ler o vocabulário de eventos antes de avaliar o trace

Os relatórios de entrada são stateful: os valores inalterados não precisam de voltar a aparecer. EV_ABS identifica eventos de eixo absoluto, e SYN_REPORT separa frames de entrada. SYN_DROPPED indica overflow da fila de eventos do cliente.^[3] Uma captura que contenha esse marcador está incompleta; repita uma captura mais curta e reporte a perda. Não utilize uma sequência incompleta para provar uma libertação em falta ou uma falha de hardware.

Leia os limites dos eixos impressos para o dispositivo. Estas são unidades de entrada em bruto, não necessariamente píxeis do LCD. Um valor próximo do máximo X em bruto não significa que a aplicação deva colocar o ponteiro numa coordenada de píxel numericamente idêntica.

Procure um ciclo de vida do contacto, bem como alterações de posição. Os campos exatos dependem das capacidades. Não assuma que todos os dispositivos reportam pressão, suportam múltiplos contactos ou utilizam o mesmo protocolo.

Para um dispositivo que utiliza o protocolo multi-toque tipo B, os slots retêm estado. Um ABS_MT_TRACKING_ID não negativo identifica um contacto; -1 marca a sua libertação. ABS_MT_POSITION_X e ABS_MT_POSITION_Y descrevem a sua posição. ABS_MT_SLOT pode estar ausente quando o slot selecionado não mudou.^[4]

Consequentemente, um dedo estacionário não precisa produzir coordenadas repetidas. Um traço que lista apenas o dedo em movimento ainda pode descrever dois contatos ativos. Reconstrua o estado retido antes de declarar o outro dedo ausente.

4. Execute um teste de entrada bruta de cinco pontos e dois traços

Manter evtest em execução no nó confirmado. Use o seguinte protocolo proposto para tornar as capturas comparáveis entre execuções. Ele verifica cobertura básica e continuidade; não estabelece um limiar universal de precisão.

1. Toque o centro uma vez, mantenha brevemente e levante completamente.
2. Repita nas áreas superior esquerda, superior direita, inferior direita e inferior esquerda. Mantenha cada ponto visivelmente dentro da área de toque ativa, e não sobre a borda.
3. Desenhe um traço horizontal lento através da área utilizável e, em seguida, levante.
4. Desenhe um traço vertical lento e, em seguida, levante.
5. Repita qualquer ação questionável isoladamente em uma captura mais curta.

Para cada toque, registre se um novo contato aparece, se sua posição está dentro dos limites dos eixos reportados e se o levantamento final encerra o contato. Compare as posições entre os cinco pontos. Elas devem formar um padrão espacial repetível, mas os eixos brutos podem diferir em direção da imagem exibida. Documente se cada eixo bruto aumenta ou diminui com cada movimento físico e, em seguida, compare isso com a orientação pretendida do projeto. O canto superior esquerdo físico não precisa corresponder a ambos os mínimos dos eixos em uma montagem rotacionada ou espelhada.

Para cada traço, procure uma sequência de mudanças de posição correspondentes ao movimento. Registre saltos súbitos, encerramentos inesperados de contato ou valores que repetidamente deixam de cobrir parte da área pretendida. Um traço físico horizontal pode alterar principalmente o outro eixo bruto em uma montagem rotacionada; essa observação é evidência útil, não um defeito automático.

Repita o mesmo movimento se algo parecer errado. Anote se a anomalia se repete no mesmo local ou ocorre de forma imprevisível. Qualquer um dos padrões pode orientar investigações adicionais, mas nenhum deles sozinho identifica o componente com falha.

Uma observação básica bem-sucedida é pressão completa, movimento e liberação com cobertura repetível. Isso não estabelece precisão de produção, latência, desempenho ambiental ou confiabilidade de longo prazo. Esses requisitos exigem critérios de aceitação específicos da aplicação e um plano de qualificação separado.

5. Teste múltiplos contatos apenas quando suportado

Prossiga apenas se a capacidade documentada do dispositivo e a interface de eventos suportarem o teste multi-toque pretendido. Caso contrário, registre a limitação em vez de interpretar um resultado de contato único como um teste de dois dedos malsucedido.

Para um dispositivo tipo B suportado, coloque um dedo próximo ao lado esquerdo e mantenha-o imóvel. Coloque um segundo dedo próximo ao lado direito. Mova apenas o segundo dedo, levante-o e, em seguida, mova e levante o primeiro. Por fim, repita com os papéis invertidos.

Inicie a captura com ambos os dedos levantados e, em seguida, rastreie as identidades de contato e o estado do slot retido entre os quadros. As observações úteis são dois contatos ativos distinguíveis, movimento associado ao contato pretendido, liberação de um contato enquanto o outro permanece ativo e liberação do último contato. O slot selecionado ou as coordenadas estacionárias podem não se repetir em cada quadro.

Mantenha os dois dedos suficientemente afastados para tornar as ações pretendidas claras. Este teste verifica se o ciclo de vida reportado segue o procedimento. Não é uma certificação de contagem de contatos nem uma medição de espaçamento mínimo.

Se a sequência bruta for ambígua, repita apenas a transição que causou dúvida. Uma captura curta de “segundo dedo para baixo, segundo dedo para cima, primeiro dedo para cima” é mais fácil de revisar do que uma sessão longa contendo muitos gestos não relacionados.

6. Compare o libinput com as mesmas ações físicas

Encerrar evtest, e, em seguida, inspecione o libinput:

sudo libinput list-devices

libinput list-devices mostra os dispositivos reconhecidos pelo libinput, suas capacidades e padrões integrados. Não reporta a configuração real do desktop.^[5] Localize o nó de evento confirmado e inspecione sua capacidade de toque reportada. Não dependa de um layout fixo de colunas de saída para análise automatizada.

libinput debug-events monitora eventos em um contexto separado. Seu comportamento pode diferir do compositor ou da aplicação.^[6] Repita o toque central, o traço horizontal e a liberação final. Se suportado, repita a sequência de dois contatos. Encerre a sessão com Ctrl+C.

Se o toque bruto for coerente mas o libinput não reconhecer o nó como esperado, preserve ambas as saídas. A próxima investigação diz respeito ao reconhecimento, classificação ou ao ambiente de userspace testado. A comparação estreitou a questão; não provou que o painel ou o firmware do controlador está defeituoso.

Se ambas as ferramentas mostrarem toque coerente, passe para a aplicação real. Um teste separado do libinput não pode certificar a associação de exibição, rotação ou tratamento de eventos da aplicação pelo compositor.

7. Localize a camada com falha sem adivinhar uma correção

An open device handle does not prove an exclusive grab. Likewise, no events do not prove failed hardware: a wrong node, access condition, grab, or driver path can produce a silent capture. Avoid changing several settings at once; doing so removes the controlled comparison.

In the application, repeat the same five points and strokes. Record whether the mismatch affects the whole desktop, one output, or one application. Inspect the configuration actually used by that compositor or toolkit. This guide does not prescribe a universal calibration matrix.

8. Prepare a small, reproducible technical handoff

Provide the display and touch-controller models, USB identifiers, kernel release, tool versions, confirmed event node, and capability output. Include a short event excerpt tied to exact physical actions, plus the observed difference between raw input, libinput, and the application. State whether the capture contains any dropped-event marker.

Also describe the host, display orientation, connected outputs, touch connection, and application environment. Remove unrelated output. A concise reproduction gives another engineer a better starting point than a large log labeled only “touch does not work.”

For broader module requirements, see the guia de módulos de ecrã tátil; for a separate platform architecture discussion, see Android touch and HDMI touch. To request project-specific review, send RJY the model details and the bounded test record. RJY can discuss documented display and touch-module requirements from that record. Compatibility and any adaptation of an existing module still require verification for the actual controller, host, software, and application.

Referências

1. Linux kernel documentation: input subsystem introduction.
2. Debian manual: evtest.
3. Linux kernel documentation: input event codes.
4. Linux kernel documentation: multi-touch protocol.
5. libinput documentation: helper tools.
6. Debian manual: libinput debug-events.
7. systemd documentation: udevadm.
8. Debian manual: lsusb.