This file tells how to use gpm and X with a Gunze touchscreen.

It is pretty similar to README.microtouch, and I plan to unify them as
soon as I  port the two implementation to offer  a consistent look and
feel. Currently the Gunze  implementation is more configurable but has
a    worse    calibration     management    (it    must    write    to
/etc/gpm-calibration).

		DEVICE CONFIGURATION
		--------------------

The gpm decoder requires the Gunze  device to be in Gunze Mode (not in
Elo Emulation  Mode). The supported  serial speeds are 9600  and 19200
baud, the  latter being the default  speed (in other  words, to decode
data at 9600 you must use the  "-b 9600" option of gpm; no "-b" option
selects  19200 baud).  Currently,  the only  device  supported is  the
10-bit one.

		USER INTERFACE
		--------------

The  decoder currently  implemented in  gpm is  quite simple:  it only
supports mouse  motion and button-1  events. This will soon  change: I
plan to implement corner-taps for  button-2 and button-3, as well as a
different "mode" where motion is  not supported and any touch event is
converted to a button-1 click.

In the  default (and only) mode,  when a user touches  the screen, the
decoder generates mouse motion events. Tapping on the screen generates
button-press (as well as drag and release) events.

A "tap" is a finger-down (or pen-down) event generated quickly after a
finger-up. A touch event is considered  a "tap" if the lapse since the
last finger-up is less than or equal to the double-click interval (the
default  is 250ms,  and the  value is  chosen by  specifying  the "-i"
option of gpm). This means that you'll usually move the pointer to the
desired position and then tap on it.

Double-and triple clicks are easily generated by repeated tapping.

Since tapping is usually accompanied  by a small movement, the decoder
will use the coordinates of  the finger-up event for the button-press.
Further dragging will  be relative to the tapping  position (i.e., the
finger-up position).  Moreover, the  last coordinate pair  received on
finger-up is discarded, because it  usually is slightly offset (due to
the non-negligible area of the fingertip).

My own experience  with the Gunze device, revealed  that sometimes the
finger bounces, generating very fast finger-up/finger-down pairs.  The
gpm decoder, therefore, ignores  any quick succession of finger-up and
finger-down events. The default is to ignore any release-press pair if
the time lapse is less than 100ms (note, however, that this time lapse
is configurable).


		GPM OPERATION
		-------------

In  order to  run the  touchscreen with  gpm, you  need to  update the
/dev/mouse  symbolic link  to point  to  the right  serial port;  then
invoke gpm with a command line like

	gpm -t gunze

If /dev/mouse is not updated to point to the touchscreen serial port,
use
	gpm -t gunze -m /dev/ttyS0
or an equivalent command.

Unfortunately,  there is  currently no  way  to paste  text, but  I'll
implement corner-tapping to achieve that.


		Gunze-specific Configuration
		----------------------------

It is possible  to specify device-specific options to  gpm in order to
customize the behaviour  of the Gunze decoder. The  options are passed
as  argument  to the  "-o"  command  line  (reminiscent of  the  mount
command).

The following options are recognized:

    smooth=
	The  decoder smooths  mouse  movements, to  prevent the  jumpy
	behaviour  that  usually  results  from finger  movement.  The
	default  smoothin factor  is 9,  you can  specify  a different
	value if  you wish:  "gpm -t gunze  -o smooth=3"  gives faster
	(and  more jumpy) motion,  while "gpm  -t gunze  -o smooth=30"
	gives a very slow feeling.x

    debounce=
	The  option is  used to  specify  the minimum  time lapse,  in
	milliseconds between finger-up and finger-down events. Smaller
	time intervals are discarded  to achieve debouncing. Note that
	the  maximum  time lapse  is  the  one  used for  double-click
	detection, and is specified with the "-i" command-line option,
	common to every other mouse type.
		

Please note that more than one option can be specified, by using the
comma ``,'' as a separator. For example:

	gpm -t gunze -o smooth=5,debounce=150



		Calibration
		-----------

To calibrate  the touchscreen, use the program  "gunze-setup" found in
the source  tree of  gpm. The  gpm daemon must  already be  running in
order for  the program  to work flawlessly,  as the program  stops and
restarts gpm  internally (it  depends on gpm  for correct  serial port
initialization).

The calibration program uses either /dev/touchscreen (if available) or
/dev/mouse  (otherwise) as  the serial  port to  communicate  with the
touchscreen.  You'll need  therefore to  create a  symlink for  one of
those names before running "gunze-setup".

After calibration,  the calibration  values can be  found in  the file
/etc/gpm-calibration, but gpm must be restarted in order to be able to
read them.  This can be construed as  a bug, and avoiding  to stop the
program is in my TODO list.



		X OPERATION
		-----------

In  order to  use the  touchscreen in  X, you  should install  in your
system the "Summa"  module, as modified by Frank  Holtz (the driver is
available from http://www.hof-berlin.de/tablet/tablet.html, as well as
in the gpm CVS tree and from gpm-1.18.2 in the gpm release as well).

The compiled  module (xf86Summa.so) should go in  the module directory
of your  X server, usually  /usr/X11/lib/modules, when it sits  in the
right place, a proper XF86Config will arrange for its loading.

Gpm must run in repeater mode, with a command line like:
	gpm -t gunze -Rsumma
, which instructs gpm to repeat packets according to the Summa protocol.

Then, you need to add the following sections to your XF86config:

	Section "module"
	        Load "xf86Summa.so"
	EndSection
	
	Section "Xinput"
	    Subsection "SummaSketch"
	        Port "/dev/gpmdata"
	        DeviceName "touchscreen"
	        Mode Absolute
	        AlwaysCore
	    EndSubSection
	EndSection


Moreover, you should disable the "Pointer" section. I used a trick
like this one:

	Section "Pointer"
	    Protocol    "MouseSystems"
	    Device      "/dev/fifo"
	EndSection

Where /dev/fifo is just a plain unused fifo ("mknod /dev/fifo p")

If, when calling ``startx'', it won't work 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
    xf86Summa.so: Unknown error loading module

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


	Calibration
	-----------

To calibrate  the touchscreen, use the program  "gunze-setup" found in
the source tree of gpm (yes, it  is the same program used for the text
mode).   The gpm  daemon  must already  be  running in  order for  the
program  to work  flawlessly, as  the program  stops and  restarts gpm
internally (it depends on gpm for correct serial port initialization).

The calibration program uses either /dev/touchscreen (if available) or
/dev/mouse  (otherwise) as  the serial  port to  communicate  with the
touchscreen.  You'll need  therefore to  create a  symlink for  one of
those names before running "gunze-setup".