Hampshire TSHARC Linux Driver Installation

Revision: 3.0.4b

Date: June 21, 2007

**********************************************************************************
This document is divided into the following sections:
I.	Features
II.	Known Issues
III.	How to Install
IV.	Configure daemon to automatically start
V.	Using the control panel
		- General procedure for setting up controllers on a system
		- Command-line parameters
VI.  	How to Uninstall
VII.	Troubleshooting
**********************************************************************************

I.  Features


Changes from 3.0.4:
Added Inset support
Increased maximum supported controllers to 6

New Features from version 2.07:

TinyX / Kdrive support
5pt, 9pt, 25pt, 28pt calibration support
X11R7 (Xorg 7.x) support
User-mode calibration support
No reboot required after installation
Text-mode control panel that works with or without X-windows running
Setup has menu interface for installing driver components
Automatic detection and configuration of TSHARC PS/2 components
Little to no configuration required after installation
Automatic detection of USB controllers upon daemon start
Uninstall script provided
Reduced library dependencies
EEPROM Reading and Writing of calibration
Full capacitive controller support

Features retained from version 2.07:

4pt calibration support
GUI calibration support.
Right click emulation.
Touch Modes (Normal, Pendown, Penup)
Configurable Primary and Alternate buttons
Configurable configuration file path
Multi-display support
Multi-screen support
Serial, USB and PS/2 support
X11R6 Support
Xinerama support

Features NOT retained from previous release:

X11 module support

**********************************************************************************

II.  Known Issues:

Since there is a wide variance among Linux distribution, there may be issues with the daemon automatically starting after a reboot for some distributions.

**********************************************************************************

III.  How to install:

1.  Uncompress the file Tsharc304.tar.gz into any directory on the local system and run the command "sudo ./install.sh" at the console.  The command to uncompress the file into the current directory is "tar zxvf Tsharc303.tar.gz".  Next, enter the command "cd Tsharc303" at the console to change the current directory to the installation directory.

2.  Enter the command "sudo ./install.sh" at the console.  A menu will appear with a series of components that can be toggled on and off.  Select up to three controller components to install.

3.  If a directory other than "/etc/tsharc" is needed, this may be changed by choosing the option "Set configuration file directory" and changing the path to a different directory.

4.  Select the install menu choice.

All of the configured controllers should now be responding normally to touch.

**********************************************************************************

IV.		Configure daemon to automatically start

There are two daemon registration scripts included with the TSHARC linux daemon, "registerSysVexample.sh" and "registerX11example.sh".  Both of these scripts try to ensure that the command "xhost local:" (ensures we are allowed permission to move the Xservers mouse cursor) script command "boot.tsharc start" (starts the daemon) is executed during startup.

The "registerSysVexample.sh" scripts attempts to register the daemon with the target system that utilizes System V initialization.  There are two main types of initialization that are normally found on Linux distributions; System V initialization (an example would be Fedora) and BSD initialization (an example would be Slackware).  It is only necessary to use this script if the TSHARC control panel is to be run without X-windows running.  It is important to note that if the daemon is started at this stage, X-windows communications is disabled.  To enable X-windows communications, run the script command "boot.tsharc start" again after X-windows has started.  If X-windows is installed on the target system, then the "registerX11example.sh" script should be executed in addition to executing "registerSysVexample.sh" so that the X-windows communications is enabled when X-windows starts.

The "registerX11example.sh" script attempts to register the daemon with the X11 startup scripts on the target system. Since X11 is generally, the default environment for using a touch screen controller the "registerX11example.sh" is normally the only script that needs to be executed.

To register the daemon to start using System V initialization, run the command "sudo ./registerSysVexample.sh".

To register the daemon to start using X11 startup scripts, run the command "sudo ./registerX11example.sh".

For information on how to unregister the daemon, refer to section "VI. How to Uninstall".

Note: To manually start the daemon: Enter "boot.tsharc start" at the command prompt.  Also, the file "./registerSysVexample.sh" file will not be present in the installation directory until after running the script "./uninstall.sh".

The files and directories that are required to be present for proper operation of the TSHARC daemon:

