Solución de problemas de pantalla táctil USB en Linux: Un flujo de trabajo práctico con evtest y libinput

Una pantalla táctil USB puede aparecer en la lista de dispositivos USB mientras la aplicación sigue sin recibir entrada táctil utilizable. Para encontrar la capa que falla, pruebe la ruta en orden: identidad del dispositivo, nodo de eventos del kernel, eventos de contacto, libinput y la aplicación. Mantenga la misma pantalla táctil y los mismos movimientos de prueba durante todo el proceso para que cada comparación responda a una pregunta específica.

Este flujo de trabajo de solución de problemas de pantallas táctiles USB en Linux abarca controladores táctiles que exponen una interfaz evdev. Utiliza comandos de diagnóstico de solo lectura y propone un procedimiento de banco repetible. No se conectó ninguna pantalla táctil objetivo durante la elaboración; los comandos se verificaron contra la documentación, y el procedimiento no constituye una calificación de hardware completada.

1. Registrar el entorno y encontrar el dispositivo USB

Comience con una pantalla táctil conocida cuando sea posible. Separe la conexión de pantalla de la conexión táctil en sus notas. Una imagen de video funcional no establece que el controlador táctil USB se haya enumerado.

uname -r

Registre la versión del kernel y qué herramientas están disponibles. Los nombres de paquetes, los permisos de acceso y las versiones de las herramientas varían según la distribución. Si falta un comando, obtenga la herramienta adecuada mediante el proceso documentado de su distribución antes de seguir esa parte de la prueba.

lsusb lista los dispositivos USB.^[8] Haga coincidir una entrada de controlador plausible con la documentación del hardware o un registro de dispositivo existente. Un nombre de producto puede ser genérico, así que conserve también los identificadores de proveedor y producto. La enumeración USB por sí sola no prueba que el kernel haya creado un nodo de eventos táctiles ni que la GUI pueda utilizarlo.

En /proc/bus/input/devices, busque un dispositivo de entrada candidato y su controlador de eventos. Linux expone los eventos de entrada del kernel al espacio de usuario mediante nodos evdev como /dev/input/event7.^[1] Un controlador puede exponer más de una interfaz de entrada. No seleccione un nodo solo porque su nombre incluya “USB”.”

Si la identidad USB esperada está ausente, resuelva primero esa cuestión de enumeración. Registre la disposición de la conexión y si el dispositivo aparece de forma consistente. Las pruebas de eventos posteriores no pueden diagnosticar un dispositivo que no tiene una ruta de entrada identificada.

2. Confirmar el nodo de eventos antes de capturar el toque

En cada comando a continuación, N es un marcador de posición. Reemplácelo con el número de evento identificado en su máquina; no escriba la letra N literalmente.

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

udevadm info lee información de la base de datos de dispositivos. Cuando estén disponibles, los identificadores USB, un número de serie o la ruta del dispositivo ayudan a vincular el nodo con el controlador.^[7] Las propiedades pueden variar o estar ausentes. Conserve la salida junto con la captura en lugar de asumir que un número de evento identificará el mismo dispositivo tras una reconexión.

evtest imprime las capacidades del dispositivo y luego monitorea eventos. Leer el nodo a menudo requiere permisos elevados.^[2] Utilice los permisos apropiados para su sistema de prueba. No cambie el nodo a acceso escribible por todos. Presione Ctrl+C para finalizar cada sesión de monitoreo.

Comience con todos los dedos levantados. Toque el centro una vez con un dedo, luego levante. Confirme que esta acción produce eventos en el nodo candidato. Lea las capacidades para ejes absolutos y cualquier campo multitáctil. Un nodo que expone solo controles no relacionados no es la interfaz táctil que necesita.

Si varios nodos siguen siendo plausibles, finalice una sesión e inspeccione el siguiente candidato. Mantenga una nota que vincule cada nodo con su identidad y la respuesta observada. Esto evita interpretar el silencio de la interfaz equivocada como una falla del controlador.

No agregue --grab. Una captura exclusiva cambia qué clientes reciben la entrada e interferiría con la comparación posterior de la aplicación.

3. Leer el vocabulario de eventos antes de juzgar la traza

Los informes de entrada son con estado: los valores sin cambios no necesitan aparecer de nuevo. EV_ABS identifica eventos de eje absoluto, y SYN_REPORT separa tramas de entrada. SYN_DROPPED indica desbordamiento de la cola de eventos del cliente.^[3] Una captura que contenga ese marcador está incompleta; repita una captura más corta e informe la pérdida. No utilice una secuencia incompleta para probar una liberación faltante o una falla de hardware.

Lea los límites de eje impresos para el dispositivo. Estas son unidades de entrada sin procesar, no necesariamente píxeles del LCD. Un valor cercano al máximo X sin procesar no significa que la aplicación deba colocar el puntero en una coordenada de píxel numéricamente idéntica.

Busque un ciclo de vida del contacto así como cambios de posición. Los campos exactos dependen de las capacidades. No asuma que cada dispositivo informa presión, admite múltiples contactos o utiliza el mismo protocolo.

Para un dispositivo que utiliza el protocolo multitáctil tipo B, las ranuras conservan estado. Un ABS_MT_TRACKING_ID no negativo identifica un contacto; -1 marca su liberación. ABS_MT_POSITION_X integrada y el ABS_MT_POSITION_Y describir su posición. ABS_MT_SLOT puede estar ausente cuando la ranura seleccionada no ha cambiado.^[4]

