This is the documentation for Guts-1.0              .  Copyright (C)
2001,2003,2004 Alessandro Rubini <rubini@linux.it>
   
This file documents the Guts package, an X11 driver for ATouch touchscreen devices. I plan to add support for other protocols
 as 
I find time.

 

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

   The package supports serial and USB touch panels manufactured by ATouch, 
under GNU/Linux and XFree86.  The latest version of this driver can be downloaded from:

`ftp://ftp.gnudd.com/pub/guts'

, `http://www.gnudd.com/software/#guts'


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 `guts'. As an alternative, you can use 
view cvs at `http://cvs.gnudd.com'.  The latest CVS snapshot can also be 
downloaded from
`ftp://ftp.gnudd.com/pub/guts' or the mirror site
`ftp://ftp.linux.it/pub/People/rubini/guts'. 

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
"guts_drv" module, part of this distribution.

 The compiled module (`guts_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> guts_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 guts 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  Guts 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 "guts"
 
Option "Device"                    "/dev/ttyS0"
  
Option "BaudRate"               "9600"
     
#Option "Protocol"                "a-touch"
     
#Option "CalibrationFile"     "/etc/guts.calib"
     
Option "Smoothness"           "0"
     
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 "guts"'
     
The name of the driver is mandatory. It is used to load the
 associated module. In this case the file `guts_drv.o'.

`Option "Device" "/dev/ttyS0"'
     
The device name is mandatory. It states where input data is
 collected from. For USB, it will be `/dev/ttyUSB0' or similar.

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

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

`Option "Smoothness"       "0"'
 The smoothness of the pointer. 
The default value is 0. The greater
 the value the smoother the motion. While I found it useful when
 testing the hardware without a real screen underneath, 
I now
 default to no smoothness as it's the correct setting when you
 click buttons directly on the screen.

`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
     xf86Guts.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 `guts_calib' script, under X.

 The program needs to find `guts_control' and `guts_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 guts_control::). The conversion 
tool is used so that the calibrator can read ASCII data instead of 

binary data (*note guts_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 "`guts_control on'" 
or
"`guts_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
guts_control::.

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

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

guts_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.


guts_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.

guts_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...
