Revision 1.15, 14th Jan 2007

Linux Installation

Limitations

Requirements

Important notes

Welcome to UPDD Linux platform specific notes for UPDD 4.0.6. Although UPDD V4 driver was released in Oct 2006 these notes and the information held within has been build up over the years with the usage of our previous driver in the Linux environments but have been modified to accommodate installation and other subtle changes relating to version 4.

Very important general note: Linux is an open source environment utilised and supported by highly knowledgeable and capable developers. Many aspects of the Linux system are maintained by Linux groups and communities. Nearly all software created by these Linux groups is made available under open source license agreements, including any touch screen drivers that have been written, mainly by individuals. Linux distributions are many and varied and all have slight subtle differences. Many users, developers and integrators in the Linux community do not expect to pay for software. All of this makes it commercially very difficult to operate in the Linux environment with a niche product such as our touch screen driver products.

Our driver is mainly aimed at the non technical Linux users or larger commercial organisations that need a tried and tested touch driver solution that comes with comprehensive support. To this end our driver offers a generalised installation package with basic system requirements and in many cases should work ‘out the box’, especially with the main stream Linux distributions. If you are a Linux technician, with access to open source touch driver code that you can modify and make the necessary system configuration changes then UPDD is unlikely to match your specific requirements particularly as there are license costs involved.

Further, given the number of Linux distributions, if UPDD has any issues on distributions not listed and tested we may not be readily able to offer free support as the amount of support needed does not match the commercial viability of Linux sales.

License Notice

The software is licensed software and as such requires a license per system when the production version of the software is installed. Production software is either supplied by pointer device manufacturers or system integrators (who are entitled to distribute the driver) or is available directly from Touch-Base sales.

Evaluation software, which is available from our Download Centre has a 100 ‘mouse click’ restriction at which point the driver needs to be reloaded or a calibration performed to gain a further 100 clicks.

Copyright Notice

The Linux version utilises a software library, libusb, which is used under the terms of the GNU Lesser General Public License as published by the Free Software Foundation and under the terms of this license the following applies:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Under the terms of this license we will also make the Universal Pointer Device Driver binaries available to allow the libusb module to be replaced with an alternative version. Please contact technical@touch-base.com for further information.

Full details of the LGPL are available here.

Linux driver build history

Release

Date

Change

4.0.2

10^th Oct 06

Initial Version 4 release for X86 systems

22^nd Nov 06

Support new X interface on Fedora Core 5

4.0.4

5^th Jan 07

Added support for Power PC based systems

16^th Jan 07

Changes required for SUSE 10.1

17^th Jan 07

Interactive touch fix. Mouse settings called from Click Mode dialog for KDE and Gnome.

9^th March 07

Multi-monitor support added

4.0.6

15^th Nov 07

Linux 64 bit support

Deliverables

The main installation package is held within the compressed file called linuxupdd.tgz. Software requested from Touch-Base to be delivered electronically will be delivered in one of three ways:

As an email attachment.

Delivered to an FTP folder for manual download. The FTP link, user name and password details will be sent in an email.

Automatically downloaded from a HTTP download link as sent in an email.

General Notes

UPDD for Linux has two driver components. A core processing engine which exists outside the kernel and an X extension to provide the mouse interface for X based GUI applications. This architecture allows for maximum portability. As the core driver is not embedded in the kernel a single compiled module can be executed on any kernel version. The vast majority of users use X to host GUI applications; however, UPDD has the flexibility to support other GUI’s by reimplementation of this minimal module.

Hardware access is performed through operating system defined device interfaces allowing UPDD to operate with all compliant hardware, rather than just those tested by Touch-Base. UPDD’s flexible modular architecture does however allow for direct hardware access to be added for specific device categories if required.

The initial UPDD for Linux was developed under Linux 2.4 + X (or X-Windows). The driver has been tested on various Linux flavours using Xfree86, mainly version 4.x and more recently X.org. It has also been extensively tested under 2.6.x kernel. In theory the driver should install and run on most of the standard Linux distributions. Please contact us if you should experience any difficulties installing or running the driver as it is likely to be a minor issue that is preventing the software from working.

