Risoluzione dei problemi del touchscreen USB su Linux: un flusso di lavoro pratico con evtest e libinput

Un touchscreen USB può comparire nell'elenco dei dispositivi USB mentre l'applicazione continua a non ricevere alcun input touch utilizzabile. Per individuare il livello malfunzionante, testare il percorso in ordine: identità del dispositivo, nodo eventi del kernel, eventi di contatto, libinput e l'applicazione. Mantenere lo stesso touchscreen e gli stessi movimenti di test per tutta la durata, in modo che ogni confronto risponda a una domanda specifica.

Questo flusso di lavoro per la risoluzione dei problemi dei touchscreen USB su Linux copre i controller touch che espongono un'interfaccia evdev. Utilizza comandi diagnostici in sola lettura e propone una procedura da banco ripetibile. Durante la stesura non è stato collegato alcun touchscreen target; i comandi sono stati verificati rispetto alla documentazione e la procedura non costituisce una qualificazione hardware completata.

1. Registrare l'ambiente e individuare il dispositivo USB

Iniziare, quando possibile, con un touchscreen noto. Separare nelle proprie note la connessione del display da quella del touch. Un'immagine video funzionante non dimostra che il controller touch USB sia stato enumerato.

uname -r

Registrare la versione del kernel e quali strumenti sono disponibili. Nomi dei pacchetti, permessi di accesso e versioni degli strumenti variano in base alla distribuzione. Se un comando è mancante, ottenere lo strumento appropriato tramite la procedura documentata della propria distribuzione prima di seguire quella parte del test.

lsusb elenca i dispositivi USB.^[8] Corrispondere una voce di controller plausibile alla documentazione hardware o a un record di dispositivo esistente. Un nome di prodotto può essere generico, quindi conservare anche gli identificatori di vendor e product. La sola enumerazione USB non prova che il kernel abbia creato un nodo eventi touch né che la GUI possa utilizzarlo.

In /proc/bus/input/devices, cercare un dispositivo di input candidato e il relativo event handler. Linux espone gli eventi di input del kernel allo userspace tramite nodi evdev quali /dev/input/event7.^[1] Un controller può esporre più di un'interfaccia di input. Non selezionare un nodo solo perché il suo nome contiene “USB”.”

Se l'identità USB attesa è assente, risolvere prima questa questione di enumerazione. Registrare la configurazione della connessione e se il dispositivo compare in modo coerente. I successivi test sugli eventi non possono diagnosticare un dispositivo privo di un percorso di input identificato.

2. Confermare il nodo eventi prima di catturare il touch

In ogni comando seguente, N è un segnaposto. Sostituirlo con il numero di evento identificato sulla propria macchina; non digitare la lettera N alla lettera.

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

udevadm info legge informazioni dal database dei dispositivi. Quando disponibili, gli identificatori USB, un numero di serie o il percorso del dispositivo aiutano a collegare il nodo al controller.^[7] Le proprietà possono variare o essere assenti. Conservare l'output insieme alla cattura invece di presumere che un numero di evento identifichi lo stesso dispositivo dopo una riconnessione.

evtest stampa le capacità del dispositivo e poi monitora gli eventi. La lettura del nodo spesso richiede permessi elevati.^[2] Utilizzare i permessi appropriati al proprio sistema di test. Non modificare il nodo per un accesso scrivibile da tutti. Premere Ctrl+C per terminare ogni sessione di monitoraggio.

Iniziare con tutte le dita sollevate. Toccare il centro una volta con un dito, poi sollevare. Confermare che questa azione produca eventi sul nodo candidato. Leggere le capacità per gli assi assoluti e per eventuali campi multi-touch. Un nodo che espone solo controlli non correlati non è l'interfaccia touch necessaria.

Se rimangono plausibili più nodi, terminare una sessione e ispezionare il candidato successivo. Tenere una nota che colleghi ciascun nodo alla sua identità e alla risposta osservata. Questo evita di interpretare il silenzio dell'interfaccia sbagliata come un guasto del controller.

Non aggiungere --grab. Un grab esclusivo modifica quali client ricevono input e interferirebbe con il successivo confronto dell'applicazione.

3. Leggere il vocabolario degli eventi prima di giudicare la traccia

I report di input sono stateful: i valori invariati non devono necessariamente riapparire. EV_ABS identifica gli eventi ad asse assoluto, e SYN_REPORT separa i frame di input. SYN_DROPPED indica overflow della coda eventi del client.^[3] Una cattura contenente quel marcatore è incompleta; ripetere una cattura più breve e segnalare la perdita. Non utilizzare una sequenza incompleta per dimostrare un rilascio mancante o un guasto hardware.

Leggere i limiti degli assi stampati per il dispositivo. Questi sono unità di input grezze, non necessariamente pixel LCD. Un valore vicino al massimo X grezzo non significa che l'applicazione debba posizionare il puntatore a una coordinata pixel numericamente identica.

Cercare un ciclo di vita del contatto oltre ai cambiamenti di posizione. I campi esatti dipendono dalle capacità. Non presumere che ogni dispositivo riporti la pressione, supporti più contatti o utilizzi lo stesso protocollo.

Per un dispositivo che utilizza il protocollo multi-touch di tipo B, gli slot mantengono lo stato. Un ABS_MT_TRACKING_ID non negativo identifica un contatto; -1 ne indica il rilascio. ABS_MT_POSITION_X e ABS_MT_POSITION_Y ne descrivono la posizione. ABS_MT_SLOT può essere assente quando lo slot selezionato non è cambiato.^[4]

