3M Touch Systems, Inc.
TouchWare for Linux

Version 5.62 SR1, April 2004
Copyright 2001-2004 3M 
All rights reserved.

---------------------------------
PRODUCT SUMMARY
---------------------------------
TouchWare for Linux is the software for your 3M Touch Systems touch screen.
It allows you to select, launch, and drag objects using the touch screen.

TouchWare provides full touch screen functionality for all applications
running under Linux Kernel 2.4 kernels running XFree86 4.

---------------------------------
FEATURES AND ENHANCEMENTS
---------------------------------
* Added support for SuSE 9.0.
* Increased the timeout of the calibration tool from 6 to 20 seconds.
* Corrected the X input module to default to no cursor offset.
* Corrected the driver to no longer use RTS/CTS handshaking for serial
  controllers. This prevented some controllers from being recognized.
* Corrected a timing problem in the driver that caused serial controllers
  not to be recognized. This happened only on some machines.
* Added a driver parameter that specifies the first serial port to
  search.

---------------------------------
RETRIEVING THE FILES
---------------------------------
* TouchWare for Linux arrives as a tar.gz file. If you are using KDE or
  Gnome as your user interface, use a file browser to locate the file.
  Right-click on the file and select "Archiver". Use the archiver to
  extract the contents to some directory. If you are using the command line
  interface, use gunzip and tar to extract the files.

---------------------------------
DRIVER SELECTION
---------------------------------
* The distribution has pre-built drivers. If your kernel distribution and
  configuration matches one of the pre-built drivers, you may be able these.
  If not or if the pre-built driver does not work with your system, please
  visit our web page at www.3MTouch.com and contact technical support.

* Locate the directory where you expanded the tar.gz file.

* There are a series of subdirectories reflecting the distribution and
  configuration. At the top of these subdirectories is the kernel
  distributor, either "RedHat" or "SuSE". Within these subdirectories are
  distribution versions, such "9.0". The bottom of the directory tree is
  the kernel configuration, such as "i686.config". For Red Hat, most
  installations will use the "i686.config" subdirectory and for SuSE, most
  installations will use the "defconfig" subdirectory. Choose the
  subdirectory that match your system.

* In the chosen subdirectory, there are two files, "TWDrv.o" and
  "TWDrv_nousb.o". If your system has USB support, copy "TWDrv.o" to the
  parent directory. If you do not have USB support on your system, copy
  "TWDrv_nousb.o" to the parent directory and rename the file to "TWDrv.o".
  Both drivers support serial touch controllers. Proceed to the "Driver
  Installation" instructions below.

---------------------------------
DRIVER INSTALLATION
---------------------------------
* In the parent directory, there is a file "install". Issue the command
  "./install" to install the driver.

* Though there are no ill effects, the part of the install script that
  issues the mknod and "chmod" commands need to be run only once. It is
  possible to just issue "insmod" commands after the install script has
  been run once.

* To install the driver at system startup, insert into your system startup
  script a command to issue the install command or copy the contents of
  "install" into your installation script. You may move the file TWDrv.o if
  you wish. Again, only the insmod command and commands to support it are
  necessary.

* The insmod command has optional parameters. Read the "DRIVER PARAMETERS"
  section below. If desired, set these parameters in the install script.

* When the insmod command runs, there may be a message stating that the
  driver's kernel version does not match your kernel version. As long as
  the kernel version of your machine starts with the same kernel version of
  the driver, such as 2.4.18 versus 2.4.18custom, then the driver should
  operate properly.

* When the insmod command runs, there may also be a message stating that
  your kernel was built using the gcc version 3 compiler and that the
  driver was built using the version 2 compiler. It also states that this
  is known to cause problems. We have yet to see any problems. The driver
  and your kernel should operate properly.

---------------------------------
DRIVER PARAMETERS
---------------------------------
These parameters may be specified in the insmod command line or in the
install script file.

* The parameter TWDrv_pszSerialPath is the name of the serial device to
  which the touch controllers are attached. The default is /dev/ttyS.

