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

• General Information:
• Bugs:
• Device Support:
• XFree Configuration:
• Usb Driver:

General Information

The package supports Gunze touch panels under Linux and XFree86. Supported panels are the serial, PS/2, and USB devices. The serial and PS/2 devices are supported by means of an X module, xf86Gunze. Support for USB comes as a kernel module that emulates the PS/2 protocol, so you still need the xf86Gunze module.

The latest version of this driver can be downloaded from:

• ftp://ar.linux.it/pub/gunzets
• http://ar.linux.it/pub/gunzets

The latest source tree can be accessed from my CVS server, instructions are available at http://ar.linux.it/software/#cvs . The package name to use is gunzets. The latest CVS snapshot can also be downloaded from ftp://ar.linux.it/pub/gunzets .

Bugs

The following bugs are currently known:

• Debouncing is only supported for XFree 4.0 (not 3.3.6).
• A bounce event breaks smoothing processing
• Support for multi-screen operation is not supported.

Device Support

To run the serial or PS/2 devices you only need the information in this section. To run the USB device you also need to load the kernel module, described under See Usb Driver, later in this file.

Support for all three device flavors is implemented by means of xf86Gunze.c, a module for XFree86.

The driver has been used under XFree86 version 3.3.6 and version 4.0.1.

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

The compiled module (xf86Gunze.so for XFree86 3.3 or gunze_drv.o for XFree86 4.0) should go in the module directory of your X server, usually /usr/X11R6/lib/modules for XFree86 3.3 or /usr/X11R6/lib/modules/input for XFree86 4.0. When the file is in place, a proper XF86Config will arrange for its loading.

In order to compile the module for different version of the XFree86 systems you need access the source tree and compile using there commands:

make XFREE33SOURCE=<location-of-source> xf86Gunze.so
make XFREE40SOURCE=<location-of-source> gunze_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.

Both XFREE33SOURCE and XFREE40SOURCE can be defined in your environment. Also, calling make without arguments will compile both modules.

To compile gunzets 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).

XFree Configuration

• XFree 3.3:
• XFree 4.0:
• Generic X Configuration:
• Text Console:
• Calibration:
• XFree Tools:

XFree 3.3

In order to use a Gunze device with XFree 3.3 you need to add the following two sections to your XF86Config (the example below shows all the options available for the module, but most of them are optional, see below for details):

Section "module"
Load "xf86Gunze.so"
EndSection

Section "Xinput"
Subsection "GunzeTS"
DeviceName "touchscreen"
Port            "/dev/ttyS0"
DeviceType      Serial
Speed           9600
CalibrationFile "/etc/gunzets.calib"
Smoothness      9
TappingDelay    0
DebugLevel      0
#Res12Bit
AlwaysCore
EndSubSection
EndSection

The meaning of the individual options is the following:

DeviceName "touchscreen"

The device name is an identifier string chosen by the user. It is mandatory.

Port "/dev/ttyS0"

The hardware channel used to read input data. The line is mandatory. It can be a serial port, a PS/2 port (/dev/psaux) or the USB entry point (/dev/gunzets).

DeviceType Serial

Optional specification of the device type. It is used to select the protocol used by the port. Possible values are (case-insensitive): "serial", "ps2" (or "ps/2") and "usb". If the information is not present in the configuration file, the file name is used to guess the device type. Such guess will work under Linux but may fail under other operating systems.

Speed 9600

Speed of the serial connection. Only used for serial devices, the value defaults to 9600. Only valid values are 9600 and 19200.

CalibrationFile "/etc/gunzets.calib"

Optional specification of the calibration file. The default is /etc/gunzets.calib as shown. The format of the calibration file is specified later in this documents.

Smoothness 9

The smoothness value is used to smooth out movements. It is only meaningful for motion and drag events. Allowed values are in the range 0 to 50. If you want to do handwriting, you'll need to disable smoothness processing (i.e., set it to 0).

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

DebugLevel 0

Any debug level greater than 0 tells the driver to spit informative messages. The greater the number, the higher the message rate. Messages go to the usual X error channel (stderr, normally connected to the text console used to fire X).

Res12Bit

The boolean option states whether your panel reports data with 12 bits of resolution (i.e., as numbers in the 0-4095 range). The default, when no option is specified, is 10 bits (0-1023). 12-bit support is implemented by discarding the lowest two bits, and has been contributed by Atsushi Nemoto.

AlwaysCore

The input device is a "core" input device (like the main pointer device - the mouse or equivalent). If the directive is not specified, the touch screen acts as an auxiliary input device, and applications may individually request to use it.

XFree 4.0

In order to use a Gunze device with XFree 4.0 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 "gunze"
Option "Device"            "/dev/ttyS0"
#Option "DeviceType"       "serial"
Option "BaudRate"          "9600"
#Option "CalibrationFile"  "/etc/gunzets.calib"
Option "Smoothness"        "9"
Option "TappingDelay"      "0"
Option "JitterDelay"       "50"
Option "DebugLevel"        "0"
Option "Res12Bit"          "False"
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 "gunze"

