=====================================================================                  

                 Elo Touchscreen Linux Driver - USB
       
         Installation/Calibration/Uninstallation Instructions 

---------------------------------------------------------------------                      
                            Version 3.1
                           July 25, 2008
                          Elo TouchSystems

=====================================================================                  

Elo Linux USB Driver package contains native Linux drivers designed for Linux kernel 2.6 (GCC version 3.3.5 and later), video alignment utility, rotation utility and control panel utilities for Elo touchmonitors. The driver works only for kernel versions 2.6.24 and below. 


This readme file is organized as follows:

  1. Supported Touchmonitors and Elo Touchscreen Controllers
  2. System Requirements
  3. Installing the Elo Touchscreen USB Driver 
  4. Calibrating the Touchscreen 
  5. Accessing the Control Panel  
  6. Adapting Touchscreen Calibration to Video Rotation 
  7. Uninstalling the Elo Touchscreen USB Driver
  8. Troubleshooting
  9. Contacting Elo TouchSystems



==========================================================
1. Supported Touchmonitors and Elo Touchscreen Controllers
==========================================================

 - Elo USB Controllers (IntelliTouch(R) 2600, 2500U, 
   CarrollTouch(R) 4000U, 4500U) 

  --------------------------------------------------------
 |                                                        |
 | Elo USB Controller AccuTouch(R) 3000U is not supported.|
 |                                                        |
 | This driver does not support Elo PC-Bus controllers.   |
 |                                                        |
  --------------------------------------------------------


======================
2. System Requirements
======================

 - 32 bit x86 platforms only

 - Kernels supported: 
    Kernel version 2.6.24 and below (GCC version 3.3.5 and later)

 - XFree86 supported: 
    Xfree86 version 4.3.0 
    Xorg version 6.8.2 - 7.2
    Xorg (Xserver) version 1.3
    Xorg (Xserver) version 1.4  


 - Motif versions supported:
    Motif version 3.0 (libXm.so.3)


Note:
=====

The same binaries folder can be used for installation on other machines using the same kernel.



===============================================
3. Installing the Elo Touchscreen USB Driver 
===============================================

Important:
==========
a.) Must have administrator access rights on the Linux machine to
    install the Elo Touchscreen USB Driver. 
 
b.) Ensure all earlier Elo drivers are uninstalled from the system.

c.) The USB Human Interface Devices (usbhid or hid) component must 
    be built and loaded as a module. The Elo Touchscreen USB driver
    will not function if the usbhid is built as a static 
    "compiled-in" module while building the kernel.

d.) Do not extract the downloaded binary package on a Windows system. 

e.) The environment should be setup for building kernel modules. 
    Check if necessary packages like gcc, make, kernel header files
    or kernel sources are installed. Refer to other documentation on 
    setting up the system for building loadable kernel modules.   

f.) This driver will work with GCC version 3.3.5 or later. Older 
    versions of GCC are not supported. 

g.) This driver will work only on kernel versions 2.6.24 and below.

h.) Motif 3.0 (libXm.so.3) library is required to use the Graphic
    User Interface (GUI) based control panel (/elo/cpl). Openmotif
    or lesstif installation packages provide the required libXm.so.3
    library.



Step I:
-------

