.\" Copyright (c) 2017, Martin Kepplinger <martink@posteo.de>
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.
.\" %%%LICENSE_END
.\"
.TH "TS.CONF" "5" "" "" "tslib"
.SH "NAME"
ts.conf \- Configuration file for tslib, controlling touch screens for embedded devices\&.
.SH "DESCRIPTION"
.PP
The idea of tslib is to have a core library that provides standard services, and a set of plugins to manage the conversion and filtering as needed\&.
.PP
The plugins for a particular touchscreen are loaded automatically by the library under the control of a static configuration file,
/etc/ts\&.conf\&.
/etc/ts\&.conf
gives the library basic configuration information\&. Each line specifies one module, and the parameters for that module\&. The modules are loaded in order, with the first one processing the touchscreen data first\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
  module_raw input
  module variance delta=30
  module dejitter delta=100
  module linear
   
.fi
.if n \{\
.RE
.\}
.SH "ENVIRONMENT VARIABLES"
.PP
Latest versions of the Xorg tslib input driver use
\fBhal\fR
to configure the touchscreen within Xorg\&. Environment variables are only needed for the tslib commands\&.
.PP
\fBTSLIB_TSDEVICE\fR
.RS 4
If the default touchscreen device cannot be found, set the
\fBTSLIB_TSDEVICE\fR
environment variable to the touchscreen device to use\&.
.sp
Default when using ts_setup():
We try to open /dev/input/ts, /dev/input/touchscreen and /dev/touchscreen/ucb1x00 and on Linux, we then scan /dev/input/event* for the first device with property INPUT_PROP_DIRECT.
.RE
.PP
\fBTSLIB_CONSOLEDEVICE\fR
.RS 4
Tslib default console device\&.
.sp
Default:
/dev/tty
.RE
.PP
\fBTSLIB_CALIBFILE \fR
.RS 4
Stores calibration data obtained using
ts_calibrate\&.
.sp
Default:
/etc/pointercal
.RE
.PP
\fBTSLIB_CONFFILE\fR
.RS 4
Set a different location for the
ts\&.conf
configuration file itself\&.
.sp
Default;
/etc/ts\&.conf\&.
.RE
.PP
\fBTSLIB_FBDEVICE\fR
.RS 4
Framebuffer device to use for the touchscreen support\&.
.sp
Default:
/dev/fb0\&.
.RE
.PP
\fBTSLIB_PLUGINDIR\fR
.RS 4
Plugin directory for tslib\&.
.sp
Default:
/usr/lib/$triplet/ts0/
where triplet is the MultiArch path, e\&.g\&. arm\-linux\-gnueabi\&.
.RE
.SH "MODULE PARAMETERS"
.PP
\fBdejitter\fR
.RS 4
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\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdelta\fR
.sp
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\&.
.RE
.RE
.PP
\fBlinear\fR
.RS 4
Linear scaling module, primarily used for conversion of touch screen co\-ordinates to screen co\-ordinates\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBrot\fR
.sp
Rotation of touch coordinates. 0=no, 1=CW, 2=UD, 3=CCW. Default: the screen-rotation that was used with ts_calibrate (-r option).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBxyswap\fR
.sp
Interchange the X and Y co\-ordinates \-\- no longer used or needed if the new linear calibration utility ts_calibrate is used.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpressure_offset\fR
.sp
Offset applied to the pressure value. Default: 0.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpressure_mul\fR
.sp
Factor to multiply the pressure value with. Default: 1.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpressure_div\fR
.sp
Value to divide the pressure value by. Default: 1.

.RE
.RE
.PP
\fBiir\fR
.RS 4
Infinite impulse response filter. Similar to dejitter, 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).
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBN\fR
.sp
numerator of the smoothing fraction. Default: 0.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBD\fR
.sp
denominator of the smoothing fraction. Default: 1.

.RE
.RE
.PP
\fBpthres\fR
.RS 4
Pressure threshold filter. Given a release is always pressure 0 and a press is always >= 1, this discards samples below / above the specified pressure threshold.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpmin\fR
.sp
Minimum pressure value for a sample to be valid. Default: 1.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBpmax\fR
.sp
Maximum pressure value for a sample to be valid. Default: INT_MAX.

.RE
.RE
.PP
\fBcrop\fR
.RS 4
Ignore touch points outside of the framebuffer.
.sp
.RS 4

.RE
.RE
.PP
\fBdebounce\fR
.RS 4
Simple debounce mechanism that drops input events for the specified time after a touch gesture stopped.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdrop_threshold\fR
.sp
drop events up to this number of milliseconds after the last release event. Default: 0.

.RE
.RE
.PP
\fBskip\fR
.RS 4
Skip nhead samples after press and ntail samples before release. This should help if for the device the first or last samples are unreliable.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBnhead\fR
.sp
Number of events to drop after pressure. Default: 1.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBntail\fR
.sp
Number of events to drop before release. Default: 1.

