touchcal v0.1 (c) 1999 by Christoph Baumann <cgb@debian.org>


0. Disclaimer
-------------

As it is already stated in the copyright, there is NO WARRANTY for any damage
caused by a malfunction of this program. Users of MicroTouch touch screens
are informed that the program rewrites the ROM of the MicroTouch controller.
As this rewrite uses an undocumented command which may be changed in later
versions of the firmware it may cause irreparable damage to the controller.
The author also doesn't have any access to touch screen devices any more.
So please don't send me complaints except bug reports which also may not be
solved - Sorry.


1. Purpose
----------

touchcal is a tool to calibrate touch screens with serial controllers from the
manufacturers EloGraphics(R) (IntelliTouch E281-2310) and MicroTouch(R) (SMT3 
serial)  for use under XFree86.


2. Compiling
------------

The program uses the curses/ncurses library. It won't compile if this library
isn't installed on your system.
To compile just type "make". The gcc will then be called with the right 
parameters.


3. What the program does
------------------------

The program initializes the controller (only if used with a MicroTouch device).
Then it reads in 3 coordinates from the touch screen (see below) and
calculates the appropriate values for the entries in XF86Config. It prints
the result to STDOUT and also writes the file /tmp/cal.tmp which contains
the output in the XF86Config format. So some script could just insert
/tmp/cal.tmp into XF86Config at the appropriate section. 
Read XFree86-Touch-Screen-HOWTO for more details on the entries in XF86Config.


4. Invocation
-------------

touchcal needs to be run as root and with no Xserver running. As you can guess
by now, it needs to be run in console mode. To allow the use of the coordinates
obtained in console mode under X, the borders of the monitor display of these
two modes need to be exactly the same. This is rather easy with LCD displays.
With CRTs this is more or less hopeless :-(.
 
touchcal requires two parameters. First the device type:
'e' for EloGraphics, 'm' for MicroTouch. Then the serial port to which the 
device is connected: e.g. /dev/ttyS1 .
For example to calibrate a MicroTouch touch screen connected to serial port 2:
touchcal m /dev/ttyS1


5. Usage
--------

After invoking touchcal correctly 3 cross-hair-like markers are displayed, one
after another. Each marker must be touched from the position of normal use. 
Don't be hasty. The more exact you touch the markers the better the 
calibration. After the three markers are touched, touchcal writes the entries 
for XF86Config to STDOUT and into the file /tmp/cal.tmp . This output can then 
be inserted into XF86Config by a shell script. If you use a MicroTouch device 
there are additional information printed to STDOUT stating what cruelties the 
program does to the touch screen controller.


6. Limitations
--------------

* touchcal only works with the above stated models 
* the console - X discrepancy


7. Further information
----------------------

see:
* manpage for XF86Config
* XFree86-Touch-Screen-HOWTO
* the manuals and homepages of the manufacturers 
