tslib

C library for filtering touchscreen events

tslib consists of the library libts and tools that help you calibrate and use it in your environment.

contact

If you have problems, questions, ideas, or suggestions, please contact us by writing an email to [email protected], which is our mailing list.

website

Visit the tslib website for an overview of the project.

table of contents

• setup and configure tslib
• filter modules
• the libts library
• building tslib
• hardware support
• contribute

setup and configure tslib

install tslib

tslib runs on various hardware architectures and operating systems, including GNU/Linux, FreeBSD, or Android/Linux. See building tslib for details. Apart from building the latest tarball release, running ./configure, make, and make install, tslib is available from distributors like Arch Linux / Arch Linux ARM, Buildroot, Debian / Ubuntu, Fedora, or OpenSUSE and their package management.

configure tslib

This is just an example /etc/ts.conf file. Touch samples flow from top to bottom. Each line specifies one module and its parameters. Modules are processed in order. Use one module_raw on top, that accesses your device, followed by any combination of filter modules.

module_raw input
module median depth=3
module dejitter delta=100
module linear

See the section below for available filters and their parameters. On Linux, your first commented-in line should always be module_raw input which offers one optional parameter: grab_events=1 if you want it to execute EVIOCGRAB on the device.

With this configuration file, we end up with the following data flow through the library:

driver --> raw read --> median  --> dejitter --> linear --> application (using `ts_read_mt()`)
           module       module      module       module

calibrate the touch screen

Calibration is applied by the linear plugin, which uses its own config file TSLIB_CALIBFILE. Don't edit this file manually. It is created by the ts_calibrate program:

# ts_calibrate

The calibration procedure simply requires you to touch a cross on the screen, where it appears, as accurately as possible.

test the filtered input behaviour

You may quickly test the touch behaviour that results from the configured filters, using ts_test_mt:

# ts_test_mt

On the bottom left of the screen, you will see the available concurrent touch contacts supported, and whether it's because the driver says so, or ts_test_mt was started with the -j commandline option to overwrite it.

environment variables (optional)

You may override the defaults. In most cases, though, you won't need to do so:

TSLIB_TSDEVICE          Touchscreen device file name.
                        Default:                automatic detection (on Linux)

TSLIB_CALIBFILE         Calibration file.
                        Default:                ${sysconfdir}/pointercal

TSLIB_CONFFILE          Config file.
                        Default:                ${sysconfdir}/ts.conf

TSLIB_PLUGINDIR         Plugin directory.
                        Default:                ${datadir}/plugins

TSLIB_CONSOLEDEVICE     Console device. (not needed when using --with-sdl2)
                        Default:                /dev/tty

TSLIB_FBDEVICE          Framebuffer device.
                        Default:                /dev/fb0

use the filtered result in your system (X.org method)

If you're using X.org graphical X server, things should be very easy. Install tslib and xf86-input-tslib, reboot, and you should instantly have your ts.conf filters running, without configuring anything else yourself.

use the filtered result in your system (ts_uinput method)

TL;DR: Run tools/ts_uinput_start.sh during startup and use /dev/input/ts_uinput as your evdev input device.

tslib tries to automatically find your touchscreen device in /dev/input/event* on Linux. Now make ts_uinput use it, instead of your graphical environment directly:

# ts_uinput -d -v

-d makes the program return and run as a daemon in the background. -v makes it print the new /dev/input/eventX device node before returning.

Now make your graphical environment use that new input device, using evdev drivers.

• For Qt5 for example you'd probably set something like this:

  QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS=/dev/input/eventX:rotate=0

• For X11 you'd probably edit your xorg.conf Section "InputDevice" for your touchscreen to have

  Option "Device" "/dev/input/eventX"

Please consult your input system's documentation on how to use a specific evdev input device.

Let's recap the data flow here:

driver --> raw read --> filter(s) ... --> ts_uinput --> libevdev read  --> GUI app/toolkit
           module       module(s) ...     daemon        e.g. in libinput

symlink /dev/input/ts_uinput to the new event file

/dev/input/event numbers are not persistent. In order to know in advance, what enumerated input device file is created by ts_uinput, you can use a symlink:

• use the included tools/ts_uinput_start.sh script that starts ts_uinput -d -v and creates the symlink called /dev/input/ts_uinput for you, or

• if you're using systemd, create the following udev rule, for example /etc/udev/rules.d/98-touchscreen.rules:

  复制

  SUBSYSTEM=="input", KERNEL=="event[0-9]*", ATTRS{name}=="NAME_OF_THE_TOUCH_CONTROLLER", SYMLINK+="input/ts", TAG+="systemd" ENV{SYSTEMD_WANTS}="ts_uinput.service"
  SUBSYSTEM=="input", KERNEL=="event[0-9]*", ATTRS{name}=="ts_uinput", SYMLINK+="input/ts_uinput"