Copy the elo driver files from the binary folder to the default elo folder. Compile the kernel module and copy it to the default elo folder. Change the permissions for all the elo driver files. Copy and place the X display Elo component file in the proper location.

  a.) Copy the driver files to /elo folder location.

       > cp -r ./bin-usb/  /elo
       > cd /elo

  b.) Compile and build the kernel module "elousb.ko" and check 
      if it compiles without any errors. Copy the kernel module 
      to /elo folder location.

       > cd ./elousbctrl-src
       > make
       > cp ./elousb.ko /elo/

  c.) Use the chmod command to set full permissions for all the
      users for the /elo folder.(read/write/execute) 

       > cd /elo
       > chmod 777 *


  c.) Copy and place the X display Elo component file in the proper
      location. Use "> X -version" command to check the X display
      version.


       For Xorg (Xserver) version 1.4 or later: (example: Ubuntu 8.04)
           
         > cp  /elo/elo_drv.so_1.4  /usr/lib/xorg/modules/input/elo_drv.so

       (or)

       For Xorg (Xserver) version 1.3: (example: Ubuntu 7.10)
           
         > cp  /elo/elo_drv.so_1.3  /usr/lib/xorg/modules/input/elo_drv.so

       (or)

       For Xorg version 7.2 to 7.3: (example: Fedora 7)
           
         > cp  /elo/elo_drv.so_7.2  /usr/lib/xorg/modules/input/elo_drv.so

       (or)

       For Xorg version 7.0 to 7.1.1: (example: Fedora Core 5)
           
         > cp  /elo/elo_drv.o_4.3  /usr/lib/xorg/modules/input/elo_drv.o

       (or)

       For other XFree86 or Xorg versions: (example: XFree86 4.3 or Xorg 6.8.2) 

         > cp  /elo/elo_drv.o_4.3  /usr/X11R6/lib/modules/input/elo_drv.o



Step II:
--------

Modify the X windows configuration file (xorg.conf or XF86Config or XF86Config-4). This file is located in the /etc/X11 directory. Check the X windows log file ("/var/log/XFree86.0.log" or "/var/log/Xorg.0.log") to verify the X windows configuration file in use. 

  a.) Add the following lines to create a new Elo device configuration at the end of the file.
   
        Section "InputDevice"
           Identifier "elo"
           Driver "elo"
           Option "Device" "/dev/input/elo"
           Option "SendCoreEvents" "true"
        EndSection


  b.) Add the following line to the ServerLayout section to include
      the elo input device.
         
        InputDevice "elo"



Step III:
---------

Confirm whether the "/dev/input" directory exists. If it does not exist, create a new directory.
           
  > mkdir -p /dev/input



Step IV:
--------
 
Install the "elousb" driver module by running the following command.

  > ./install.sh



Step V:
-------

Configure a script to invoke Elo service at system startup.  


Debian, Ubuntu (older than 6.10) systems: 
- - - - - - - - - - - - - - - - - - - - -
 
Copy the elorc script file present in the /elo directory to the /etc/init.d directory.
 
  > cp /elo/elorc /etc/init.d 

A symbolic link for the elorc script has to be created in the desired runlevel directory (example: rc2.d,rc3.d,....rc5.d). This will allow the elorc script to run at system startup. Ubuntu and Debian systems use runlevel 2 (rc2.d directory) as default.

This directory has startup files (symbolic links) of the form SDDxxxx where DD is the sequence number. Pick a sequence number XX which is at least one smaller than the sequence number of the display manager script (xdm, gdm, etc.) found in this directory. 

Use the maintainer script update-rc.d to create the elorc symbolic link with selected sequence number XX.

  > cd /etc/rc2.d 
  > update-rc.d elorc start XX 2 .


Important: 
==========

 - Only use the update-rc.d maintainer script to modify these        
   symbolic links. The elorc script will not be run at startup
   if these symbolic links are  manually created. 

 - Notice that the update-rc.d command syntax has a space and
   period after the run-level parameter. 

 - The above example is for runlevel 2. Pick the appropriate folder
   for the desired runlevel. The default runlevel can be found in
   the /etc/inittab file.


Note:
===== 

The path of the runlevel directories might vary from distribution to distribution. The path for runlevel 5 in Redhat is "/etc/rc.d/rc5.d" while the path for Debian and Ubuntu is "/etc/rc2.d" for runlevel 2.

Locate the corresponding runlevel directory in the system and create the symbolic link for elorc script file in that directory using the update-rc.d maintainer script.
   


Redhat, Fedora, Mandrake, Slackware and Ubuntu (6.10 or later) systems:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

