Zytouch Driver
--------------

This is a Linux user space "driver" for the Zytronic projected capacitive
technology (PCT) touch screens. The Zytronic home page is here:

    http://www.zytronic.co.uk/

Currently, the only screens that are supported are the ones with USB
Vendor:Product identifiers of 14c8:0002 and 14c8:0003.



Authorship and Licensing
------------------------
This driver was written by Erik de Castro Lopo <erikd@mega-nerd.com> while
working as a full time employee of bCODE Pty Ltd (www.bcode.com). Since
bCODE's core business is not touchscreens or touchscreen drivers, bCODE
decided to release the code under the terms of the GNU GPLv3.

I, Erik de Castro Lopo am still a full time employee of bCODE and will be
maintaining the public version of this driver in parallel to the version that
bCODE uses in its products.



How it Works
------------

The touchscreen is a simple USB connected device. The driver uses libusb to
find the device on the USB bus and then read data from it. The read data is
then transformed into X/Y coordinates which is injected directly into the X11
server using X11's XTest interfaces:

    http://www.linuxcertif.com/man/3/XTestQueryExtension/

Obviously, this is a bit of a hack, but bCODE Pty Ltd has been using this in
mission critical applications for over two years. Longer term it would probably
be desirable to re-write this as an X11 input driver.

The main problem with the current driver is that it must be run as the same 
user id as the person currently logged in. Unfortunately (but for all sorts of
very good reasons), the X11 XTest interfaces only accept input events from
process running as the same user id as the user that is currently logged in.



Compiling the Driver
--------------------

Compiling the driver itself on Linux should require little more than a full
development environment (Make, GCC etc) as well as the libusb for communicating 
with the USB connected touchscreen and the XTest header files.

On Debian and Ubuntu systems (where this driver was developed), the build tools
can be installed using the command:

    sudo aptitude install build-essential libusb-dev libxtst-dev

Included in the tarball there is also a calibration program which was written
in the Ocaml programming language. To install the tools and libraries required
to build the calibration utility run the command:

    sudo aptitude install ocaml-native-compilers ocaml-nox libextlib-ocaml-dev \
		libcairo-ocaml-dev liblablgtk2-ocaml-dev

With the above tools, libraries and header files installed, compiling and installing
the driver and calibration utility should require nothing more than running:

	make && sudo make install

This install command will install the following files:

    /usr/bin/zytouch-daemon
    /usr/bin/zytouch-calibrate
	/etc/zytouchd.conf
	/etc/zytouchd_v3.conf

The last two files are the configuration files for version 2 (ie USB id
14c8:0002) and version 3 (USB id 14c8:0003) of the touchscreen.



Using the Driver
----------------

As mentioned earlier, the driver must be run as the same user is as the
currently logged in user. First make sure the zytouch screen is connected by
doing :


    lsbusb | grep 14c8

which should result in either:

    Bus XXX Device YYY: ID 14c8:0002

for the version 2 of the screen or:

    Bus XXX Device YYY: ID 14c8:0003

for version 3. If you do not see anything then check that the screen is plugged
in and try again. If you see some number other than 0002 and 0003 then the 
screen you have is not yet supported.

If have one of the supported devices and it is visible on the USB bus the
daemon can be run in a terminal using:

    zytouch-daemon

If all goes well, the process will disconnect from the session and run in the
background sending events to the X11 server.

If this fails, it can be run in debug mode using:

    zytouch-daemon -d

With a bit of luck this will provide enough information to debug the problem.



Using the Calibration Utility
-----------------------------

The calibration utility does not work for version 2 of the driver (USB id of
14c8:0002). For version 2 of the touchscreen the config file /etc/zytouchd.conf
should be edited by hand. If anyone *really* needs a calibration utility for
a version 2 touchscreen they should contact the maintainer and offer to pay
for modifying the zytouch-calibrate utility to allow calibration for both
versions of the touchscreen.

For a version 3 touchscreen the zytouch-daemon should be started first and then
the calibration utility can be run using:

    sudo zytouch-calibrate

This needs to be run as root so that it can modify the configuration file
/etc/zytouchd_v3.conf.

Once the calibration utility is run, the user should be presented with a black
screen with some text in the center and a white cross in one of the corners.
The user should touch the screen where the cross is and repeat this for each
subsequent while cross shown on the screen.

At the end of the calibration process, the black screen will disappear and the
user will be returned to the normal desktop. The touchscreen should now be
calibrated.



TODO List
---------

- Modify calibration utility to read/modify/update the version 3 config file.
- Modify the calibration utility to allow it to detect swapped X and Y axes.