where NAME_OF_THE_TOUCH_CONTROLLER the touchscreen found in your cat /proc/bus/input/devices | grep Name. The first rule is only needed, if tslib doesn't automatically choose the correct device for you.

running as systemd service (optional)

In case you have to use non-default paths, create a file containing the environment for tslib, like /etc/ts.env

  TSLIB_CALIBFILE=/etc/pointercal
  TSLIB_CONFFILE=/etc/ts.conf
  TSLIB_PLUGINDIR=/usr/lib/ts

and create a systemd service file, such as /usr/lib/systemd/system/ts_uinput.service

  [Unit]
  Description=touchscreen input
  BindsTo=dev-input-ts.device
  After=dev-input-ts.device
  RequiresMountsFor=/etc/ts.env

  [Service]
  Type=forking
  EnvironmentFile=/etc/ts.env
  ExecStart=/usr/bin/ts_uinput -d

Adjust the paths. They could just as well be in /usr/local/, too.

other operating systems

There is no tool that we know of that reads tslib samples and uses the Windows touch injection API, for example (yet).

filter modules

module: linear

Linear scaling - calibration - module, primerily used for conversion of touch screen co-ordinates to screen co-ordinates. It applies the corrections as recorded and saved by the ts_calibrate tool.

Parameters (usually not needed):

• rot

  overwrite the rotation to apply. Clockwise: rot=1, upside down: rot=2, counter-clockwise: rot=3. Default: screen-rotation during ts_calibrate calibration.

• xyswap

  Interchange the X and Y co-ordinates -- no longer used or needed if the linear calibration utility ts_calibrate is used.

• pressure_offset

  Set the offset applied to the pressure value. Default: 0

• pressure_mul

  factor to multiply the pressure value by. Default: 1.

• pressure_div

  value to divide the pressure value by. Default: 1.

Example: module linear rot=0

module: invert

Invert values in the X and/or Y direction around the given value. There are no default values. If specified, a value has to be set. If one axis is not specified, it's simply untouched.

Parameters:

• x0

  X-axis (horizontal) value around which to invert.

• y0

  Y-axis (vertical) value around which to invert.

Example: module invert y0=640 (Y-axis inverted for 640 screen height, X-axis untouched)

module: median

The median filter reduces noise in the samples' coordinate values. It is able to filter undesired single large jumps in the signal. For some theory, see Wikipedia

Parameters:

• depth

  Number of samples to apply the median filter to. Default: 3.

Example: module median depth=5

module: pthres

Pressure threshold filter. Given that a release is always pressure 0 and a press is always >= 1, this discards samples below / above the specified pressure threshold.

Parameters:

• pmin

  Minimum pressure value for a sample to be valid. Default: 1.

• pmax

  Maximum pressure value for a sample to be valid. Default: (INT_MAX).

Example: module pthres pmin=10

module: iir

Infinite impulse response filter. This is a smoothing filter to remove low-level noise. There is a trade-off between noise removal (smoothing) and responsiveness. The parameters N and D specify the level of smoothing in the form of a fraction (N/D).

Wikipedia has some theory.

Parameters:

• N

  numerator of the smoothing fraction. Default: 0.

• D

  denominator of the smoothing fraction. Default: 1.

Example: module iir N=6 D=10

module: dejitter

Removes jitter on the X and Y co-ordinates. This is achieved by applying a weighted smoothing filter. The latest samples have most weight; earlier samples have less weight. This allows one to achieve 1:1 input->output rate. See Wikipedia for some theory.

Parameters:

• delta

  Squared distance between two samples ((X2-X1)^2 + (Y2-Y1)^2) that defines the 'quick motion' threshold. If the pen moves quick, it is not feasible to smooth pen motion, besides quick motion is not precise anyway; so if quick motion is detected the module just discards the backlog and simply copies input to output. Default: 100.

Example: module dejitter delta=100

module: debounce

Simple debounce mechanism that drops input events for the specified time after a touch gesture stopped. Wikipedia has more theory.

Parameters:

• drop_threshold

  drop events up to this number of milliseconds after the last release event. Default: 0.

Example: module debounce drop_threshold=40

module: skip

Skip nhead samples after press and ntail samples before release. This should help if the first or last samples are unreliable for the device.

Parameters:

• nhead

  Number of events to drop after pressure. Default: 1.

• ntail

  Number of events to drop before release. Default: 1.

Example: module skip nhead=2 ntail=1

module: lowpass

Simple lowpass exponential averaging filtering module.

Parameters:

• factor

  floating point value between 0 and 1; for example 0.2 for more smoothing or 0.8 for less. Default: 0.4.

• threshold

  x or y minimum distance between two samples to start applying the filter. Default: 2.