You should be aware that it is possible to load multiple X sessions on a machine and switch between them as required. At any one time an X session will be active on the desktop and the other X sessions will be in the background. The driver can be installed from any X session. Each X session running will receive pointer movements and click requests which might not be desirable as you will not know what is being selected in the hidden, background, X sessions. We believe that in a touch environment most users will only run with one X session and therefore we do not think this is a significant issue. Please contact us if this causes any problems, as it may be possible for us to limit mouse movement and clicks to the active X session if you must run in a multiple X session environment.

The driver is statically linked with its required libraries and as such is quite large in size. This is normally not an issue for standard Linux desktop systems but can be an issue in specialised, cut down or embedded Linux environments. Please contact technical@touch-base.com if you require a dynamically linked version of the driver.

There are a number of hardware considerations:

USB

If you are installing a USB controller please be advised that in our experience USB port initialisation can take up to 20 seconds to complete, during which time USB connected touch screens will not be active. The driver initialises the USB port when it loads, and currently, after calibration.
Important USB controller observation: Not all USB controllers are supported by Linux. We have found a number of USB controllers that do not conform to USB standards and hence cause issues with the underlying OS interface. Most of these controllers have successfully worked in Windows by fluke or driver changes to overcome shortcomings in the firmware. It is only when they are used on a different OS that the problems appear.
Important USB technical interface note: Prior to UPDD version 3.7.10, the driver’s USB interface method resulted in a timeout warning in the system log every time a USB pending read timed out. This could result in 1000’s of entries in the log given sufficient time. Although we considered this to be an unnecessary warning message issued by the OS we investigated alternative approaches to overcome this issue.

Unfortunately, finding a generic solution has not been as straight-forward as envisaged, given that USB support in some Linux distributions appears to be flakey in places. We found that terminating pending read requests does not work as expected (we found that although pending reads can be cancelled the USB stack goes mad issuing log messages until the next interrupt occurs). It should be possible to circumvent this by use of the USB reset command, but this forces a bus re-enumeration and several touch screen controllers we tested with stopped working after this. We also found that in some cases, if we do successfully cancel outstanding read requests the thread that requested the read will not terminate until the timeout period on the read elapses – all very frustrating! In addition to this we also found that older versions of the kernel do not work consistently after the pending i/o cancellation. Given that the USB stack support appears to be so flakey in some distributions, we have had to go for a non optimal solution that appears to work in all cases. The new USB interface method works perfectly well. However, to receive USB data there is always a pending read outstanding and drivers cannot be unloaded in this state, which in some cases we need to do (trouble shooting etc) so we deliberately placed a timeout on this read of 10 minutes at which time we reissue the read. This does, however, result in a timeout message being written to the timeout log every 10 minutes, which we trust is acceptable.

PS/2

Linux kernel version 2.6.5 introduced specific problems for PS/2 devices. However a publicly available patch corrects this problem and UPDD will generally work with PS/2 connected devices on this kernel version. See point 3 below.

Unfortunately later kernel versions have introduced a new category of problem. Whereas previously the device /dev/aux was available to read ps/2 data, this now appears to be a synonym for /dev/mice, so data from all mice is passed to this device. Moreover the data from any connected PS/2 device that does not match the protocol of a PS/2 mouse is altered.

This behaviour was first observed with kernel version 2.6.20-15. This makes it impossible for UPDD to support PS/2 devices using the /dev/aux device.

There are other approaches that might be possible, but these are not considered viable given the non-commercial nature of Linux and the R&D effort that might be required.
On some of our development systems the PS/2 data received into the driver is not consistent and makes for very poor usage as a pointer device, especially with our driver, as the driver spends a great deal of its time resyncing on the next data packet. On other systems the driver works perfectly OK. However, none of our customers using the PS/2 driver have reported poor performance and we believe this to be system specific issue.
In early Linux version 2.6.x the developers have removed the functionality needed for users to access the PS/2 hardware, amongst others, and have instead implemented mouse drivers in the kernel itself. This means that UPDD can no longer interface to PS/2 touch controllers unless the kernel is patched with a third party module.

To incorporate this module, which provides the Linux 2.4 method of accessing PS/2 devices into kernel 2.6, the patch available at http://www.ee.oulu.fi/~tuukkat/rel/psaux-2004-04-19.tar.gz should be applied. Once the patch is applied, the documentation for this patch is located in /usr/src/linux-2.6.6userdev/Documentation/input/serio-userdev.txt.

In later versions of 2.6.x a serio_raw device has been introduced which we believe is a continuation of the above patch which has now been officially included in the kernel.

