www.nico.schottelius.org/software/gpm/browse_source/gpm-1.99.4/doc/README.gunze
Nico Schottelius 95a46c5577 import gpm from unix.schottelius.org
Signed-off-by: Nico Schottelius <nico@ikn.schottelius.org>
2009-10-08 22:52:35 +02:00

196 lines
7.2 KiB
Text

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