On the above distributions, there are some restrictions for running the elorc script from /etc/rc.d/rc*.d directory. Hence, add the following two lines at the end of daemon configuration script in "/etc/rc.local" file. 

[ rc.local file might also be at location /etc/rc.d/rc.local. Use the   "> find /etc -name rc.local" command to locate the rc.local file.]

  /elo/loadelo  
  /elo/elodaem 



SUSE Systems:
- - - - - - -

Add the following two lines at the end of the configuration script in "/etc/init.d/boot.local" file.

  /elo/loadelo
  /elo/elodaem



Step VI: (Debian, Ubuntu (except Ubuntu 6.10) skip to Step VII)
--------

Redhat, Fedora, SUSE, Mandrake, Slackware and Ubuntu 6.10 systems:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The elousb module needs to load before the USB Human Interface Devices (usbhid or hid) module, to take control of the Elo USB Touchscreen Controller, during system startup. Select and modify the appropriate module configuration file (/etc/modules.conf or /etc/modprobe.conf or /etc/modules) based on the kernel version to enable elousb module to load before USB HID module. Use the "> uname -r" command to check the current kernel version.

  a.) For 2.4 kernels edit the "/etc/modules.conf" file and add
      the following line at the end of the file.

       post-install usbcore modprobe elousb
  

    (or)   


  b.) For 2.6 kernels edit the "/etc/modprobe.conf" or "/etc/modules" file and add
      the following line at the end of the file. 

      install <name-of-your-hid module> { /sbin/modprobe elousb; } ; /sbin/modprobe --first-time --ignore-install
      <name-of-your-hid-module> && { /sbin/modprobe/ keybdev; /sbin/modprobe mousedev; /bin/true;}


      Note: 
      =====
 
      Replace <name-of-your-hid module>, in the above line, with the
      correct USB HID module name. The name may vary from
      distribution to distribution. Use the "> lsmod |grep hid" 
      command or use the 
      "> ll /lib/modules/`uname -r`/kernel/drivers/usb/input" 
      command to locate the HID module and note the exact module
      name. The module name is usually "usbhid" or "hid" in most
      popular distributions.  

      The names of the keyboard and mouse modules may also vary
      among distributions. The use of the "keybdev" and "mousedev"
      module names will provide the required device functionality but
      may cause warnings to appear. To avoid these warnings locate
      the exact modules names for the keyboard and mouse and replace
      the generic names mentioned above.      

      Example: Consider the USB HID module is named "usbhid", the
      keyboard module is named "keybdev" and the mouse module is
      named "mousedev". The modified line to insert at the end of
      the "/etc/modprobe.conf" or "/etc/modules" file is shown below.  
 
      install usbhid { /sbin/modprobe elousb; } ; /sbin/modprobe --first-time --ignore-install 
      usbhid && { /sbin/modprobe/ keybdev; /sbin/modprobe mousedev; /bin/true;} 



Step VII:
--------
 
Debian, Ubuntu systems (except Ubuntu 6.10): (Other Linux & Ubuntu 6.10 systems skip to Step VIII)
- - - - - - - - - - - - - - - - - - - - - -

The elousb module needs to load before the USB Human Interface Devices (usbhid or hid) module, to take control of the Elo USB Touchscreen Controller, during system startup. 

  a.) For Debian system: Edit the "/etc/modules.conf" file and add
      the following line at the end of the file.

       post-install usbcore modprobe elousb
  

    (or)   


  b.) For Ubuntu 7.10 or 8.04 system: Edit the "/etc/rc.local" file 
      to add entries to remove elousb and usbhid modules and then 
      load elousb ahead of usbhid. These entries have to be added 
      before the "/elo/loadelo" and "/elo/elodaem" entries. The 
      /etc/rc.localfile would look similar to this at the end.

      rmmod elousb
      rmmod usbhid
      sleep 1s
      modprobe elousb
      modprobe usbhid

      /elo/loadelo
      /elo/elodaem   
  

    (or)   


  c.) For Ubuntu 7.04 system: Copy and place the "elo.modprobe" file 
      in the "/etc/modprobe.d" directory.

      > cp /elo/elo.modprobe /etc/modprobe.d/
  

    (or)   


  d.) For Ubuntu 6 system: Edit the "/etc/init.d/readahead" file and
      add the following line before the "exit 0" command at the end
      of the file.
   
      /sbin/modprobe elousb


    (or)   


  e.) For Ubuntu 5.1 system: No modifications are needed as the
      necessary commands to load the elousb ahead of the USB HID
      module are already inserted into the modified "elorc" script.
      Proceed to Step VIII.