The “serio_raw” module is a 2.6 kernel feature (which appeared sometime after 2.2.6) that allows raw access to IO ports in the way that was possible with kernels 2.4 and earlier. This module needs to be enabled and then the PS/2 port remapped port to /dev/psaux (which is now redundant in 2.6 but used by the touch driver). This is needed because serio_raw maps the PS/2 port to something other than /dev/psaux.

To enable PS/2 access on later Linux 2.6 kernels the following should be performed as “root”:-

Edit “/etc/modprobe.conf” and add the line: “install psmouse /bin/echo”
Edit “/etc/modules” and add the line “serio_raw”
Edit “/etc/rc.local” and add the line “echo -n "serio_raw" > /sys/bus/serio/devices/serio1/drvctl”
In a console window type “rm -rf /dev/psaux”
In a console window type “mknod /dev/psaux c 10 63”
Restart the system

Some Linux systems have a built in PS/2 mouse driver that can conflict with UPDD. It is necessary to disable this built in driver. Unfortunately it is difficult to implement a generic automated solution because the exact data to be changed can vary from system to system. Until we have an automated solution you can use the guidelines below to modify the Linux configuration files to disable the internal driver. If there is anything unclear please email us for further guidance.

In the file /etc/X11/XF86Config there is a section which will be similar to the following:-

Section “InputDevice”

Identifier “Mouse0”

# Modified by mouseconfig

Driver “mouse”

Option “Device” “/dev/mouse”

Option “Protocol” “PS/2”

Option “Emulate3Buttons” “no”

Option “ZaxisMapping” “4 5”

EndSection

This identifies a PS/2 mouse to use with X using the name ’Mouse0’ to identify itself. There will be another section like the one shown below:

Section “ServerLayout”

InputDevice “Updd0” “SendCoreEvents”

Identifier “Anaconda Configured”

Screen 0 “Screen0” 0 0

InputDevice “Mouse0” “CorePointer”

InputDevice “Keyboard0” “CoreKeyboard”

EndSection

The line ‘InputDevice “Mouse0” “CorePointer”’ in this section is including the PS/2 mouse driver configured in the other section. This line should be removed.

The line ‘InputDevice “Updd0” “SendCoreEvents”’ should be modified so that it reads:-

InputDevice “Updd0” “CorePointer”

System Requirements

Apart from the Linux kernel software our software requires the following components:

XF86config-4 XF86config Xorg.conf	graphical interface (if using a graphics interface – driver will load and work without X allowing for application API interface to driver) See Window Manager installation below.
“86” in the config file names refers to the fact that it was originally developed on x86 and doesn’t actually reflect what processor/platform it’s running on
Fileutils	mkdir, cd etc, Sound utility sox if using calibration beeps, see Hardware requirement below.
C library	UPDD V4 uses dynamic linked library calls so requires the C library to be available. UPDD V4 utilises release 6 (libstdc++.so.6). C library version 6 has been available for a number of years and should be shipped as standard in most Linux distributions. For legacy distributions with earlier C libraries either install the V6 lib or use UPDD V3 (uses V5 C library). A C++ version 6 library that may be suitable in some distributions can be found here.
Hardware	If calibration beeps are enabled in the UPDD Console a sound card is required as we have not been able to access the internal PC speaker under Linux.
USB	*Important:* For USB devices the USB file system must be a component of the distribution and enabled.

UPDD version 4 Linux has been tested on both X86 and Power PC implementations.

