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