Step VIII:
----------

Reboot the system to complete the driver installation process.
 
  > shutdown -r now 



==============================
4. Calibrating the Touchscreen
==============================

Important:
==========

Users must have read and write access to "/dev/elo" directory and "/dev/input/elo" file to perform the touchscreen calibration. 


Step I:
-------

Run the calibration utility from a command window in X Windows from the /elo directory. 

  > cd /elo
  > ./elova -u 


Step II:
--------

Touch the targets from a position of normal use. The calibration data is written to the driver at the end of calibration. 



==============================
5. Accessing the Control Panel 
==============================

The control panel application allows the user to easily set the available driver configuration options. After the driver package is installed, change to the /elo directory and run control panel application. 


Important:
==========

Users must have read and write access to "/dev/elo" folder to run the control panel applications.


Step I:
-------

Run the control panel utility from a command window in X Windows from the /elo directory. Motif version 3.0 (libXm.so.3) is required to use the GUI based control panel (/elo/cpl).

  > cd /elo
  > ./cpl 


Step II:
--------

Navigate through the various tabs by clicking on them. Here is an overview of information related to each tab.

  General    - Perform touchscreen calibration
  Mode       - Change the touchscreen mode
  Properties - Display data related to the Serial/USB touch monitor.
  About      - Information about the package. Click on the Readme                    
               button to open this Readme file. 
	

Step III:
---------

If Motif is not installed, use the command line version of the application to access the control panel. Run the command line application from a command window in X Windows from the /elo directory.

  > cd /elo
  > ./cplcmd



=====================================================
6. Adapting Touchscreen Calibration to Video Rotation 
=====================================================

Important:
==========

Users must setup the touchscreen rotation support using the /elo/rotate/setup_rotation.sh script. This script must be run in normal video mode without any rotation.  


Step I:
-------

Run the setup_rotation.sh script from a command window in X Windows from the /elo/rotate/ directory. The script will invoke elova calibration utility to perform an accurate calibration in normal video mode. It then saves this normal video mode touchscreen configuration file as /elo/rotate/eloconfig_rotate_normal.Once this file is created, the touchscreen rotation feature can be used.   

  > cd /elo/rotate
  > ./setup_rotation.sh 

As an option, if you like the current calibration and do not wish to run calibration utility again, you can manually copy the /elo/eloconfig file and rename it as /elo/rotate/eloconfig_rotate_normal. Proceed to the next step.


Step II:
--------

Use the elorotate utility to adapt the touchscreen calibration to the current video rotation mode.

 > cd /elo/rotate
 > ./elorotate /?       [ Lists the utility description, usage and options available ]
 > ./elorotate -left    [ Adapts the touchscreen calibration for LEFT video rotation ]    
 > ./elorotate -right   [ Adapts the touchscreen calibration for RIGHT video rotation ]
 > ./elorotate -normal  [ Restores the touchscreen calibration to NORMAL video rotation ]

The utility can be used to adjust the touchscreen calibration after or before the video rotation is performed using the command line options. Another option would be to use a script file (example: /elo/rotate/elo_video_rotate.sh) to perform both the video and touchscreen rotation at the same time. Please edit the script file to suit the target system.

 > cd /elo/rotate
 > ./elo_video_rotate left   [ Rotate video and touchscreen to the LEFT ]
 > ./elo_video_rotate normal [ Restore video and touchscreen to normal mode ]
   


