3M Touch Systems, Inc.
MT 7 Software for Linux

Version 7.14.4, December 11, 2014
Copyright 1991-2014 3M.
All rights reserved.

---------------------------------
PRODUCT SUMMARY
---------------------------------
MT 7 Software, a member of the MicroTouch(tm) Software Suite, provides
unified driver support for MicroTouch touch technologies over a wide
range of operating systems. This version, 7.14 for Linux, provides
support for the Linux operating system for kernels 2.4, 2.6, and 3. This
product includes a user-space touch screen driver and a calibration tool.

---------------------------------
FEATURES AND ENHANCEMENTS
---------------------------------
* The new README and CHANGELOG files replace the old ReadMe.txt. The new
  LICENSE file replaces the old License.txt file.
* The software now correctly computes the desktop size if XRandR is
  installed but disabled.
* The 64-bit software no longer depends some later glibc libraries that
  are not on some early distributions.
* The Install script now supports /etc/X11/xinit.d as an X11
  initialization script directory.
* The MT7.14.4.bin and MT7.14.4.bin64 programs no longer directly link
  against libncurses and is now compatible with various versions of that
  library.
  
See the file CHANGELOG for a complete revision history.

---------------------------------
SYSTEM REQUIREMENTS
---------------------------------
Hardware Prerequisites

* The MT 7 for Linux software runs on most computers that run the Linux
  kernel 2.4, 2.6, and 3 operating systems. The computer's processor
  must be compatible with the Intel x86 and x86_64 series of processors.
* One or more of the following MicroTouch touch screen controllers:
  - MicroTouch EX serial or USB controllers
  - MicroTouch RX serial or USB controllers
  - MicroTouch DX serial or USB controllers
  - MicroTouch PX serial or USB controllers (single touch only)
  - MicroTouch SX serial controllers
* Depending on the touch screen, either a serial port or a USB port is
  required.

Software Prerequisites

* The MT 7 for Linux software requires 32-bit or 64-bit version of the
  Linux operating system of kernels 2.4, 2.6, or 3.
* If using USB controllers, the Linux operating system kernel 2.6 or
  better is required.
* Shared memory support is required. This is absent in some early kernel
  2.4 systems and some embedded Linux distributions.
* The calibration tool requires an X11-compliant X Windows server.

---------------------------------
INSTALLATION INSTRUCTIONS
---------------------------------
* License
  The MT 7 for Linux software is proprietary and not open source. The
  distribution is an executable program. Run this program from a command
  line. It presents a license agreement and asks you to either accept or
  decline the agreement. If you accept the agreement, the program
  produces a 'tar.gz' file. Follow the rest of these instructions to
  complete the installation process. For your convenience, the 'tar.gz'
  file contains a copy of the license in the file 'LICENSE'.

* Preparation
  You must log in the Linux operating system as the root user or use the
  'su' or 'sudo' command to get super user access. On some systems, you
  may need to run in single user mode (run level 1 on some systems).

  The installation process requires write access to various system
  directories. By default, the directories are:
  - /etc/udev or /etc/hotplug
  - /usr/lib or /usr/lib64
  - /etc/init.d or /etc/rc.d
  - /etc/X11/xinit/xinitrc.d, /etc/X11/xsessions.d, and /etc/X11/xinit.d

  After installation completes, the MT 7 for Linux software no longer
  needs write access to these directories.

* General Instructions
  The MT 7 for Linux package, if you accept the license agreement,
  produces a tar.gz file. The expanded package resides in the
  subdirectory 'twscreen'. A script named 'Install' installs the
  package. Installation includes creating the necessary init script,
  creating symbolic links in /usr/lib, enabling USB hotplug for
  MicroTouch devices, and creating a Remove script.

  Before installing the package, read below to see if any of these
  special situations apply to you. If they do, you may need to edit the
  Install script.

  If you run the Install script and then discover errors, always run
  the Remove script to undo the installation. This removes possibly
  erroneous links into your system. Then edit the Install script, make
  the necessary changes, and install again.

* Normal Installation
  Copy the tar.gz file into the directory where you want the package to
  reside, such as /etc. Issue the command 'tar xzf
  twscreen.<version>.tar.gz' where <version> is a version number string
  of the tar.gz file. This creates the directory 'twscreen' in the
  current directory.

  From there, go into the twscreen directory and issue the command
  './Install'. This script installs links in the Linux and X Windows
  system for your touch screen to work with your system.

