Using xinput to Configure Linux X11 Touchscreens

This article provides an overview of how the Linux operating system uses the xinput utility to control and calibrate touchscreen hardware under the X11 display architecture. It covers the underlying communication between the Linux kernel, the X server, and input drivers, followed by the practical steps required to query, map, calibrate, and persist touchscreen settings using xinput.

The Architecture: Kernel to X11

The Linux operating system processes touchscreen inputs through a layered architecture:

  1. Kernel Level (evdev): When you touch a physical digitizer, the hardware generates hardware interrupts handled by a kernel driver. The kernel exposes these interactions via the event device subsystem (/dev/input/event*).
  2. X Server Driver (xf86-input-libinput or evdev): The X.Org Server reads these raw kernel events through an input driver—most commonly libinput on modern distributions. The driver normalizes raw multi-touch and absolute coordinate data into X11 core protocol events.
  3. XInput Extension: The X server exposes these inputs via the X Input Extension (XInput), currently at version 2 (XI2).
  4. The xinput Tool: The xinput command-line utility directly interfaces with the XInput extension, allowing users and scripts to dynamically query hardware states and modify driver properties at runtime without restarting the display server.

Identifying the Touchscreen

To manage a device, the X server must first identify it. Running the following command lists all recognized input devices, split into master and slave pointers/keyboards:

xinput list

Look for the device name corresponding to your touchscreen digitizer under the Virtual core pointer hierarchy. Note either its full string name or its numerical id.

Inspecting Runtime Properties

Every driver exposes a set of configurable runtime parameters to the X server. To view the active properties of a specific touchscreen:

xinput list-props <device-id-or-name>

Output properties typically include:

Mapping and Rotating with the Transformation Matrix

The primary method Linux uses to align touch coordinates with display outputs is the Coordinate Transformation Matrix. This 3x3 matrix maps input coordinates \((x, y)\) to display coordinates \((x', y')\).

[ c0  c1  c2 ]
[ c3  c4  c5 ]
[ c6  c7  c8 ]

By default, the matrix is set to the identity matrix (1 0 0 0 1 0 0 0 1). You can change this using xinput set-prop:

xinput set-prop <device-id> "Coordinate Transformation Matrix" c0 c1 c2 c3 c4 c5 c6 c7 c8

Common transformations include:

Real-Time Event Debugging

To verify that the X server receives input coordinates and button clicks accurately, xinput can capture raw events in real time:

xinput test <device-id>

Touching the screen will output real-time absolute motion events (motion a[0]=... a[1]=...) and button state transitions.

Persisting xinput Configurations

Changes made via the xinput command are stored in the X server's memory and are lost when the display server restarts or when the device is unplugged. To make configurations permanent across reboots, Linux supports two primary approaches:

  1. Xorg Configuration Files (Recommended for system-wide persistence):
    Create an InputClass configuration file inside /etc/X11/xorg.conf.d/ (e.g., 99-touchscreen.conf):

    Section "InputClass"
    Identifier "Touchscreen Calibration"
    MatchProduct "Your Touchscreen Name"
    MatchDevicePath "/dev/input/event*"
    Driver "libinput"
    Option "TransformationMatrix" "1 0 0 0 1 0 0 0 1"
EndSection

  2. Session Startup Scripts (User-level persistence):
    Add the specific xinput set-prop or xinput map-to-output commands to user session initialization files, such as ~/.xprofile, ~/.xinitrc, or the autostart utility of your desktop environment.