=================================================
7. Uninstalling the Elo Touchscreen USB Driver
=================================================


Important:
==========
Must have administrator access rights on the Linux machine to uninstall the Elo Touchscreen USB Driver. 



Step I:
-------

Delete the script or commands that invoke Elo service at startup.  


SUSE systems: 
- - - - - - -
Remove the following entries created in Step V of Installation section from the configuration script in"/etc/init.d/boot.local" file.

  /elo/loadelo
  /elo/elodaem


Redhat, Fedora, Mandrake, Slackware and Ubuntu (6.10 or later) systems:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Remove the following entries created in Step V of Installation section from the configuration script in "/etc/rc.local" file. (or "/etc/rc.d/rc.local" file)
        
  /elo/loadelo
  /elo/elodaem


Debian, Ubuntu (older than 6.10) systems: 
- - - - - - - - - - - - - - - - - - - - -

a.) Remove the symbolic link file created in Step V of Installation     
    section using the update-rc.d maintainer script.
 
      > update-rc.d -f elorc remove


b.) Remove the elo script file "elorc" placed in the "/etc/init.d"        
    directory.

      > rm /etc/init.d/elorc



Step II:
--------

Delete the following lines from X windows configuration file (xorg.conf or XF86Config or XF86Config-4). This file is located in the /etc/X11 directory. Check the X windows log file ("/var/log/XFree86.0.log" or "/var/log/Xorg.0.log") to verify the X windows configuration file in use. 

  a.) Delete Elo device configuration section
       
      Section "InputDevice"
        Identifier "elo"
        Driver "elo"
        Option "Device" "/dev/input/elo"
        Option "SendCoreEvents" "true"
      EndSection

   b.) Delete the elo device from the ServerLayout section
      
       InputDevice "elo" 



Step III:
---------

Delete all the elo driver files from the system.

  a.) Delete the elo driver folder.

        > cd /
        > rm -fR /elo


  b.) Delete X display elo component. Use "> X -version" command to  
      check the X display version.

        For Xorg version 7.2, Xorg (Xserver) version 1.3, Xorg (Xserver) version 1.4 or later: (example: Fedora 7)
        
          > rm /usr/lib/xorg/modules/input/elo_drv.so

        (or)

        For Xorg version 7.0 to 7.1.1: (example: Fedora Core 5)
        
          > rm /usr/lib/xorg/modules/input/elo_drv.o

        (or)

        For other XFree86 or Xorg versions: 
  
          > rm /usr/X11R6/lib/modules/input/elo_drv.o


  c.) Delete all the elo related folders.

        > rm -fR /dev/elo
        > rm /dev/input/elo



Step IV:
--------

Remove the installed "elousb" driver module from the directory "/lib/modules/`uname -r`/kernel/drivers".

  For 2.4 Kernels:
    > cd /lib/modules/`uname -r`/kernel/drivers
    > rm -r elousb.o 
    > depmod -a
 
  (or)  

  For 2.6 Kernels:
    > cd /lib/modules/`uname -r`/kernel/drivers
    > rm -r elousb.ko
    > depmod -a



Step V: (Debian, Ubuntu systems (except Ubuntu 6.10) skip to Step VI)
-------

Redhat, Fedora, SUSE, Mandrake, Slackware and Ubuntu 6.10 systems:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Delete the command lines inserted in the modules configuration file
in Step VI of the Installation section. Select and modify the
appropriate module configuration file (/etc/modules.conf or
/etc/modprobe.conf or /etc/modules) based on the kernel version. Use the "> uname -r"
command to check the current kernel version.

  a.) For 2.4 kernels edit the "/etc/modules.conf" file and delete
      the following line at the end of the file.

       post-install usbcore modprobe elousb
  

    (or)   


  b.) For 2.6 kernels edit the "/etc/modprobe.conf" or "/etc/modules" file and delete
      the following lines at the end of the file. The exact names of
      the USB HID, Keyboard and mouse modules may vary among
      distributions. Refer to the note in Step VI of the Installation
      section for further details. 

      install <name-of-your-hid module> { modprobe elousb; } ; /sbin/modprobe --first-time --ignore-install
      <name-of-your-hid-module> && { /sbin/modprobe/ keybdev; /sbin/modprobe mousedev; /bin/true;}