* Installing on Write-Protected Systems
  The MT 7 for Linux software requires access to a writable directory
  for runtime and configuration data. By default, it uses a 'data'
  directory in the twscreen directory.

  If you need to have the package in a read-only directory, then decide
  on a writable directory for the package to use. Edit the Install
  script and search for the line 'DataDir=""'. Change the definition of
  DataDir to the writable directory. Save the changes and run the
  script. This creates the data directory where desired and creates a
  link in the package directory to the data directory.

* Other Options
  The MT 7 for Linux software should install without other changes on
  most Linux systems. However, if you have a customized directory
  structure or the installation script fails, you may need to edit the
  Install script and change one or more of the following script
  variables.

  - HalDir
    The MT 7 for Linux software now expects the X server automatically
    to load input devices. Some systems use a program called 'HAL' to
    do this. The Install script attempts to detect HAL and install a
    HAL policy file into /usr/share/hal/fdi/policy,
    /etc/hal/fdi/policy, or a subdirectory of these. If your system
    uses HAL and stores its policy files somewhere else, set HalDir to
    the appropriate path.

  - HotplugDir
    See the symbol 'UdevDir' for details.

  - InitDir
    The MT 7 for Linux software uses an init script, TWDrvStartup, to
    start and stop the touch screen driver. Normally, this runs at run
    level 5. If your init scripts are located in a directory other than
    /etc/init.d or /etc/rc.d, then set InitDir to the appropriate path.

  - JavaBinDir
    Set this symbol to the path of the Java runtime environment (JRE).

  - LibDir
    The MT 7 for Linux software uses several shared objects. The Install
    script links these into /usr/lib. If your system's libraries are
    elsewhere, change this variable to point to the correct path. This
    directory is mandatory and the software cannot run without its
    libraries in a common library directory.

  - LSBDir
    An init script must adhere to a variety of conventions. Some
    conventions use files, such as 'function', in the script directory.
    The variable 'InitDir' handles these cases.

    Some LSB-compliant systems require access to a file 'init-functions'
    normally found in /lib/lsb. If you have an LSB system and the
    init-functions file is not in /lib/lsb, you need to change the value
    of LSBDir.

  - SEDir1 and SEDir2
    Some of the shared objects in the MT 7 for Linux software require
    access to objects secured by SELinux. If the Install script detects
    SELinux, it assigns a security type to some shared objects. The
    script inspects the directories /usr/selinux/booleans and
    /selinux/booleans to determine if SELinux is active. If your SELinux
    is in a directory other these, change the definition of one of these
    variables.

  - SEGivePermission
    If the Install script detects SELinux, it assigns the security type
    'texrel_shlib_t' to some shared objects. If this is not appropriate
    for your system, edit the script and change this variable.

  - UdevDir and HotplugDir
    The MT 7 for Linux software supports hot plugging of USB controllers
    through either the udev or the hotplug systems. Older versions of
    Linux used the hotplug system. The udev system replaced hotplug. It
    is on most current distributions.

    The Install script checks for udev support first. It assumes that
    the udev support files are in the directory /etc/udev/. If udev
    resides elsewhere, change the definition of UdevDir to the
    appropriate path.

    The Install script assumes that the hotplug support files are in the
    directory /etc/hotplug/. If hotplug resides elsewhere, change the
    definition of HotplugDir to the appropriate path.

    If you want to disable hot plugging of USB controllers, change both
    UdevDir and HotplugDir to non-existent paths.

  - XinitDir and XinitSuffix
    The MT 7 for Linux runs some background tasks needed for full
    support of some user interface features. The Install script uses an
    X init script to launch these tasks.

    The Install script automatically places the script 50MT7-xinit into
    the /etc/X11/xinit/xinitrc.d, /etc/X11/Xsession.d, and
    /etc/X11/xinit.d directories. If your distribution requires the
    script to go into a different location, supply a value to the
    XinitDir variable in the Install script.

    Some distributions require a suffix for these scripts. If needed,
    change the XinitSuffix value to the needed suffix. For example, if
    your distribution requires these scripts to have a '.sh' suffix,
    change the XinitSuffix symbol to be ".sh".

----------------------------------
ERROR MESSAGES DURING INSTALLATION
----------------------------------
This covers error messages generated by the Install script. Programs
used by the script may generate their own messages. This section does
not cover those messages.