- The files contained within the TSHARC configuration directory
- The "/usr/bin" directory and the files "tscal" and "hlincal"
- The "/var/log/tsharc" directory

**********************************************************************************

V.  Using the control panel

General procedure for setting up controllers on a system
--------------------------------------------------------

The general process for setting up controllers on the target system is as follows:

1>  Start the control panel
2>  Select a controller to configure
3>  Select a screen and/or display
4>  Calibrate the current controller
5>  Set Edge Acceleration (optional step)
6>  Set Click Settings (optional step)
7>  Set Touch Settings (optional step)
8>  Set Advanced Settings (necessary step for some system)
9>  Write Current Controller Data
10> Exit the control panel

Repeat above steps for every controller on system.

1>  Start the control panel
---------------------------

To run the control panel, run "hlincal" from the console (root-access currently not required for this).  After running this, a menu will appear in the current console window.  Note: The file "hlincal" can be run from any directory since it is located in "/usr/bin" which is usually located in the "$PATH" environmental variable.

After starting the control panel, the following menu will appear after running this command:

Main Menu

1. Controller Selection
2. Display / Screen Settings
3. Calibration
4. Edge Acceleration
5. Click Settings
6. Touch Settings
7. Advanced Settings
O. OK - Exit and Write Current Controller Data
C. Cancel - Exit and Read Current Controller Data
A. Apply - Write Current Controller Data


2>  Select a controller to configure
------------------------------------

At the top of the screen will be information on the version, the current controller and that controllers device path.  If there are multiple controllers setup on the system, the first thing that needs to be done is to select the appropriate controller to configure (refer to next section only if there are multiple controllers on the system).

First, select "1. Controller Selection" from the "Main Menu" and the following "Controller Selection Menu" will appear:

Controller Selection Menu

1. Select Current Controller by Entering ID
2. Select Current Controller by Touching Screen
P. Return to Previous Menu

Enter selection:

There are two methods of selecting a controller:

1> "Select Current Controller by Entering ID"
After selecting this option, a list of controllers identified by the driver will be displayed.  Selected the ID of the controller that is to be configured.  After selecting the new controller, the new current controller at the top of the screen will change to reflect the new choice.

2> "Select Current Controller by Touching Screen"
After selecting this option, there will be a prompt to touch the screen associated with the controller to configure.  Simply touch the screen of the controller to configure followed by pressing the enter key and the new current controller at the top of the screen will change to reflect the new choice.

To discover the current display and screen for the target system, enter the command "xdpyinfo | head".  The first line of the output of these command will provide a text string in the format ":<display>.<screen>".

3>  Select a screen and/or display
----------------------------------

If there are multiple displays and/or screens setup on the target system, select "2. Display / Screen Settings" from the "Main Menu" and the following menu will appear:

Display / Screen Settings Menu

1. Select Display ID (Current: 0)
2. Select Screen ID (Current: 1)
P. Return to Previous Menu

1> "Select Display ID"
This sets the display id of the current controller.  Changes to these values are applied immediately.  It is important that a valid display id is chosen.  If the mouse cursor is already on the correct display after touching the current controllers touch screen, then this does not need to be changed.  This should only need to be changed on systems with multiple monitors setup.  Specifying a remote display is not currently supported.

2> "Select Screen ID"
This sets the screen id of the current controller.  Changes of these values are applied immediately.  It is important that a valid display id is chosen.  If the mouse cursor is already on the correct display after touching the current controllers touch screen, then this does not need to be changed.  This should only need  to be changed on systems with multiple monitors setup.

4>  Calibrate the current controller
------------------------------------

To calibrate a controller select "3. Calibration" from the "Main Menu" and the following menu will appear:

Calibration Menu

1. 4 Point Calibration (Current)
2. 5 Point Calibration
3. 9 Point Calibration
4. 25 Point Calibration
5. 28 Point Calibration
6. Begin GUI Calibration
7. Begin Text Calibration
P. Return to Previous Menu

To select the number of calibration points, select one of the first five menu choices.  After the calibration choice has been made, select "6. Begin GUI Calibration" for a GUI calibration and "7. Begin Text Calibration" for a text calibration.  Generally, the only reason to select a text calibration is if the X-windows environment is not available or for troubleshooting purposes.

