This is the documentation for Onetouch-1.2              .  Copyright
(C) 2001,2003 Alessandro Rubini <rubini@linux.it>



   This file documents Onetouch, support software for Onetouch touch
panels under Linux and XFree86.

General Information
*******************

   The package supports serial Onetouch touch panels under GNU/Linux and
XFree86.  The latest version of this driver can be downloaded from:

   * `ftp://ftp.gnudd.com/pub/onetouch'

   * `http://www.gnudd.com/software/#onetouch'

   The latest source tree can be accessed from my CVS server,
instructions are available at `http://www.gnudd.com/software/#cvs' .
The package name to use is `onetouch'. As an alternative, you can use
VIEWCVS at `http://cvs.gnudd.com'.  The latest CVS snapshot can also be
downloaded from `ftp://ftp.gnudd.com/pub/onetouch' or the mirror site
`ftp://ftp.linux.it/pub/People/rubini/onetouch' .

Device Support
**************

   The driver has been designed to run under XFree86 version 4.x. It
has been tested on 4.1 and 4.2.

   In order  to use  the touch screen  in X,  you should install  in
your system  the "onetouch_drv" module, part of this distribution.

   The compiled  module (`onetouch_drv.o') should  be copied in  the
module directory of  your  X server, usually or
`/usr/X11R6/lib/modules/input'.  When  the file is in place, a proper
`XF86Config' will arrange for its loading.

   In order to  recompile the module you need access to the complete X
source tree, and you can compiling issuing:

     make XFREE_SOURCE=<location-of-source> onetouch_drv.o

   The "location  of source" above  should be the  full path name  to
the directory called "xc" after you uncompress the source tar file.

   `XFREE_SOURCE' can be defined in your environment if you prefer.
Note that if the variable is defined, calling MAKE without arguments
will compile the module.

   To compile ONETOUCH you'll most likely need to compile X first (by
issuing `make World' and waiting a huge lot of time). A freshly
uncompressed source tree lacks the proper header files for compilation
to succeed; since one of the errors happens inside an X header, you can
only fix it by compiling X first - I can't fix things in my source.

XFree Configuration
*******************

XFree 4.x
=========

   In order  to use a  Onetouch device  with XFree 4,  you need to  add
an `InputDevice' section to your `XF86Config'. The following example
shows how it looks like. The options that are shown commented are not
implemented in this version of the module, and are ignored if specified.

     Section "InputDevice"
     Identifier "Touchscreen0"
     Driver "onetouch"
     Option "Device"            "/dev/ttyS0"
     Option "BaudRate"          "9600"
     #Option "CalibrationFile"  "/etc/onetouch.calib"
     Option "Smoothness"        "9"
     Option "TappingDelay"      "0"
     Option "JitterDelay"       "50"
     Option "DebugLevel"        "0"
     Option "SendCoreEvents"
     EndSection

Moreover, you need to add an `InputDevice' line in the `ServerLayout'
section. After the addition, the section will most likely look like
this:

     Section "ServerLayout"
     Identifier  "Simple Layout"
     Screen      "Screen 1"
     InputDevice "Mouse1" "CorePointer"
     InputDevice "Keyboard1" "CoreKeyboard"
     InputDevice "Touchscreen0"
     EndSection

Note that if your system has no mouse device, you can remove the
`InputDevice "Mouse1"' line and add `"CorePointer"' to the touch screen
line.

   The meaning of individual options is as follows:

`Identifier "Touchscreen0"'
     The identifier string is mandatory, and appears, literally, in the
     `InputDevice' directive within the `ServerLayout' section that is
     usually found at the end of the configuration file.

`Driver "onetouch"'
     The name of the driver is mandatory. It is used to load the
     associated module.  In this case the file `onetouch_drv.o'.

`Option "Device" "/dev/ttyS0"'
     The device name is mandatory. It states where input data is
     collected from.

`Option "BaudRate" "9600"'
     The transmission rate for serial ports. It defaults to 9600.

`Option "CalibrationFile" "/etc/onetouch.calib"'
     The option is not currently implemented, the calibration filename
     is hardwired

`Option "Smoothness"       "9"'
     The smoothness of the pointer. The default value is 9. The greater
     the value the smoother the motion. If you need to do handwriting
     or similar "fast" interaction, you should set the smoothness to 0.

`Option "TappingDelay"          "0"'
     Optional  selection of  tapping mode.  By  default (tapping delay
     set to 0), any  touch event is reported as a button press. In
     tapping mode the first touch event is used to  move the pointer,
     and button press is only reported when  the user taps on the
     device. If the delay, measured in milliseconds, between pen-up and
     pen-down is greater than the selected value, the pen-down even is
     considered motion.  I personally prefer tapping mode  when testing
     the device, as  it allows me to  use  the   common
     point-and-click  semantics  instead  of click-only; this is
     especially true if your touchscreen is not placed over the image
     but in side of it (as you guess, I do that).

`Option "JitterDelay"          "50"'
     The debouncing time lapse, measured in milliseconds.  If a
     pen-down event occurs immediately after pen-up (within this time
     lapse), then both events are discarded. Debouncing has been
     contributed by Chris Howe <chris@howeville.com>, and defaults to
     50ms.

