path: root/README

Compaq TC1000 tablet driver for X11
-----------------------------------

The driver was developed to work with X.Org Xserver v1.4.0
and X.Org X11 ABI XInput driver v2.0.

Will Rose tested it with X.Org Xserver v1.3.0 and XInput
ABI v0.7 and made a patch that was later incorporated
to the source code (as of v0.1.0) to provide backward
compatibility.

RandR extension is required (for providing screen rotation
modes compatibility).

fpi2002 (kernel module or better device config. script)
is required to supply the device serial port.

The driver is developed under terms of GNU GPL which means
you may use it legaly for free.

If you find any bug or you have a problem to discuss
or a reasonable suggestion for an improvement, feel
free to contact the author (see below).



INSTALLATION:
-------------

$ ./configure --prefix=<X11_install_prefix>

$ make

# make install

should work (X11 install prefix should be /usr)



CALIBRATION:
------------

There is a simple command-line calibration tool available
in perl subdirectory.

It requires Perl and the following Perl modules to work:
Getopt::Std, Device::SerialPort, Time::HiRes.

Getopt::Std and Time::HiRes are normally distributed
with Perl itself; Device::SerialPort is not, though.

Download the module(s) from http://cpan.org/
and install them unless you have them already
(see perlmodinstall man page for more info).
Or you may conveniently use perl -MCPAN -e shell
to ease installation of bundled packages form CPAN
archive. 


Note that you shouldn't run the utility while in X
with the driver loaded (the tool reads the serial device
and if run while the driver is loaded, it will compete
with the driver over the device, which will compromise
its functionality or even cause more serious problems).

Run the tool from terminal and follow the hints to explore
your border and side-buttons HW coordinates needed to
calibrate the X driver.



OPTIONS:
--------

The driver accepts the following options.  Default values
are shown.

1/ Device configuration:

Option "Device"			"/dev/ttyS0"
Option "BaudRate"		"19200"


2/ Buttons configuration:

Option "ButtonMap"		"1 2 3 4 5 6 7 8 9 10 11 12"

	This is the default button map.
	The numbers represent final button codes of button
	events sent by Xserver (i.e. as xev reports them).
	Pen tip is mapped to the 1st position in the list
	(mouse 1 by default).
	Pen button is mapped to the 3rd position in the list
	(mouse 3 by default).
	In 3-buttons emulation mode (see below), the emulated
	button is mapped to 2nd position in the list
	(mouse 2 by default).
	Side button 1 (the [e]) activated is mapped
	to 4/5/6th pos. depending on activation by
	pen button 1/2/3, respectively.
	Analogically, the 2nd (the [=]) and 3rd (rotation)
	side buttons are mapped to 7/8/9th and 10/11/12th pos.
	Feel free to set the mapping as you wish.

Option "ButtonModes"		"2EMU 3EMUtap"

	These are the default pen button event resolvers.
	xf86-input-tc1kpen can handle pen buttons in
	various modes (see documentation for modes
	descriptions). Using this option, one may
	configure one or more modes to be used.
	On run-time, switching-around the modes
	specified is done by invoking a pen button
	(see below for the default).

Option "ButtonModeSwitch"	"12"

	Defines button that will switch the buttons resolver.
	The number denotes position of the button (not the
	button code defined in the mapping), i.e. 12 is
	the rotation side-button invoked by pen button
	no matter how the mapping is set.
	Note that setting this WON'T disable the button
	for Xserver.
	Setting it to 0 effectively disables switching,
	so it's recommended (yet not necessary) if you
	only use one button mode.

Option "Btn3EmuTimeout"		"200"

	Sets timeout (in milliseconds) for 3-buttons modes.
	See documentation for how the timeout is treated.


3/ Pointer on-screen coordinates area:

Option "CoordMinX"		"0"
Option "CoordMinY"		"0"
Option "CoordMaxX"		"8600"
Option "CoordMaxY"		"6500"

	These options set on-screen coordinates
	transformation (in tablet HW resolution).
	You need to set those correctly in order
	to calibarte your tablet.
	Note that [0,0] tablet point is in the
	lower left corner (unlike when in X Windows).
	The driver inverts Y axis on its own,
	but when you calibrate the tablet, you
	have to keep that on mind.


4/ Pointer side-buttons area:

Option "SideBtnsYOffset"	"9100"

	This sets side-buttons area Y threshold
	(in tablet HW resolution).
	If the driver encounters Y coordinate
	higher than this, it resolves side-button
	action instead of on-screen action.
	Note that for some reason, X and Y axes
	are swapped for the side buttons (so Y is
	vertical and X is horizontal).
	Set this to something a bit higher than your
	CoordMaxY. Try to change that if your pointer
	jumps on screen when trying to activate a side
	button.

Option "SideBtnsSize"		"200"

	This sets side button size (in tablet HW resolution).
	You should'n need to change that, but you may try.

Option "SideBtnsY"		"9650"

	This is vertical center of side-buttons area.
	In tablet HW resolution.

Option "SideBtn1X"		"1250"
Option "SideBtn2X"		"1770"
Option "SideBtn3X"		"2300"

	These are horizontal centers of side-buttons.
	All in tablet HW resolution.

# Transforms
Option "InvertX"		"no"
Option "InvertY"		"no"
Option "SwapXY"			"no"

	These are boolean options that transform coordinates.
	You only need to change these if you want some other
	than the normal landscape/potrtrait orientations.

Option "Rotate"			"no"

	This options can take the following values:
	"no" means no rotation, "CW" means clockwise rotation
	of 90 degrees, "CCW" means counter-clockwise rotation
	of 90 degrees.
	The rotation is realized by the 3 above transforms.
	Normaly, you don't need to set anything.


If you don't intend to do any special tricks, setting Device
option, on-screen coordinates area and side-buttons area
should be enough for you.



DEBUGGING:
----------

To compile-in debug messages, uncomment appropriate
lines in src/Makefile.am and run

$ automake

$ autoconf

and then proceed with the installation.  Debug messages
go to X server log file (/var/log/Xorg.0.log for XOrg
by default).

Note that you should use debug messages only if you
develop the driver; pen movement produces vast amount
of debug messages, thus highly degrades the driver
and X server performance and wastes disk space.
Debug messages are being logged depending on
log-level set.  Messages on lower or equal log-level
are logged.  The log-level is indicated in the message
as "DEBUG[<level>]" string, so one can easily grep e.g.
debug messages on level 3 only via grep 'DEBUG\[3\]'.



AUTHOR:
-------

Hope this will help. :-)

Regards,

vencik


Vaclav Krpec    <vencik@razdva.cz>



CONTRIBUTORS:
-------------

Many thanks to the following people for their help:

William Rose    <wrose@zip-it.org>