The calibration information is automatically saved when the calibration is accepted.

5>  Set Edge Acceleration (optional step)
-----------------------------------------

Edge acceleration is used in situations where the bezel of the display monitor covers part of the touch screen such that the calibration points cannot be touched during calibration.  Because of this, there may be a situation where the mouse cursor cannot go to the outer edges of the screen when the edges of the touch screen are touch.  The edge acceleration feature corrects for this by "accelerating" touches near the edge of the touch screen such that mouse cursor goes to the very outer edges of the display.

To set edge acceleration, select "6. Edge Acceleration" from the "Main Menu" and the following menu will appear:

Edge Acceleration Menu

1. Set acceleration for left edge of screen (Current: 0)
2. Set acceleration for top edge of screen (Current: 0)
3. Set acceleration for right edge of screen (Current: 0)
4. Set acceleration for bottom edge of screen (Current: 0)
P. Return to Previous Menu

Select the edge of the screen that is to be changed and enter a value between 0 and 255.  Values in-between 0 and 255 indicate a relative range between 0 and 25 percent from the edge of the screen.

6>  Set Click Settings (optional step)
--------------------------------------

To change click settings, select "5. Click Settings" from the "Main Menu" and the following menu will appear:

Click Settings Menu

1. Set right click delay in milliseconds (Current: 0)
2. Set right click area (Current: 100)
3. Set button used for left clicks (Current: 1)
4. Set button used for right clicks (Current: 3)
P. Return to Previous Menu

Select "1. Set right click delay in milliseconds" to change the right-click delay in milliseconds for the current controller.  After the screen is touched and held in an area for this specified amount of time, a right-click will occur.  Enter zero for this option to disable right-click emulation.

Select "2. Set right click area" to change the right-click area. The right click area is the area from the initial touch point to a point at which right-clicks will no longer occurs.  As long as the touch remains within the right-click area of the initial touch, a right-click may occur.  To determine the correct value, the following formula may be used:

Right_click_area = 4096 * (desired_event_area_width / width_of_touchscreen)

Select "3. Set button used for left clicks" to change the button used for left click when the screen is touch.  Generally this is left at 1.

Select "4. Set button used for right clicks" to change the button used for emulating a right click when the screen is touched for a period of time specified by right click delay and held in an area specified by right click area.  Generally this can be left at 3, but occasionally this needs to be changed to 2 depending on the target systems configuration.

7>  Set Touch Settings (optional step)
--------------------------------------

To change the touch settings, select "6. Touch Settings" from the "Main Menu" and the following menu will appear:

Touch Settings Menu

1. Select Normal Mode (Current)
2. Select Touch Down Mode
3. Select Touch Up Mode
P. Return to Previous Menu

Select "1. Select Normal Mode" to select normal mode.  This mode behaves the same as a normal mouse on a system.

Select "2. Select Touch Down Mode" to select touch down mode.  This mode will send a mouse click at the location of the initial touch.

Select "3. Select Touch Up Mode" to select touch up mode.  The mode send a mouse click at the location of a touch release.

8>  Set Advanced Settings (necessary step for some system)
----------------------------------------------------------

To change advanced settings, select "7. Advanced Settings" from the "Main Menu" and the following menu will appear:

Advanced Settings Menu

1. Enable EEPROM Reading and Writing (Current: 0)
Note: X offset and Y offset is normally only need in Xinerama
environments with multiple controllers and displays
2. Set X Offset in Pixels (Current: 0)
3. Set Y Offset in Pixels (Current: 0)
Note: A value of zero for width or height will cause driver to use
current screen size
4. Set Custom Width in Pixels (Current: 0)
5. Set Custom Height in Pixels (Current: 0)
P. Return to Previous Menu

Most of Hampshires newer controllers support EEPROM reading and writing.  When enabled, this feature reads the calibration and edge acceleration values from the EEPROM of the controller when the daemon is initially started.  Also, after the calibration and edge acceleration values are set and accepted, this values are written to the controllers EEPROM.  One of the advantages to using this feature is that a calibrated controller that supports this feature may be moved a different machine with a similar hardware configuration and still retain the calibration without a new calibration needing to be done.