* You must have root privileges to run this script.
  You need to log in with an account with root privileges, use the 'su'
  command to open a root session, or use the 'sudo' command.

* 'perl' not found; please install perl.
  MT 7 for Linux requires perl. Install perl and then attempt to
  install MT 7 for Linux.

* 'uinput' not found.
  Starting with version 7.14, MT 7 for Linux requires the uinput kernel
  module. The script did not detect uinput and stopped installation.
  You need to use an earlier version of MT 7 that does not require
  uinput.

* Cannot find shared memory support
  The MT 7 for Linux software uses shared memory. Some older Linux
  systems do not provide this support and the package will not run.
  Contact 3M Touch Systems for other options.

* Cannot find java; the control panel may not work
  Variations of the message may refer to other directories depending on
  the setting of the JavaBinDir variable in the Install script.

  This is a warning. The installation continues after issuing this
  message.

  The MT 7 for Linux control panel is a Java application. You can
  install Java later and as long the java executable, or a link to it,
  is in a directory listed in your PATH environment variable, the
  StartCP script will run.

* Unable to determine where to install the HAL policy file.
  The script detected the presence of the hald program. Because the
  HalDir script variable was not set, it tried to detect
  /usr/share/hal/fdi/policy and /etc/hal/fdi/policy but failed.
  Determine where your system places its HAL policy files and set the
  HalDir variable in the script.

* HAL policy file copied. You may need to reboot your system.
  HAL will not recognize the new policy file until your reboot your
  system.

* Cannot install the init script
  The Install script tries to detect the presence of the chkconfig and
  update-rc.d utilities and the /etc/rc.d/rc.local script. If it cannot
  find any of these, this message appears.

  If your system uses the chkcconfig or update-rc programs, make sure
  the PATH environment variable contains the path to where the programs
  reside. If rc.local is in another directory, edit the Install script
  and change the value of the InitDir variable.

  If your system uses some other system, you need to place the init
  script TWDrvStartup in the appropriate place. The Install script
  creates a copy where the MT 7 for Linux package resides. You may need
  to edit the TWDrvStartup script to work with your system.

* Hot plugging of USB touch screen controllers is not supported
  The Install script cannot find the udev or hotplug support files.

  If you do not need hot plugging of USB controllers, ignore this
  message. Otherwise, edit the Install script and change the UdevDir or
  Hotplug variable to an appropriate value.

* Cannot find needed libstdc++.so in /usb/lib
  Variations of the message may refer to other directories depending on
  the setting of the LibDir variable in the Install script.

  The installation script could not find the standard C++ shared
  objects. Confirm that the LibDir variable is set correctly. If so, you
  need to install the C++ shared objects or, if already present, create
  a symbolic link using the name libstdc++.so to the C++ shared object.

---------------------------------
REMOVING MT 7 FOR LINUX
---------------------------------
In the installation directory, run the script Remove. This removes the
data directories and disengages MT 7 for Linux from the system. The
files remain. You must manually remove the files from the twscreen
directory.

---------------------------------
TROUBLESHOOTING THE INIT SCRIPT
---------------------------------
Due to the variety of methods of running init scripts, the Install
script makes a best guess as to when the TWDrvStartup script should run.
This guess is occasionally wrong.

There are three critical considerations regarding the init script
sequence.

* The USB file system must be operational before the TWDrvStartup
  script runs. If not, the driver does not service USB touch
  controllers. A symptom of this is calibration does not work.

* Any script that inspects serial ports must finish before the
  TWDrvStartup script runs. These programs can interfere with the
  driver's ability to detect and identify serial touch screen
  controllers. A symptom of this is touch or calibration not working.

In each case, you need to rearrange the order of the init scripts to
satisfy the requirements of the MT 7 for Linux software. The method to
do this is specific to your system's distribution.

---------------------------------
TROUBLESHOOTING TOUCH BEHAVIOR
---------------------------------
Many issues can affect touch.

If the cursor reacts to a touch but does not appear under your finger,
usually a simple calibration fixes the problem.

Run the MT 7 Control Panel or Calibration Tool. If these programs issue
an error message or do not display information about a touch screen,
review the section "Troubleshooting the Init Script" above.

If these tools detect a touchscreen but other programs do not react to
touch, it is likely that the X Windows server does not know about the
touchscreen.

Reboot your system.