Di conseguenza, un dito fermo non deve produrre coordinate ripetute. Una traccia che elenca solo il dito in movimento può comunque descrivere due contatti attivi. Ricostruire lo stato mantenuto prima di dichiarare l'altro dito mancante.

4. Eseguire un test raw-input a cinque punti e due tratti

Mantenere evtest l'esecuzione sul nodo confermato. Utilizzare il seguente protocollo proposto per rendere le catture confrontabili tra le esecuzioni. Verifica la copertura di base e la continuità; non stabilisce una soglia di precisione universale.

1. Toccare il centro una volta, tenere brevemente e sollevare completamente.
2. Ripetere nelle aree superiore sinistra, superiore destra, inferiore destra e inferiore sinistra. Mantenere ogni punto visibilmente all'interno dell'area touch attiva anziché sulla cornice.
3. Tracciare un tratto orizzontale lento attraverso l'area utilizzabile, quindi sollevare.
4. Tracciare un tratto verticale lento, quindi sollevare.
5. Ripetere qualsiasi azione dubbia da sola in una cattura più breve.

Per ogni tocco, registrare se appare un nuovo contatto, se la sua posizione rientra nei limiti degli assi riportati e se il sollevamento finale termina il contatto. Confrontare le posizioni tra i cinque punti. Dovrebbero formare uno schema spaziale ripetibile, ma gli assi raw possono differire in direzione rispetto all'immagine visualizzata. Documentare se ciascun asse raw aumenta o diminuisce con ogni movimento fisico, quindi confrontarlo con l'orientamento previsto dal progetto. L'angolo superiore sinistro fisico non deve necessariamente corrispondere a entrambi i minimi degli assi su un assemblaggio ruotato o specchiato.

Per ogni tratto, cercare una sequenza di cambiamenti di posizione corrispondenti al movimento. Registrare salti improvvisi, terminazioni inaspettate del contatto o valori che smettono ripetutamente di coprire parte dell'area prevista. Un tratto fisico orizzontale può cambiare principalmente l'altro asse raw su un assemblaggio ruotato; tale osservazione è una prova utile, non un difetto automatico.

Ripetere lo stesso movimento se qualcosa sembra errato. Annotare se l'anomalia si ripete nella stessa posizione o si verifica in modo imprevedibile. Entrambi gli schemi possono guidare ulteriori indagini, ma nessuno dei due da solo identifica il componente guasto.

Un'osservazione di base riuscita è una pressione completa, movimento e rilascio con copertura ripetibile. Non stabilisce la precisione di produzione, la latenza, le prestazioni ambientali o l'affidabilità a lungo termine. Questi richiedono criteri di accettazione specifici per l'applicazione e un piano di qualifica separato.

5. Testare contatti multipli solo quando supportato

Procedere solo se la capacità documentata del dispositivo e l'interfaccia eventi supportano il test multi-touch previsto. In caso contrario, registrare la limitazione anziché interpretare un risultato a contatto singolo come un test a due dita fallito.

Per un dispositivo di tipo B supportato, posizionare un dito vicino al lato sinistro e tenerlo fermo. Posizionare un secondo dito vicino al lato destro. Muovere solo il secondo dito, sollevarlo, quindi muovere e sollevare il primo. Infine, ripetere con i ruoli invertiti.

Avviare la cattura con entrambe le dita sollevate, quindi tracciare le identità dei contatti e lo stato degli slot mantenuti attraverso i frame. Le osservazioni utili sono due contatti attivi distinguibili, movimento associato al contatto previsto, rilascio di un contatto mentre l'altro rimane attivo e rilascio dell'ultimo contatto. Lo slot selezionato o le coordinate stazionarie possono non ripetersi in ogni frame.

Mantenere le due dita sufficientemente distanti per rendere chiare le azioni previste. Questo test verifica se il ciclo di vita riportato segue la procedura. Non è una certificazione del conteggio dei contatti né una misura della spaziatura minima.

Se la sequenza raw è ambigua, ripetere solo la transizione che ha causato dubbi. Una cattura breve di “secondo dito giù, secondo dito su, primo dito su” è più facile da rivedere rispetto a una sessione lunga contenente molti gesti non correlati.

6. Confrontare libinput con le stesse azioni fisiche

Terminare evtest, quindi ispezionare libinput:

sudo libinput list-devices

libinput list-devices mostra i dispositivi riconosciuti da libinput, le loro capacità e i valori predefiniti integrati. Non riporta la configurazione effettiva del desktop.^[5] Trovare il nodo eventi confermato e ispezionare la capacità touch riportata. Non fare affidamento su un layout fisso delle colonne di output per l'analisi automatizzata.

libinput debug-events monitora gli eventi in un contesto separato. Il suo comportamento può differire da quello del compositor o dell'applicazione.^[6] Ripetere il tocco centrale, il tratto orizzontale e il rilascio finale. Se supportato, ripetere la sequenza a due contatti. Terminare la sessione con Ctrl+C.

Se il touch raw è coerente ma libinput non riconosce il nodo come previsto, conservare entrambi gli output. L'indagine successiva riguarda il riconoscimento, la classificazione o l'ambiente userspace testato. Il confronto ha ristretto la questione; non ha dimostrato che il pannello o il firmware del controller sia difettoso.

Se entrambi gli strumenti mostrano un touch coerente, passare all'applicazione effettiva. Un test libinput separato non può certificare l'associazione display, la rotazione o la gestione degli eventi dell'applicazione da parte del compositor.

7. Individuare il livello guasto senza ipotizzare una correzione

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 La guida ai moduli touchscreen; 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.

Riferimenti

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.