Linux calibration (AXX/BXX) using a 3rd party app (xinput Calibrator)

The calibration method described in the How to set-up a touchfoil on Mac Linux Android and Media Players article is the preferred method as it has the advantage of storing the calibration data in the touchfoil’s controller board.  This means that should you need to replace the PC or the media box, you can do so without the need of re-calibrating as long as the relative position of the display and the touchfoil remain the same.                       

However, if for some reason you are unable to use a Windows PC or you prefer to perform the calibration directly on your Linux machine, a third party calibration application provides an alternative. The process is described for an Ubuntu system as an example below.

First, install xinput_calibrator with the following command from the terminal on Ubuntu (command may vary for other Linux distributions):

$ sudo apt-get install xinput-calibrator

If the user is not in the sudoers, then root login (su) will be required, in which case the command would simply be:

# apt-get install xinput-calibrator

The rest of this guide will assume that we are logged in as root (su), as indicated by the prepended hash “#”. You do not need to type the # as part of the command.

Make sure the touchfoil controller board is plugged into the computer via the USB cable. If the computer is a laptop with an existing touchscreen, or if there are potentially other touchscreens connected to the computer, it may be wise to run the following command to list the touchscreen devices that are “calibratable”:

# xinput_calibrator --list

This should produce a list that will contain the touchscreen that we want to calibrate:

Device “USBest Technology SiS HID Touch Controller” id=8

In this case, there is only one device. Multiple touchfoils will show up with the same name but different id numbers.

To run the calibration screen, execute the following command:

# xinput_calibrator --device 8

Where “8” was the device id from the list command. If you only have one device in the list, you can simply run:

# xinput_calibrator

The calibration screen will show, and you will need to touch each target in turn (i.e. top left, top right, bottom left, bottom right).
Targets will appear in red and turn white when the click has been recognised.

If you get a message on the screen saying “Mis-click detected, restarting” then it is likely that you have either mis-clicked, or the touch controller is producing false touches (perhaps due to environmental noise), or the touchfoil is mounted incorrectly on the display: the xinput_calibrator calibration cannot compensate for a touchfoil which is rotated relative to the display.

When the four targets have been clicked, the calibration screen will close and the terminal will show you the output. At this point, the calibration data has been saved into XInput for the session, but not saved into a config file for permanent use (i.e after logout or shutdown/restart). The output in the terminal window will look like this:

Calibrating EVDEV driver for “USBest Technology SiS HID Touch Controller” id=8
Current calibration values (from XInput): min_x=4002, max_x=-4 and min_y=75, max_y=3986
Doing dynamic recalibration:
Setting calibration data: 3998, 9, 121, 4102
--> making the calibration permanent <--
Copy the snippet below into ‘/etc/X11/xorg.conf.d/99-calibration.conf’ (/usr/share/X11/xorg.conf.d/ in some distro’s)
Section “InputClass”
     Identifier  “calibration”
     MatchProduct      “USBest Technology SiS HID Touch Controller”
     Option            “Calibration”     “3998 9 121 4102”

In our experience, for Ubuntu the best place to write this snippet is /usr/share/X11/xorg.conf.d/99-calibration.conf, which may (or may not) exist.
If not, tt can be added to the end of the following file, where there is other input configuration /usr/share/X11/xorg.conf.d/10-evdev.conf

A note about swapped axes:

If the touchscreen axis (X, Y) are swapped, a touch movement from left-to-right (X) will appear as a cursor movement top-to-bottom (Y), and a touch movement from top-to-bottom (Y) will appear as a cursor movement from left-to-right (X).

The xinput calibrator program will function correctly; however, it does not produce the correct calibration values and after the calibration, the cursor may only appear in the top corner. If this is the case, it is best to configure the controller board firmware so that the axes are correct. Alternatively, you can correct the axes in the same 99-calibration.conf file (or 10-evdev.conf). You should write to this file before attempting the calibration, the file will look like this example:

Section “InputClass”
     Identifier  “calibration”
     MatchProduct      “USBest Technology SiS HID Touch Controller”
     Option            “SwapAxes”  “1”

Once you save this file and logout-login again you will see that the touch axes have been swapped. You can now calibrate correctly using xinput_calibrator. If either of your axes is inverted (touching left produces cursor movement right, or touching top produces cursor movement bottom), then the xinput_calibrator will correct the calibration for you once you touch the four targets. Alternatively, you can also write this into the file 99-calibration.conf (or 10-evdev.conf). For example:

Section “InputClass”
     Identifier  “calibration”
     MatchProduct      “USBest Technology SiS HID Touch Controller”
     Option            “SwapAxes”  “1”
     Option            “InvertX”   “1”
     Option            “InvertY”   “1”

Note you may not need to invert both axes – you should determine which axis needs to be inverted. You should then have the cursor movement roughly ok. If the touchfoil dimensions match the display dimensions, then no calibration will be needed, however, it may be wise to run xinput_calibrator to get the geometry calibration perfect.

The resulting output can be copied back into the 99-calibration.conf file (or 10-evdev.conf):

Option            “Calibration”     “3998 9 121 4102”

(you can add it anywhere between the Section “InputClass” – EndSection block).

A note about misclicks:

If the xinput_calibrator is complaining about misclicks and you have a “noisy” touch cursor, it may be possible to change the misclick settings so that you can calibrate successfully. Our recommendation, however, would be to fix the cursor stability by identifying the source of the problem and fixing this. By default, the misclick threshold is 25 pixels. You can increase this by using the misclick flag when running xinput_calibrator:

# xinput_calibrator --misclick 99

This will increase the misclick threshold to 99 pixels. You can also turn off the misclick detection completely by setting it to 0.

A note about touchscreen rotation:

Since the xinput_calibrator program uses a simple four-point calibration, it cannot correct for rotation. If you disable the misclick detection by setting it to 0, you will be able to calibrate a rotated touchscreen, however, the resulting calibration values will be incorrect and the cursor position will be incorrect.

A note about display orientation:

Unfortunately, if the display orientation is changed, the touchscreen calibration will no longer be correct. This means that using this xinput_calibrator method will not work with devices where the display orientation can change dynamically (e.g. as part of your software application, or by an accelerometer [e.g. tablet device]). Once the display orientation has changed, it is possible to run xinput_calibrator again and calibrate the touchscreen to the new display orientation.


Third-Party Software Disclaimer