`Option "DebugLevel" "0"'
     The level of messages spit out by the driver. The directive is
     optional and it defaults to 0.

`Option "SendCoreEvents"'
     The directive instructs X to use the touch screen as a core input
     device (like the main mouse). This module can currently only work
     as a core device.

Generic X Configuration
=======================

   Please note that with XFree you can still use a  normal mouse
together with  the touch panel. Also, can use the touch screen as its
only pointer device.

   If,  when calling  `startx', it  fails with  a message  of `Invalid
Subsection  Name', please  check the  previous error lines,  as they
explain what is wrong. They usually look like:

     (--) no ModulePath specified using default: /usr/X11R6/lib/modules
     xf86Onetouch.so: Unknown error loading module

   The messages are pretty clear, if your  are careful in reading them
(I am not that careful,  and lose half an hour in trying  to figure out
what was wrong).

Calibration
***********

   To calibrate the touch panel, run the `onetouch_calib' script, under
X.

   The program needs  to find `onetouch_control' and
`onetouch_to_ascii' in the  command search path or the current
directory. This usually means you can simply "`make install'" before
running the calibration, but you can also run the calibration program
from the source directory, provided "`.'" is in your `PATH'.

   The control program is used to turn off the touchscreen in X, so the
calibrator can read input data (*note onetouch_control::). The
conversion tool is used so that the calibrator can read ASCII data
instead of binary data (*note onetouch_to_ascii::).

   The new 5-point calibration, as of release 1.2 of the package, is a
full-screen application that takes complete control of your desktop.
Since it disables the touchscreen in X in order to directly read the
serial port, you'll need to invoke "`onetouch_control on'" or
"`onetouch_control raw'" if the program terminates unexpectedly.
Premature death of the application is not foreseeable, but you may want
to send a termination signal to the calibrator for whatever reason.
*Note onetouch_control::.

Support Tools
*************

   The package includes three tools that work by connecting with the X
server:

onetouch_control
================

   The program receives a single command-line argument and uses it as a
command to be performed by communicating with the X server.

   The following commands are supported:

`devinfo'
     Report device information to standard output. The information is
     about the input devices active in the current X server. In order
     for the other commands to succeed, the server must have exactly one
     touch panel configured. *Note XFree Configuration::.

`off'
     Deactivate the input device. The command makes the driver stop
     reading the serial port, so the calibration program (or otherwise)
     can read touchscreen data.

`on'
     Activate the input device. The command tells the driver to start
     reading the serial port again and activate the current calibration.
     If no calibration file is found the touchscreen will work in raw
     mode.

`raw'
     Activate the input device in raw mode. Even if a calibration file
     exists, it will not be used until the ON command is issued.  The
     command is meant to stop using wrong calibration information that
     sometimes may be generated by error.

`b1'
     Generate button-1 press and release events (the default).

`b2'
`b3'
     Generate button-2 (middle button) events from now on, likewise for
     button-3 (right button).

`b2once'
`b3once'
     Generate a button-2 event for the next press and release events,
     and then turn back to reporting button-1 events. The program won't
     terminate until the button-2 events have been reported.  Likewise
     for button-3.

`getleds'
     Return to standard output information about the current status of
     device leds. There are no physical leds on the touchscreen device,
     but the "led" abstraction is what has been used to send commands
     to the driver. This command is useful to me but very unlikely to
     be useful to anyone else.

onetouch_panel
==============

   The program is a simple graphical application to control generation
of button-2 and button-3 mouse events. Running the application is
optional, and you won't need to run it if your setup only uses button-1
events.

   The program window is made up of two buttons, labelled "2" and "3".
They are inactive by default.

   After clicking on one of the buttons, it becomes yellow and the touch
screen will report a button-2 or button-3 event once. After the event is
reported the button turns back gray and the touchscreen will go back to
report button-1 events.

   After clicking twice on one of the buttons, the button becomes red
and button-2 or button-3 events will be generated from now on. To go
back to button-1 events just click on the button again to inactivate it.

onetouch_to_ascii
=================

   The program reads from the serial port specified on the command-line
and converts binary packet to ascii information. Besides being used by
the calibration program, the program can be used for basic diagnosis of
hardware problems.

warp
====

   The program moves  the mouse pointer.  It can  be used to move the
mouse when  there is no active mouse.  It accepts a series of  letters
on the  command line:  each uppercase  N, S,  W, E moves the  pointer
by  100 pixels to  the north,  south, west, east.  Each lowercase  n,
s, w,  e  moves the  pointer by  10 pixels.


...Table of Contents...