The name of the driver is mandatory. It is used to load the associated module. In this case the file gunze_drv.o.

Option "Device" "/dev/ttyS0"

The device name is mandatory. It states where input data is collected from. It can be a serial port, a ps2 port or the USB device created by the gunzets device driver.

Option "DeviceType" "serial"

The device type specification is not currently supported. If the option is present it is ignored. The actual device type is retrieved from the device name: any device name that includes the string "tty" is assumed to be a serial port, other devices are assumed to speak the PS/2 protocol.

Option "BaudRate" "9600"

The transmission rate for serial ports. It defaults to 9600 and is ignored for non-serial input devices.

Option "CalibrationFile" "/etc/gunzets.calib"

The option is not currently implemented.

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 "Res12Bit" "False"

The boolean option states whether your panel reports data with 12 bits of resolution (i.e., as numbers in the 0-4095 range). The default is 10 bits (0-1023). 12-bit support is implemented by discarding the lowest two bits, and has been contributed by Atsushi Nemoto.

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 both version 3.3 and 4.0 of XFree you can still use a normal mouse together with the touch panel. While XFree 4.0 can use the touch screen as its only pointer device, version 3.3 of the X server can't do that. If you have no other pointer and don't want X to choke on the configuration file, you can use 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 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
xf86Gunze.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).

Text Console

Use of the touch screen on the text console is not supported, and I don't think it ever will (although I made it work under gpm some time ago, I no longer maintain gpm).

Calibration

To calibrate the touch panel, run the gunzets_calib script, under X. It has been tested with both XFree86 version 3.3.6 and version 4.0. To calibrate pass the device name on the command line of the program:

gunzets_calib /dev/ttyS0	(serial device)
gunzets_calib /dev/psaux	(PS/2 device)
gunzets_calib /dev/gunzets	(USB device)

The program needs to find gunzets_control in the command search path (it uses the control program to turn off the touchscreen in X, so the calibrator can read input data).

In order to calibrate you'll need to move the mouse pointer first. You can do that with the warp command (see below) if no other pointer is available on the system. While I could use the touch panel to this aim, and delay turning it off, I didn't think of it and don't want to re-test it all. The next release will be better in this respect (too).

XFree Tools

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

gunzets_control

The program accepts on, off or info as argument. It turns the touchscreen off, turns it on, or reports information about active input devices. The program needs to connect to an X server.

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.

Usb Driver

This driver has been developed and tested with Linux-2.4.0 and works with Linux-2.2.18 as well.

Input data is made available through an entry point in /dev (using devfs if available) (FIXME: devfs support is not yet implemented) or through the input engine (the input.o module) (FIXME: input support is not yet implemented). By default it uses its own /dev entry point, dynamically allocated from the misc device driver.

• Quick Start:
• Compiling and loading:
• Unloading:
• Installing:
• Accessing data:
• Usb Calibration:

Quick Start

If all of your modules are in place, you can just invoke

make
./gunzets_load

and read the section about X support, above.

If you want to use the input mechanism (currently unimplemented), add use_input=1 to the gunzets_load command line.

Compiling and loading

In order to successfully load the module you need to have the following facilities compiled in your kernel or loaded as modules:

• usb generic support (usbcore.o)
• a usb host controller driver (usb-ohci.o o usb-uhci.o)
• support for misc devices like the ps2 mouse (misc.o)
• the input mechanism (input.o)

To compile the driver just make. If your 2.4 or 2.2 kernel headers are not available from /usr/src/linux/include then specify KERNELDIR to point to your kernel source directory, either on the make command line or in the environment. For example:

make KERNELDIR=/usr/src/linux-2.4

To load the driver, use insmod:

insmod ./gunzets.o

To use the input mechanism, specify it on the command line:

insmod ./gunzets.o use_input=1

To automatically create the entry point in /dev (needed if you are not using the input mechanism) run the gunzets_load script instead:

./gunzets_load

Unloading

You can unload the module only after disconnecting the touch panel, otherwise the rmmod program will return "Device Busy" even if no application is using the pane, because the USB mechanism is using it.

Installing

To install the module to the proper places you can run make install. You may also wish to copy gunzets_load from /usr/local/bin to /etc/rc.d/init.d or /etc/init.d and create a proper symbolic link for automatic load at boot.

Accessing data

Data read from the touch screen is available as raw data returned in PS/2 format in the file /dev/gunzets. You can use the same XFree driver described above for serial and PS/2 devices with this driver.

Usb Calibration

To calibrate the touch panel, run the "gunzets_calib" script, under X. See Calibration.

Table of Contents

• General Information
• Bugs
• Device Support
• XFree Configuration
  • XFree 3.3
  • XFree 4.0
  • Generic X Configuration
  • Text Console
  • Calibration
  • XFree Tools
• Usb Driver
  • Quick Start
  • Compiling and loading
  • Unloading
  • Installing
  • Accessing data
  • Usb Calibration