* The parameter TWDrv_nMaxSerial is the number of the serial devices that
  the driver searches for controllers. The default is 4. Hence, the
  driver searches for controllers, by default, on devices /dev/ttyS0
  through /dev/ttyS3. If you are using a USB touch screen controller, set
  TWDrv_nMaxSerial to 0.

* The parameter TWDrv_nMinSerial is the number of the first serial device
  that the driver searches for controllers. The default is 0.

---------------------------------
X INPUT MODULE INSTALLATION
---------------------------------
* There are two subdirectories called Xfree4.0.3 and Xfree4.1.0. In each
  there is a file called TWXinput_drv.o. Depending on the version of
  XFree86 you are using, copy that file into your XFree86 input module
  directory. Usually, this is /usr/X11R6/lib/modules/input. If you are
  using a version of XFree86 later than 4.1.0, use the 4.1.0 input module.

* Edit your XFree86 configuration file. This file usually resides in
  /etc/X11 and has a name similar to XF86Config-4 or XF86Config. If both
  are present, use XF86Config-4.

* Add the following section to configuration file:

  Section "InputDevice"
     Identifier "TouchScreen"
     Driver     "TWXinput"
     Option     "Device" "/dev/twscreen0"
  EndSection

* Locate a section called "ServerLayout". Add the following line to this
  section:

     InputDevice "TouchScreen" "SendCoreEvents"

* If your system will not have a mouse, then use "CorePointer" instead of
  "SendCoreEvents" in the "ServerLayout" section.

* Save the file and restart X. Usually you need to log out and the option
  to restart X is on the login dialog.

* If X does not restart, there are normally two problems. First, the kernel
  touch driver is not installed. Run the install script or issue the insmod
  command and try again. Second, there may be a problem in the XF86Config
  file. In either case, the X log file, usually found in
  /var/log/XFree86.0.log, can be helpful in determining the error.

---------------------------------
RUNNING THE CALIBRATION UTILITY
---------------------------------
* The calibration utility is in the TWCalib subdirectory under the
  directory where the distribution tar.gz was expanded. In this directory
  is a program called TWCalib. This program may be moved to any location
  for your convenience.

* Run this program with the command "./TWCalib" to calibrate your touch
  screen. Note that this is an X Windows program and must be run while the
  X Server is running.

* TWCalib presents two targets for you to touch. These touches are all that
  are required to calibration the touch screen controller.

* There is one command line argument for TWCalib. This specifies the device
  to which the touch screen controller is attached. The default is
  /dev/twscreen1, which is the first touch screen controller supported by
  the driver. You may specify other devices as appropriate, such as
  /dev/ttyS0.

---------------------------------
AUTOMATIC DRIVER INSTALLATION
---------------------------------
* After testing the system, you may want to automatically install the driver
  during the booting of the system. Since the driver is used only during X
  Windows operations, it is best to install the driver only when X Windows
  is launched, which occurs when the "init 5" command is issued. The
  directory containing X Windows startup scripts is /etc/rc.d/rc5.d. Then
  copy the "install" script into this directory and rename it to "S99TWDrv".
  The next time you boot your system, the driver will be automatically
  installed.

---------------------------------
KNOWN ANOMALIES
---------------------------------
* At this time, only the Linux kernel distributions Red Hat 8.0,
  Red Hat 9.0, SuSE 8.2, and SuSE 9.0 are supported. The driver may work
  on other kernel versions, but this is not covered by any warranties.

* At this time, only XFree86 versions 4.0.3 and 4.1.0 are supported. The X
  Input module may work with other versions of XFree86, but this is not
  covered by any warranties.

* The calibration utility uses the library libglut.so.3. You need to
  download and install a package, such as Mesa, that supplies this library
  if it is not already on your system.

___________________________________________________________________________

MicroTouch, the MicroTouch logo, and TouchWare are either registered
trademarks or trademarks of 3M in the United States and/or other countries.
___________________________________________________________________________