.RE
.RE
.PP
\fBmedian\fR
.RS 4
Similar to what the variance filter does, the median filter suppresses spikes in the gesture.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdepth\fR
.sp
Number of samples to apply the median filter to. Default: 3.

.RE
.RE
.PP
\fBinvert\fR
.RS 4
Invert values in X and/or Y direction around a given value.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBx0\fR
.sp
X-axis (horizontal) value around which to invert. Default: 0.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBy0\fR
.sp
Y-axis (horizontal) value around which to invert. Default: 0.

.RE
.RE
.PP
\fBlowpass\fR
.RS 4
simple exponential averaging lowpass filter
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBfactor\fR
.sp
floating point values betwenn 0 and 1. Default: 0.4.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBthreshold\fR
.sp
x or y minimum distance between two samples to start applying the filter. Default: 2.

.RE
.RE
.PP
\fBevthres\fR
.RS 4
Number of samples needed from the device after considered a valid touch. This
filter will drop a tapping when too little samples are between "down" and "up".
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBN\fR
.sp
Minimum number of events needed between "down" and "up". Default: 5.

.RE
.RE
.PP
\fBvariance\fR
.RS 4
Tries to do it's best in order to filter out random noise coming from touchscreen ADCs. This is achieved by limiting the sample movement speed to some value (e\&.g\&. the pen is not supposed to move quicker than some threshold)\&.
.sp
This is a greedy filter, e\&.g\&. it gives less samples on output than receives on input\&. There is \fBno multitouch\fR support for this filter.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdelta\fR
.sp
Set the squared distance in touchscreen units between previous and current pen position (e\&.g\&. (X2\-X1)^2 + (Y2\-Y1)^2)\&. This defines the criteria for determining whenever two samples are near or far to each other\&.
.sp
If the distance between previous and current sample is far, the sample is marked as potential noise\&. This doesn't mean yet that it will be discarded; if the next reading will be close to it, this will be considered just a regular quick motion event, and it will sneak to the next layer\&. Also, if the sample after the potential noise is far from both previously discussed samples, this is also considered a quick motion event and the sample sneaks into the output stream\&.
.RE
.RE
.PP
.BR hardware
.BR support
.sp
.RE
On Linux, use the
\fBmodule_raw input\fR
if you can. The other raw access modules are device specific userspace drivers. If you need one of those, enable it explicitly when building tslib. The list of modules enabled by default might shrink in the future.
\fBmodule_raw input\fR
supports multitouch (MT) too.

.TS
allbox;
lb lb lb lb lb lb
l l l l l l.
module_raw	supported devices	interface	platforms	MT	how to enable
T{
.BR input
T}	all with Linux evdev drivers	any (driver) /dev/input/	Linux, FreeBSD	yes	enabled by default
T{
.BR arctic2
T}	IBM Arctic II	.	Linux, BSD, Hurd, Haiku	no	--enable-arctic2
T{
.BR collie
T}	Sharp Zaurus SL-5000d/SL-5500	.	Linux, BSD, Hurd, Haiku	no	--enable-collie
T{
.BR corgi
T}	Sharp Zaurus SL-C700	.	Linux, BSD, Hurd, Haiku	no	--enable-corgi
T{
.BR dmc_dus3000
T}	DMC DUS Series (DUS3000, ...)	UART	Linux	no	--enable-dmc_dus3000
T{
.BR dmc
T}	DMC (others)	.	Linux, BSD, Hurd, Haiku	no	--enable-dmc
T{
.BR galax
T}	eGalax 100, 112, 210	any (driver)	Linux, BSD	no	--enable-galax
T{
.BR h3600
T}	Compaq IPAQ	.	Linux, BSD, Hurd, Haiku	no	--enable-h3600
T{
.BR mk712
T}	Hitachi Webpad	.	Linux, BSD, Hurd, Haiku	no	--enable-mk712
T{
.BR tatung
T}	Tatung Webpad	.	Linux, BSD, Hurd, Haiku	no	--enable-tatung
T{
.BR touchkit
T}	Touchkit SAT4000UR	RS232	Linux, BSD, Hurd	no	enabled by default
T{
.BR ucb1x00
T}	UCB1x00 Touchscreens	.	Linux, BSD, Hurd, Haiku	no	--enable-ucb1x00
T{
.BR waveshare
T}	Waveshare Touchscreens	/dev/hidrawX	Linux	no	enabled by default
T{
.BR cy8mrln_palmpre
T}	in Palm Pre/Pre Plus/Pre 2	.	Linux	no	--enable-cy8mrln-palmpre
T{
.BR one_wire_ts_input
T}	FriendlyARM one-wire touch screen	.	Linux	no	--enable-one-wire-ts-input
T{
.BR input_evdev
T}	Linux evdev drivers (libevdev)	.	Linux	yes	--enable-input-evdev
.TE
.SH "SEE ALSO"
.BR ts_calibrate (1),
.BR ts_test (1),
.BR ts_test_mt (1)