En consecuencia, un dedo estacionario no necesita producir coordenadas repetidas. Una traza que solo enumera el dedo en movimiento aún puede describir dos contactos activos. Reconstruya el estado retenido antes de declarar que el otro dedo falta.

4. Ejecutar una prueba de entrada sin procesar de cinco puntos y dos trazos

Mantener evtest ejecutándose en el nodo confirmado. Utilice el siguiente protocolo propuesto para que las capturas sean comparables entre ejecuciones. Comprueba la cobertura básica y la continuidad; no establece un umbral de precisión universal.

1. Toque el centro una vez, mantenga brevemente y levante completamente.
2. Repita en las áreas superior izquierda, superior derecha, inferior derecha e inferior izquierda. Mantenga cada punto visiblemente dentro del área táctil activa en lugar de sobre el bisel.
3. Dibuje un trazo horizontal lento a través del área utilizable, luego levante.
4. Dibuje un trazo vertical lento, luego levante.
5. Repita cualquier acción cuestionable por sí sola en una captura más corta.

Para cada toque, registre si aparece un nuevo contacto, si su posición se encuentra dentro de los límites de eje reportados y si el levantamiento final termina el contacto. Compare las posiciones entre los cinco puntos. Deberían formar un patrón espacial repetible, pero los ejes sin procesar pueden diferir en dirección respecto a la imagen mostrada. Documente si cada eje sin procesar aumenta o disminuye con cada movimiento físico, luego compare esto con la orientación prevista del proyecto. La parte superior izquierda física no necesita corresponder a ambos mínimos de eje en un ensamblaje rotado o reflejado.

Para cada trazo, busque una secuencia de cambios de posición correspondientes al movimiento. Registre saltos repentinos, finalizaciones inesperadas de contacto o valores que repetidamente dejan de cubrir parte del área prevista. Un trazo físico horizontal puede cambiar principalmente el otro eje sin procesar en un ensamblaje rotado; esa observación es evidencia útil, no un defecto automático.

Repita el mismo movimiento si algo parece incorrecto. Anote si la anomalía se repite en la misma ubicación o ocurre de forma impredecible. Cualquiera de los dos patrones puede guiar una investigación adicional, pero ninguno por sí solo identifica el componente fallido.

Una observación básica exitosa es presión completa, movimiento y liberación con cobertura repetible. No establece precisión de producción, latencia, rendimiento ambiental ni confiabilidad a largo plazo. Esos requieren criterios de aceptación específicos de la aplicación y un plan de calificación separado.

5. Probar múltiples contactos solo cuando sea compatible

Proceda solo si la capacidad documentada del dispositivo y la interfaz de eventos admiten la prueba multitáctil prevista. Si no es así, registre la limitación en lugar de interpretar un resultado de contacto único como una prueba de dos dedos fallida.

Para un dispositivo tipo B compatible, coloque un dedo cerca del lado izquierdo y manténgalo quieto. Coloque un segundo dedo cerca del lado derecho. Mueva solo el segundo dedo, levántelo, luego mueva y levante el primero. Finalmente, repita con los roles invertidos.

Inicie la captura con ambos dedos levantados, luego rastree las identidades de contacto y el estado de ranura retenido entre fotogramas. Las observaciones útiles son dos contactos activos distinguibles, movimiento asociado con el contacto previsto, liberación de un contacto mientras el otro permanece activo, y liberación del último contacto. La ranura seleccionada o las coordenadas estacionarias pueden no repetirse en cada fotograma.

Mantenga los dos dedos suficientemente separados para que las acciones previstas sean claras. Esta prueba verifica si el ciclo de vida reportado sigue el procedimiento. No es una certificación de recuento de contactos ni una medición de separación mínima.

Si la secuencia sin procesar es ambigua, repita solo la transición que causó duda. Una captura corta de “segundo dedo abajo, segundo dedo arriba, primer dedo arriba” es más fácil de revisar que una sesión larga que contiene muchos gestos no relacionados.

6. Comparar libinput con las mismas acciones físicas

Finalizar evtest, luego inspeccione libinput:

sudo libinput list-devices

libinput list-devices muestra los dispositivos reconocidos por libinput, sus capacidades y los valores predeterminados integrados. No informa la configuración real del escritorio.^[5] Encuentre el nodo de eventos confirmado e inspeccione su capacidad táctil reportada. No dependa de un diseño fijo de columnas de salida para el análisis automatizado.

libinput debug-events monitorea eventos en un contexto separado. Su comportamiento puede diferir del compositor o de la aplicación.^[6] Repita el toque central, el trazo horizontal y la liberación final. Si es compatible, repita la secuencia de dos contactos. Finalice la sesión con Ctrl+C.

Si el tacto sin procesar es coherente pero libinput no reconoce el nodo como se esperaba, conserve ambas salidas. La siguiente investigación concierne al reconocimiento, la clasificación o el entorno de espacio de usuario probado. La comparación ha acotado la pregunta; no ha demostrado que el panel o el firmware del controlador sean defectuosos.

Si ambas herramientas muestran un tacto coherente, pase a la aplicación real. Una prueba separada de libinput no puede certificar la asociación de pantalla del compositor, la rotación ni el manejo de eventos de la aplicación.

7. Localizar la capa fallida sin adivinar una solución

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 touchscreen module guide; 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.

Referencias

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.