Hampshire TSHARC Linux Driver Installation

Revision: 2.06

Date: July 5, 2005

**********************************************************************************
This document is divided into the following sections:
I.     System Requirements
II.    Some useful Linux commands
III.   Installing TSHARC controller
IV. 	 Calibration

**********************************************************************************
I.  System Requirements
	- XFree86 version 4.x or Xorg version 6.x
	- Kernel version 2.4.x or greater
	- Kernel support for USB if USB controllers is to be installed
	Note: If kernel does not include USB support, the kernel may be recompiled to support this.
	  Recompiling a kernel is beyond the scope of this document.
	- GCC version 3.3 or better

**********************************************************************************
II.  Some useful Linux commands:

Kernel and GCC Version
	"cat /proc/kernel"

Xfree86 / Xorg version
	"xdpyinfo"
		Approximately the fourth line will yield the version number. 
Note: this command must be launched from within the X environment in order to work.

**********************************************************************************
III. Installation of TSHARC controller

Note: If this is a PS/2 installation, please contact Hampshire Company for additional PS/2 files and information and follow the "ps2readme" document prior to reading this document.

1. Verify that your Xfree86 / Xorg X-Windows manager is operating correctly.
2. Become root by entering "su" at a command prompt and entering root password.
3. Copy and prepare driver files using the "install" script by entering the following:

"sh ./install"

The following are USB controller only steps.  For a RS-232 installation, please proceed to step 7

4. - Edit /etc/hotplug/usb.handmap

  a.  Add the following line to the end of the file:

	evdev                0x0003 0x07dd   0x0001    0x0000       0x0000       0x00         0x00            0x00            	0x00            0x00            0x00            0x00000000

This will ensure that the TSHARC USB controller gets handled by the evdev module when the controller is plugged in.

5. Reboot

6. Find out which Event Device the Touch Screen Controller is using:
(NOTE: root access required)

	a. enter "cat /dev/input/event0"

	b. if there is a blank line, touch the screen.  If gibberish shows up the
	touch screen controller is on /dev/input/event0.

	c. if no gibberish shows up, or "No Such Device", press control-c, then
	re-try for the next event (event1).

7. Edit the X Windows Configuration file:

Typically this file is found under "/etc/X11" and may be named as "XF86Config", "XF86Config-4" or "xorg.conf".

	a. Under Section "ServerLayout" add the following line:
		InputDevice "touchscreen0"

	b. Add the following before or after your existing "InputDevice" sections:

Section "InputDevice"
	Identifier 	"touchscreen0"
	Driver	"tsharc"
	Option	"Device"	"/dev/ttyS0"
	Option	"TSHARCBaud"	"9600"
	Option	"TSHARCType"	"12"

	# if all three of the following options are "0", RS232 is used
	# set this option to "1" if configuring PS/2 controller
	Option	"TSHARCPS2"		"0"
	# set this option to "1" if configuring USB controller
	Option	"TSHARCUSB"		"0"
	# set this option to "1" if configuring BUS controller
	Option 	"TSHARCBUS"		"0"

	Option	"ScreenNumber"	"0"
	Option	"ButtonNumber"	"1"
	Option	"AltButtonNumber"	"3"
	Option	"RightClickTimeout" "0"
	Option	"TMode"		"0"
	Option	"SendCoreEvents"
EndSection

Where:
	Device: 		- the port the TSHARC controller is connected to
                              
					USB / PS2
					"/dev/input/event<X>" - PS/2 or USB ID discovered from previous steps
					
					RS-232
					"/dev/ttyS0" - COM1
					"/dev/ttyS1" - COM2
					"/dev/ttyS2" - COM3
					etc.

	TSHARCBaud		- the TSHARC controller baudrate:
					2400
					4800
					9600
					19200
				Note TSHARC-8 uses only 2400.  The TSHARC-12
                                can use all 4 baud rates, but they are
                                jumper selectable.  All other controllers are
				set at 9600 baud.

	TSHARCType		- TSHARC controller type:
					8 - for TSHARC-8
					12 - for 12 and 10 bit TSHARC controllers

	TSHARCUSB		- Set to 0 or exclude this option if not USB, set to 1 if USB

	TSHARCPS2		- Set to 0 or exclude this option if not PS/2, set to 1 if PS/2

	TSHARCBUS		- Set to 0 or exclude this option if not BUS, set to 1 if BUS

	ButtonNumber		- Button that is sent a pen down when the screen is being touched.

	RightClickTimeout	- This is the time delay before an alternate click is sent - 0 disables the right click.

	AltButtonNumber		- Button that is sent a pen up after the RightClickTimeout time has expired.  
				This value MUST be specified in order for right click emulation to work properly.

	TMode			Touch Mode:
					0 - "Normal" mode
					2 - "Touch Down" mode	


	SendCoreEvents		- Use this option if you wish the touch
                                screen to Function when X starts.  This will also allow simultaneous use of the touch
                                screen and a mouse assuming a mouse is installed.

	Note: Currently, the TSHARC controller cannot be set as the CorePointer. 

4.  Save the modified X Windows Configuration file
5.  If within X-Windows environment, enter "startx", otherwise enter "reboot" at the command prompt.
6.   If SendCoreEvents is not defined you can enable the touch screen in an
Xterminal by typing "xsetpointer TSHARC".  You can revert back to the
normal pointer (disable touch screen) by typing in an Xterminal "xsetpointer pointer".
Or you can see what pointers are available by typing in an Xterminal
"xsetpointer -l".
7. The touch screen should now be functioning.
8. Proceed to the calibration section for details on how to calibrate the
touch screen to your display.

**********************************************************************************
4. Calibration

1. Once the driver is properly installed, reboot XWindows.

2. Run the "tscal" application to calibrate the Touch Screen.  No command line
options are needed for a 4 point calibration. To perform a 20 point calibration, enter ./tscal -c 20 at the command line.


Command Line Options:


Note: The calibration utility writes the calibration to a file:

	/usr/tsharc.cal

During calibration a secondary file is also used:

	/usr/tsharc.val

For non-root users to be able to calibrate the screen, both files need read/write
access for other user levels.  In order to allow read/write access, use the command:

chmod 666 /usr/tsharc.cal
chmod 666 /usr/tsharc.val

To change ownership of the file, use:

chown <username>:<group> /usr/tsharc.cal
chown <username>:<group> /usr/tsharc.val

NOTE: "tscal" requires libstdc++.so.6 in the /usr/lib/ directory.  This should be done automatically using the "install" script.  But if this needs to be done manually, copy libstdc++.so.6.0.3 to the "/usr/lib/" directory and set up a symbolic link to it
from libstdc++.so.6 by entering the following lines at the command prompt:

"cp libstdc++.so.6.0.3 /usr/lib/"
"cd /usr/lib/"
"ln -s lib libstdc++.so.6.0.3 libstdc++.so.6"

Troubleshooting:

Why is there no event device nodes under /dev/input?

The evdev module must be loaded.  To get a listing of the current modules, enter lsmod.  If evdev is not listed, then enter modprobe evdev.  Also, if this modules was missing, to ensure this module is loaded after every reboot, the line modprobe evdev needs to be added to the appropriate initialization file.  For example, in Fedora or Redhat, this file would be /etc/rc.d/rc.sysinit.

When I try to determine my USB or PS/2 device node, all of the device nodes under /dev/input return the message device not found. Why?

This is likely because the version of the kernel that is being used is too old.  Downloading a more recent distribution or recompiling the kernel should fix this issue.