If the problem persists, the system may be using the HAL program to
notify the X Server about devices on the system. The Install script
copies the policy file 99-3M-touchscreens.fdi to either
/usr/share/hal/fdi/policy or /etc/hal/fdi/policy.

Issue the command 'hald --version' to see if your system supports HAL.
If so, check the above directories to ensure the policy file is present.
If so, determine where your system stores its HAL policy files
elsewhere. If so, copy the policy file to the directory. You may also
want to uninstall MT 7, edit the Install script and set the variable
HalDir, and reinstall.

---------------------------------
RUNNING THE TOUCH APPLICATIONS
---------------------------------
There are two touch applications that you can run to customize the
touch system. These programs reside in the directory where you
installed the package.

* Calibration
  The Calibration program aligns the touch sensor to the display's
  screen. You should run this program after installation or whenever
  adding a new sensor to the system. Run the program by running the
  'TwCalib' program.

* Control Panel
  The Control Panel provides more features to customize. Run this
  program as needed by running the 'StartCP' script.

  Note that this is a Java program. This program requires a JRE that you
  may need to install. You also may need to edit the StartCP script to
  provide the proper path to the JRE.

-----------------------------------
CALIBRATION MESSAGES ARE UNREADABLE
-----------------------------------
The Calibration program attempts to use a Helvetica font. If not found,
it uses a relatively random font. This font may be unreadable.

To override this behavior, set the symbol MT7FontSanSerif to a proper X
Windows font name. To find a suitable font, use the xlsfonts command or
other suitable utility that lists the available fonts. In a command
prompt, set the symbol, export it, and run the MT 7 calibration utility
TwCalib. Experiment with the value of MT7FontSansSerif until the
calibration text is suitable. For example, if MT 7 for Linux is in
/etc/twscreen, a test sequence may be:

> MT7FontSansSerif="-*-utopia-*"
> export MT7FontSansSerif
> /etc/twscreen/TwCalib

You can also test your font string with xlsfonts. After setting
MT7FontSansSerif, issue the command 'xlsfonts -fn $MT7FontSansSerif' to
see what font, if any, matches.

If you find a suitable font, change your system login script, such as
/etc/profile.local, to set and export MT7FontSansSerif.

---------------------------------
KNOWN ISSUES
---------------------------------
Issue 9:  The driver does not detect USB controllers plugged into a hub
          on some early 2.6 kernels.
Issue 10: Some distributions show a slow update when dragging. Tapping
          works fine on these systems.
Issue 15: When running the package binary file, MT7.xx.xx.bin, the
          prompt to accept the license agreement does not appear at the
          bottom of some X terminal programs. Dragging the bottom of
          the terminal window exposes the prompt.
Issue 16: When using the standalone calibration tool, TwCalib, the
          calibration completion message appears on the primary display
          instead of the calibrated display. This happens only for
          multiple display systems.
Issue 18: Many graphical displays (for example, calibration and draw
          test) do not regain keyboard input after the user changes
          application focus (such as when using ALT TAB).
Issue 28: The driver crashes when using an EX HID controller on some
          early 2.6 kernels.
Issue 29: On some systems, there is a font problem with calibration
          when launched from the control panel. The standalone
          calibration program displays the fonts correctly. One recent
          distribution exhibits this issue.
Issue 33: Static text in the control panel may appear with a white
          background instead of the expected background color of the
          rest of the control panel.
Issues 34, 35: The labels on the sliders on the Edge Adjustment tab of
          the control panel may be misleading. The positions of the
          sliders are correct as are the values displayed at the end of
          the slider.
Issue 36: With some desktop managers, using the left and right arrow
          keys to navigate the control panel's tabs does not cause the
          tabs' contents to appear. In these cases, you need to hit the
          spacebar after using the arrow keys to select a tab.
Issues 37, 38: On a single distribution with SELinux set to "enforced",
          the Install script does not set the proper security on the
          necessary files. Once you set proper security on these files,
          the desktop manager crashes. The touch software works with
          SELinux disabled. 
Issue 39: On the Edge Adjustment tab in the control panel, you can use
          the arrow keys to change the settings of the sliders. Doing
          so slows the system down for several seconds. Using touch or
          a mouse works without a delay.
Issue 216: The bottom edge adjustment may not work on some systems.
Issue 248: The PX controller may show a status of 'STR'. This should be
          'PWM'.