To enable EEPROM reading and writing, select "1. Enable EEPROM Reading and Writing" and enter a value of 1.  To disable EEPROM reading and writing, enter a value of 0.

If the target system is setup with multiple displays and Xinerama setup for the Xserver, both the X and Y offset and a custom width and height will need to be set for every controller setup on this type of system.  The X and Y offset specifies the minimum starting point from the upper left of the first screen on the Xinerama system.  For example, if a touch screen second screen on an Xinerama setup is to the right of a screen with width of 1024 pixels, then a 1024 value would go into the X offset and the touch screen on the first screen would be left at 0 for the X offset.

Select "2. Set X Offset in Pixels" to specify the start of a range in the X direction for a mouse cursor to stay in as a result of a touch.

Select "3. Set Y Offset in Pixels" to specify the start of a range in the Y direction for a mouse cursor to stay in as a result of a touch.

Select "4. Set Custom Width in Pixels" to specify the end of range from the X offset value in the X direction for a mouse cursor to stay in as a result of a touch.

Select "5. Set Custom Height in Pixels" to specify the end of range from the Y offset value in the Y direction for a mouse cursor to stay in as a result of a touch.

9>  Write Current Controller Data
---------------------------------

To save settings for the current controller so that the next time the TSHARC daemon is started, the current settings are used, select "A. Apply - Write Current Controller Data" from the "Main Menu".

10> Exit the control panel
--------------------------

To exit and revert settings for the current controller to the state it was at since the last save, select "C. Cancel - Exit and Read Current Controller Data" from the "Main Menu".

To exit and save settings for the current controller so that the next time the TSHARC daemon is started, the current settings are used, select "O. OK - Exit and Write Current Controller Data" from the "Main Menu".

Command-line parameters (command format: hlincal <parameter(s)>)
-----------------------

-h, --help
								Display help text

-q, --quick=numPoints
								Specify number of calibration points for quick calibration

-d, --display=displayNum
								Specify display to use (use with -q option)

-s, --screen=screenNum
								Specify screen to use (use with -q option)

-c, --controller=controllerNum
								Specify controller id to use

**********************************************************************************

VI.  How to Uninstall

To uninstall TSHARC daemon, please follow these steps:

1> Get to a command prompt.
2> Run the commmand "sudo uninstall.sh" and select 'y' to uninstall.

If the scripts "registerSysVexample.sh" and/or "registerX11example.sh" were executed during installation, the corresponding scripts should be run to unregister the daemon with the target system.

If the "registerSysVexample.sh" was executed during installation, run the command "sudo ./unregisterSysV.sh".

If the "registerX11example.sh" was executed during installation, run the command "sudo ./un6X11.sh".

**********************************************************************************

VII.  Troubleshooting:

If for some reason, the controller that was installed does not respond there are additional steps can can be made.

1>  Enter "xhost local:" at the command prompt using the same username as from the initial X-windows login.  On some distributions (such as Suse) this command is needed for the daemon to acquire permissions to communicate with the X-server.

2>  As part of the daemon installation files, there is an executable "tsharc_state".  This utility is used to ensure that basic communication can be made with the controller.

- Run the command "boot.tsharc stop" to ensure the daemon is not running during this communication test. 

- At the command prompt, change the current directory to the directory the installation files are located and run the command "./tsharc_state <device path>" where <device path> is the path the device.  

For example, if a serial controller is believed to be on "/dev/ttyS1", then enter "./tsharc_state /dev/ttyS1".   

For a PS/2 controller on "/dev/tsharcps2", enter "./tsharc_state /dev/tsharcps2". 

For a USB controller, enter "./tsharc_state tsharcusb".  This will cause this utility to communicate with the first TSHARC USB controller that is found

 After this command is run,  touch the screen and the coordinates should be displayed within the console window.  If coordinates are not shown, then additional paths may be tested until the correct one is found.

After communication has been confirmed, reinstall the TSHARC using the appropriate settings.

3>  If all else fails, change the current directory to the directory the installation files are located and run "./sysinfo.sh".  This will generate a "sysinfo.tar.gz" file in the "/tmp" directory which can be sent to Hampshire company for examination and troubleshooting purposes.