Step VI:
-------
 
Debian, Ubuntu systems: (Other Linux & Ubuntu 6.10 systems skip to Step VII)
- - - - - - - - - - - -

Delete the command line inserted in the modules configuration file or startup script file in Step VII of the Installation section.

  a.) For Debian system: Edit the "/etc/modules.conf" file and delete 
      the following line at the end of the file.

       post-install usbcore modprobe elousb
  

    (or)   


  b.) For Ubuntu 7.10 or 8.04 system: Edit the "/etc/rc.local" file 
      to remove all the entries shown below.

      rmmod elousb
      rmmod usbhid
      sleep 1s
      modprobe elousb
      modprobe usbhid

      /elo/loadelo
      /elo/elodaem   
  

    (or)   


  c.) For Ubuntu 7.04 system: Delete the "elo.modprobe" file in the
      "/etc/modprobe.d" directory.

      > rm /etc/modprobe.d/elo.modprobe
  

    (or)   


  d.) For Ubuntu 6 system: Edit the "/etc/init.d/readahead" file and
      delete the following line located before the "exit 0" command
      at the end of the file.
   
      /sbin/modprobe elousb


    (or)   


  e.) For Ubuntu 5.1 system: No modifications are needed as the
      modified "elorc" script has been deleted in Step I of this
      Uninstallation section. Proceed to Step VII.



Step VII:
---------

Reboot the system to complete the driver uninstallation process.
 
  > shutdown -r now 



==================
8. Troubleshooting
==================

A. Every time X Windows is reconfigured using XWindows configurator, 
   the X windows configuration file (xorg.conf or XF86Config) has to     
   be modified to include the elo device configurations mentioned in       
   Sp II of the Installation section.

B. Hardware Check (For Serial devices only)
   --------------

   To verify that the touchmonitor is connected and functioning 
   correctly, type the following command in an command window 
   for serial port 1 (COM1).

     > od -h -w10 </dev/ttyS0 

   Similarly for serial port 2 (COM2) use,

     > od -h -w10 </dev/ttyS1 

   The screen should start displaying a lot of numbers when the
   screen is touched. The standard Elo protocol data packet is 
   identified by the distinctive appearance of "5455" as the 
   first byte pair of a 10 byte data packet. 

C. The display image should be centered on the screen and fill 
   as much of the visible area of the touchmonitor screen as 
   possible without image distortion. 

  
D. Incase of Mandrake Linux, use the xdm display manager instead of      
   "Mandrake Display Manager". This can be changed using the      
   "settings" from "display manager". 



==============================
9. Contacting Elo TouchSystems
==============================

Website: http://www.elotouch.com


E-mail:  eloinfo@elotouch.com


Mailing Address: 
----------------

  Elo TouchSystems, 
  301 Constitution Dr.,
  Menlo Park, CA 94025
  USA

  Phone:   (800) 557-1458
           (650) 361-4700
  Fax:     (650) 361-4722

--------------------------------  

  Elo TouchSystems GmbH & Co. KG
  Haidgraben 6
  D-85521 Ottobrunn
  Germany
         
  Phone: +49 (0) 89/60822-0
  Fax:   +49 (0) 89/60822-150

--------------------------------  

  Elo TouchSystems, NV
  Diestsesteenweg 692
  B-3010 Kessel-Lo
  Belgium

  Phone: +32 (16) 35-2100
  Fax:   +32 (16) 35-2101


=====================================================================                  
                Copyright (c) 2008 Elo TouchSystems

                       All rights reserved.

===================================================================== 