---------------------------------
REVISION HISTORY
---------------------------------
Version 7.14.1, August 14, 2014
* The ReadMe.txt file now refers to the generic kernel 3.
* The ReadMe.txt file now states that PX support is single touch only.
* Sounds through the system speaker now work if the user is not root.
* The udev rules file 99-TwDrver.rules no long uses deprecated keywords.

Version 7.14.0, April 9, 2012

* Added support for the Linux kernel 3.0
* Added full 64-bit support for x86_64 platforms
* Added support for uinput
* Put the MT 7 version number in the control panel's title bar
* Disabled the 'right-click' button in the control panel
* Changed the StartCP script to check for the presence of Java

Version 7.13.6, September 21, 2011

* Added support for additional PX controllers.

Version 7.13.5, August 10, 2011

* Improvements in handling of Xinerama and RandR
* Added '--accept-license' to the distribution package
* Prevented multiple driver instances from running
* Improved handling of USB controllers when starting

Version 7.13.4, June 2, 2011

* The MT 7 Software now supports X server version 1.9 and 1.10.
* Added support for the PX 32" controllers.

Version 7.13.3, November 19, 2010

* The MT 7 Software now supports X server version 1.8.
* The MT 7 Software now supports 64 bit X server versions.
* Corrected an error that prohibited saving of configuration data.
* Fixed directory error in the TWDrvStartup init script.
* Eliminated a crash in the MT 7 X input module.
* Fixed the detection of monitor configurations on some XRandR systems

Version 7.13.2, April 15, 2010

* Added support for the PX series of controllers.
* Issue 8: Addressed the font issue in calbiration
* Issues 30, 97, 217, 218, 249, 263: The Control Panel now can run from
  outside its installation directory.
* Issues 40, 205, 206: Cleaned up the TWDrvStartup script.
* Issue 126: Changed to use MT7Help.pdf as the help file.
* Issue 162: Added support for X servers versions 1.6 and 1.7.
* Issue 188: Changed to properly restore calibration data on a CX
  controller.
* Issue 189: Changed to launch calibration after linearizing a CX
  controller.
* Issue 194: Fixed the /M:P and /M:F switches in TwCalib.
* Issue 203: Corrected the handling of pen and finger frequencies for
  the SX controllers.
* Issue 215: Corrected the handling of the /T switches in TwCalib.
* Issue 226: Fixed a memory leak related to loading auxiliary databases.
* Issue 238: The Monitor program is now responsible for sending 'beeps'
  to the system speaker.
* Issue 261: The Install script no longer supplies a default xorg.conf.

Version 7.12.5, July 15, 2009

* Calibration now works on systems that have XRandR 1.2 installed but
  enable Xinerama instead.

Version 7.12.4, April 17, 2009

* Added the Control Panel application. This program allows a user to
  calibrate touch screens and customize the system.
* Corrected the calibration tool so that its dialogs are centered
  properly on multiple monitor systems.
* Improved support for XRandR, Xinerama, and TwinView. This improvement
  adds a background task, TwMonitor, that detects changes in the
  system.
* Issue 7: The calibration tool now restores the prior calibration
  settings for an EX HID controller when calibration fails or is
  canceled.

Version 7.12.2, March 10, 2009

* Added support for the new MicroTouch CX series touch screen
  controller.
* Added support for the X.org X server version 1.5.
* Changed the X input module to support right-click in some early
  versions of the X server.
* Corrected the touch driver and the configuration library so that the
  driver would recognize MT 7 configuration changes, such as through
  the TwCfgUtil program.
* Changed the calibration and linearization functions to present an
  appropriate target shape when the monitor is in portrait mode.
* Improved the handling of the ESC key in the linearization and draw
  test functions.
* Corrected the error handling for the linearization function to
  provide more appropriate messages when an error occurs.
* Changed the installation script to link the X input module to the
  appropriate directory instead of copying it.
* Changed the removal of the touch screen section in the X server
  configuration file so that it no longer leaves extra blank lines.
* Corrected an error in the Install and TWDrvStartup scripts that
  incorrectly mapped a data file to the MT 7 binary path. This error
  was noticable on systems that write-protect the binary directory
  paths.
* Changed the TWDrvStartup script to install at runlevel 2 as well as
  5 to allow proper installation on systems that use runlevel 2 to
  launch X Windows.

Version 7.12.1, September 23, 2008

* Initial release

_______________________________________________________________________

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

Linux is a registered trademark of Linus Torvalds.

All other trademarks are the property of their respective owners.
_______________________________________________________________________