X86 Distribution	Date tested (or informed all OK by user)
Many Linux X86 distributions have been tested and found to work fine as long as they conform to the above system requirements:
SUSE 8, 9.3 and 10.0	May require C library version 6 (libstdc++.so.6) to be installed
Redhat 8, 9 and 10	May require C library version 6 (libstdc++.so.6) to be installed
Fedora Core 1, 2 and 3
Debian 3.0 (Woody)
Gentoo Linux 2006.1	31^st October 2006, see Gentoo notes below.
Fedora Core 5	22^nd Nov 2006. Tested in-house. Needed changes to support new X interface
Fedora Core 6	23^rd Nov 2006. Reported OK by a customer.
SUSE 10.x	15^th Jan 2007. Tested in-house. Needed change to support new task initiation. See Suse 10.x notes below
Mandriva 2006	26^th Feb 2007. Reported OK by a customer.
Maemo 2.0	9^th March 2007. Reported OK by a customer. Cannot handle full screen calibration so calibration style Custom2Point must be defined and used. See Calibration note below.
Maemo 3.0	9^th March 2007. Tested in-house. Cannot handle full screen calibration so calibration style Custom2Point must be defined and used. See Calibration note below.
Slackware 11	23^rd March 2007. Tested in-house.
Debian 4.0 (Etch)	1^st Aug 2007. Tested in-house.
Ubuntu – Edgy Eft	1^st Aug 2007. Tested in-house.
Ubuntu – Feisty Fawn	13^th Dec 2007. Tested in-house. Needed change to driver start up scripts.
Ubuntu – Gusty Gibbon	13^th Dec 2007. Tested in-house. Needed change to driver start up scripts. USBFS must be enabled, see below.
Limited testing on Power PC but there is a good chance that it will work on most Power PC distributions
Power PC distribution
Debian	5^th Jan 2007 – Tested in-house.
Important – Check the distribution notes section below that records any issues we have had during testing
Distribution Notes At the time of writing we are aware of the following distributions that have some issue:

Distribution	Issues
General	Window management issue – first noted on Fedora Core 5 and 6 and also reported on Suse 10.1 but could effect other distributions: Generating a click via touch is sometimes ignored. In some areas of the Linux menu system we have found that unless the mouse is moved to the position of the click the click is ignored, such as the 2^nd level of menus from the Application start menu option: Some items within the applications menu will expand to a 2^nd level menu. Lifting the stylus off the first menu and clicking into the second menu item will not activate the selected item. You need to slide your finger from the first menu to the second menu and lift the stylus off when over the desired item. This problem can also be seen with a mouse by having the mouse at the position of the second level item and clicking when it is shown. With no mouse movement prior to click, the click is ignored.
Calibration	Correct operation of the calibration requires the calibration screen to be displayed in full screen mode. Some Linux distributions cannot handle the method used by our calibration program to force full screen with unpredictable results. To date we have seen this with Linux distribution Maemo. On systems where the full screen issue occurs, one of the following actions will be necessary: 1. Execute the calibration program in an environment that supports full screen display. For example if a window manager is preventing full screen mode try running without the window manager active. (This has been necessary on systems using the TWM window manager) 2. In cases where full screen is not possible we have utilised a UPDD calibration style, named Custom2Point, whereby calibration does not attempt full screen mode (and therefore cannot draw accurate calibration points) but instead requests that the top left and bottom right corners of the calibration area be used as the calibration reference points. No other calibration patterns are catered for. Either request a build from Touch-Base with this calibration style pre-defined or use the UPDD Console, calibration dialog to add the style (deleting the existing style) and then calibrate to invoke corner calibration.
TWM window manager	In order to calibrate you must run the calibration program (tbcalib) without the TWM window manager active so that the entire screen area is used. If this is not possible see calibration notes above.
Slackware 10	We found two issues with this distribution: 1. The Linux files are installed in a different file structure so UPDD install does not locate configuration file and therefore there is some extra work to do after installation, as follows: Install UPDD as normal. Then create a file called “rc.updd” in the “/etc/rc.d” directory with the following content:- #!/bin/sh if [ “$1” = “stop” ]; then echo “Stopping updd…” killall tbupddlx elif [ “$1” = “restart”]; then echo “Restarting updd…” killall tbupddlx sleep 1 /tbupddlx/tbupddlx & else # assume $1 = start: echo “Starting updd: /tbupddlx/tbupddlx” /tbupddlx/tbupddlx & fi It should be marked executable by typing “chmod +x /etc/rc.d/rc.updd” The file “/etc/rc.d/rc.local” should be modified to include the following 3 lines (the location of these lines is not significant so long as they do not split an existing code block):- if [ -x /etc/rc.d/rc.updd –a –x /usr/sbin/syslogd –a –d /var/log ]; then . /etc/rc.d/rc.updd start fi The system should then be rebooted. We will automate this installation in a forthcoming UPDD release. 2. The default Linux kernel provided with Slackware 10.1 has problems with USB that prevent UPDD communicating with a USB device. However there is a 2.6 kernel supplied on CD2 of the distribution which functions correctly. To install and use this kernel follow the instructions located in mountpath>/testing/packages/linux-2.6.10/README.initrd.
Mandrake 9.2	Installs X 3.n.n. X needs to be upgraded to 4 to work.
Elinos Embedded