If you need a driver for other environments, such as a different graphics manager or different processor we can update our driver to match your requirements but there will be a cost involved on a time and materials basis.

UPDD Linux has been around many years and used on many distribution and the old Linux documentation lists previous distributions tested.  The following table shows the distributions tested since 4.1.1 release:

Important Note – The table below shows the list of distributions that have been tested or reported as ok.  However, given the number of Linux distributions it is impossible to guarantee that our install and/or driver will work in all environments or in all distributions, even if the same underlying kernel, X interface and desktop manager is in use or if a distribution is based on one of the supported distributions. To this end we have selected a number of main stream distributions to regularly test our latest driver and to try and keep the driver current, these being ubuntu, Fedora-Core, Redhat and Suse. Issues with our driver in any other distribution may incur a cost to investigate.

General

General

Calibration issues

Openbox

TWM window manager

Driver background process

Fluxbox window manager

Driver priority

Distribution

ARM based

MeeGo

Ubuntu 8.04, 8.10

and others

Slackware 10

CD Distribution

We believe the best approach is to expand the contents of the linuxupdd.tgz file to the CD ensuring the permissions on the extracted files are preserved.  The end user should then be able to run the installer directly from the CD.  Please test before creating many copies!

Installation

We highly recommend you uninstall any previous UPDD installations, see note 1 below.

This section describes the different installation options and the changes made to the system as part of the installation and covers the following topics:

Installation scripts

UPDD provides a number of installation scripts for most common platforms and these are referenced by the GUI installation program. These scripts provide tailoring of the default package to the specific requirements of a given distribution. Typically this will deal with aspects such as launching the various processes, placing icons on the desktop and so on.

As Linux is very flexible and can be used in many different ways, these scripts are intended for only the most straightforward “out of the box” cases, where a standard Linux installation is performed, with default selections. If you use a non-standard installation you might need to implement a strategy to run the updd software as required. The post installation scripts (*.xns) are provided in the updd installation package and these can be used as a guide. You can of course repackage these to provide a customized UPDD package.

In most cases you will need to launch

                Tbupddwu – the user mode driver

                tblinuxmouse – the user mode X interface module or Virtual Device touch interface

                aidaemon – the daemon process used to detect rotation automatically and adjust calibration.

It is suggested that you refer to the supplied scripts for examples of how to run these as this area is currently subject to change.

GUI installation Procedure
Ensure you have the correct setup file to match your processor’s architecture, being 32 or 64 bit. An error will be issued if you have the incorrect setup file:

Installation of the driver must be performed as the "root user". It is usually possible to run with root privileges by typing command "su root" or preceding the setup command with “kdesu” or “sudo” as described here but we have found on some systems this is not sufficient in which case you must log on at system start as root. Note that on SuSE 10.3 and SLED 11 “sudo” does not allow the installer to work and you must use either “su” or, optionally on SuSE 10.3, “kdesu”. In cases where the installer fails because the installer dialogs do not open try the command ‘Sux’ as this utilises a wrapper around su that transfers a user’s X credentials.

The main installation package is held within the compressed file called linuxupdd.tgz. Copy the file into a directory other than “/opt” or “/” such as a users home directory on the Linux system, change to that directory, then decompress it by using the command  “tar  zxvf  linuxupdd.tgz”.

Important - Do not decompress the software in the root directory or “/opt/” as the install will fail.

To install the software open a terminal window and either use “su” or “kdesu” to become the root user then type “./setup”. Alternatively type “sudo ./setup” and enter your password (not on SuSE10.3 and SLED 11; see note above). This will launch the setup program: Important note: the ‘setup’ program is extracted directly into the extraction directory and is not located in the ./opt/tbupddlx subdirectory just created.

• From the device list dialog select the touch device or, if it is a PnP device, optionally leave the PnP mechanism to pick up the device(s).
• From the distribution list dialog select the distribution script if it is listed.  Select the script that most closely matches your distribution. In no script matches select either “Other” or “Other-Legacy. E.g. If an exact match is listed, say Ubuntu Gusty Gibbon (Ubuntu 7.10), select that. 
• Install scripts can invoke question dialogs, such as ‘OK to enable USB file system’.  Answer these dialogs as appropriate.

Following installation you must reboot the system for the driver to load

If the install fails please refer to the note below to see if there is a solution to your problem:

Installation notes

1.    If installing on a system with UPDD installed and selecting a different installation script from the one used previously it is possible that some components will be installed and running from different locations and this will definitely cause touch failures: e.g.

The RedHat 4.8 script adds an entry to "/etc/gdm/Init/Default" for tblinuxmouse
The RedHat 6.0 script adds an entry to "/etc/X11/xinit/xinitrc.d/runtblinuxmouse.sh

In this case 2 x TBLinuxmouse processes will be running and this will cause touch to fail.

To avoid this issue it is recommended that you uninstall any previous UPDD drivers

2.    The installation procedure is used to install the software for a single touch screen / UPDD supported pointer device.  In a multi-touch screen or pointer device environment invoke the UPDD Console - Hardware dialog to add additional devices after installation.  See the Multi monitor and multi device documentation for further information.

3.    After installation it is a requirement to reboot the system as the graphical subsystem needs to be reloaded for any new drivers to work.

4.    Utility shortcuts (symlinks): If the distribution uses KDE or Gnome windows manager the installation procedure will attempt to** create desktop shortcuts to UPDD utility programs. ** The method used to create the shortcuts may not work in all distributions

When the system has restarted and user log in is complete there are a number of ways to configure the driver.
o - There may be two new icons on the desktop, Console and Calibrate, which can be used to change driver settings and calibrate the touchscreen respectively.
o - On systems where the icons are not seen then a Terminal program should be executed and the user should type “/opt/tbupddlx/upddconsole” to run the Console, and “/opt/tbupddlx/upddcalib” to run the Calibration program.
o - Alternatively manually create Linux shortcuts to the UPDD Console and Calibration program.

If it is preferred that no shortcuts are created on the desktop use the ‘ns’ install parameter to indicate that none are created i.e. “./setup ns”

5.    Root User: Calibration can not be activated when running as a root user. The problem is that when starting an X session, the user is authenticated by X and given permission to connect to the server. When switching users by using "su", the new user no longer has permission to connect to the X server and as a consequence cannot run graphical programs.

6.    UPDD for Linux uses components of the kernel to provide access to the various hardware ports, such as USB, PS/2 and serial ports.  In order to access controller hardware using a distribution that does not implement or mount these sub-systems by default the integrator will need to use the kernel documentation for the distribution in question to enable the appropriate interface.

7.    For serial devices the driver handles the serial device via standard COM port names (/dev/ttySnn) or USB to serial adaptors (/dev/ttyUSBn), so to use a serial device with a different name it is required to create a symbolic link to one of these port types.  In the UPDD serial dropdown you have a choice of COMn for hardware serial ports (maps to /dev/ttysnn-1 (e.g COM1 = TTYS0)) or Adaptorn for virtual serial ports (maps to /dev/ttyUSBn-1 (e.g Adaptor1 = TTYUSB0))  created via a Serial to USB adaptor. See Serial Port notes for more information.

8.    Different drivers exist for 32 and 64 bit processors. Ensure you have the correct build to match your processor otherwise an error will occur. Installing 64 bit on 32 bit processor gives:

$sudo ./setup
     Processing...
     Install failed

9.    The driver software has a number of dependencies, such as the NAS sub system for generating sounds on touch or during calibration. If these are missing the install may fail and display

$sudo ./setup
     Processing...
     Install failed

We have seen this on ubuntu 10.04 LTS. In this case run ‘sudo apt-get install –qq nas’ to install nas and then try the install again.

Manual Install

These instructions are not distribution-specific and locations of directories or files often differ between variants; for this reason use of the automated setup program is strongly recommended and manual installers should anticipate the need to adjust these instructions to account for these differences.

Several instructions will require root access so failed commands may require use of sudo.

Step 1 - Unpacking updd

1. Download linuxupdd.tgz to some dir (e.g. Your home)
2. tar –zxvf /linuxupdd.tgz
3. rm ./setup
4. mv ./opt /
5. cd /opt/tbupddlx (from this point, commands should be run from this location)

Step 2 – Setting attributes and copying files

This stage involves making various files executable and copying and linking them for execution; note that in step 5 the file name changes and that steps 6-8 create links in the run level directories (which may differ in location) to that copied and renamed file. Steps 10-12 may require different directories for the /usr/lib directory if /usr/local/lib does not exist. Finally, step 12 makes use of the ldconfig program bundled with most distributions of linux, if this program is not on your system you may need to download the package libc-bin using yum or apt-get

1. chmod +x S90tbupddlx
2. chmod +x tbcalib
3. chmod +x dcu
4. chmod +x xins
5. cp S90tbupddlx /etc/init.d/tbupdd
6. ln –s /etc/init.d/tbupdd /etc/rc2.d/S90tbupdd
7. ln –s /etc/init.d/tbupdd /etc/rc3.d/S90tbupdd
8. ln –s /etc/init.d/tbupdd /etc/rc4.d/S90tbupdd
9. ln –s libACE.so.5.6.2 libACE-5.6.2.so
10. cp libhbutton32_tb.so /usr/local/lib
11. cp libqt-mt.so.3 /usr/local/lib
12. /sbin/ldconfig /usr/local/lib

Step 3 - Modifying xins script

1. Find / -name .depend.start –print
2. Note the location of the file
3. Open the xins script for edit (using gedit, vi, nano, etc..)
4. Find all four mentions of the location of .depend.start (near the top of the file)
5. Edit the path to match your system setup (Debian 6.0 has the file in etc/init.d/)
6. Save and close xins

For USB/PS2 device

1.       Run ./xins

For Serial device

2. Run ./xins COM<X> 

Step 4 - Setting up the mouse control

Enable one of the X interfaces.

Do not use X11R6 and X11R7 together; if in doubt try the newer X11R7 first and undo changes if necessary.

For X11R7 systems

Locate the Default file for Gnome (Debian location is /etc/gdm3/Init/Default)

1. chmod +x tbxuser.pl
2. chmod +x tblinuxmouse
3. perl tbxuser.pl /etc/gdm3/Init/Default (or your Default file)
4. cp tblinuxmouse /usr/bin

For 32-Bit

5. mv xf86_tbupddlx_drv.so /usr/lib/xorg/modules/input

For 64-Bit

5. mv xf86_tbupddlx_drv.so /usr/lib64/xorg/modules/input

Please note that there is now an alternative to tblinuxmouse with the introduction of a virtual device interface.

For X11R6 systems

1. chmod +x xf86_tbupddlx.o

For 32-Bit

2. mv xf86_tbupddlx.o /usr/X11R6/lib/modules/input

For 64-Bit

2. mv xf86_tbupddlx.o /usr/X11R6/lib64/modules/input

Important note: The xf86_tbupddlx.o interface is a very old kernel mode interface only needed for very old distributions. If enabled on newer distributions you will get an error message due to a deprecated API call:

load /usr/lib/xorg/modules/input/xf86tbupddlx_drv.so: /usr/lib/xorg/modules/input/xf86tbupddlx_drv.so: undefined symbol: xf86GetMotionEvents

Step 5 – Finally

1. mkfifo comReadPipe
2. Restart system
3. Run /opt/tbupddlx/upddconsole to adjust touchscreen settings, test and calibrate

It is important to note that tbupddwu (the user mode driver) has to run under root and that tblinuxmouse (user mode X interface) runs under X.

Manual install - Embedded Linux systems

Given the nature of embedded Linux systems, such as those utilising Tinyx/Kdrive, it is possible that our standard install scripts may not set up the driver requirements correctly, especially the launching of the daemon processes. To this end it is recommended that the individual driver modules be manually installed in these environments.

Basic instructions to manually install and run these programs follow and should be read in conjunction of the full manual install section above. These instructions are for the use of personnel familiar with the Linux command line interface. The commands should be issued by a user logged on as root. We cannot provide detailed instructions without details of the specific target system but we hope these basic instructions will suffice. We can of course answer any specific questions you might have.

-Copy the driver package (linuxupdd.tgz) to the root (“/”) directory on the target system. i.e. “cp <location of tgz>/linuxupdd.tgz /”

-Type the following commands:-

-cd /

-tar  zxvf  linuxupdd.tgz

-rm /setup

-cd /opt/tbupddlx

-touch usermodemouseport

-mkfifo comReadPipe

This will copy the components to the correct locations. You will also need a copy of “libusb-0.1.so.4” which should be copied into the directory “/opt/tbupddlx”. If you don’t have a copy then we can provide it.

You then need to start two daemons: tbupddwu, and tblinuxdaemon. The standard place to start them from is from your “rc” files so that they will run automatically when the system starts. You will also need to set the LD_LIBRARY_PATH environment variable to include “/opt/tbupddlx” in your “rc” script. Note that tbupddwu must be launched before tblinuxdaemon.

To calibrate you need to run the script “/opt/tbupddlx/upddcalib”.

To run the UPDD Console (settings) you need to run the script “/opt/tbupddlx/upddconsole”. Please note - in some embedded systems we have seen that the UPDD Console and it's related test utility (updddraw) does not load due to missing font files. Only when the dependant modules are available will these programs load without error.

Spawned processes

Following installation the following processes should be seen from the command “ps aux | grep tb”:

root      1209  0.0  0.0  11324  1360 ?        S    08:32   0:00 /bin/sh /opt/tbupddlx/startupdd
root      1211  0.0  0.0   3780   296 ?        Ss   08:32   0:00 startpar -f -- tbupdd
root      7477  0.4  0.3  97064  7156 ?        Sl   08:59   0:00 /opt/tbupddlx/tbupddwu
canto     7633  0.0  0.0  25368   944 ?        S    08:59   0:00 /opt/tbupddlx/tblinuxmouse (if using user mode X interface)
canto     7635  0.1  0.3  88720  7076 ?        Sl   08:59   0:00 /opt/tbupddlx/aidaemon

Folder structure

Following installation the following folder structure will have been created/updated on your Linux system:

/opt/tbupddlx/*

Contains the ini file, calib gif files, etc

/usr/local/lib or /usr/lib

libTBApi.so

libhbutton.so

libqt-mt.so.3

libACE.so.5.6.0

Libraries used by the driver

/usr/X11R6/lib/modules/input/xf86_tbupddlx.o

This is the X module for systems using X11R6 based X Window Systems such as Xfree86 and early versions of x.org

/usr/lib/xorg/modules/input/xf86_tbupddlx_drv.so

This is the X module for systems using X11R7 based X Windows Systems such as the latest x.org

/etc/init.d/tbupdd

/etc/rc2.d/S90tbupdd

/etc/rc3.d/S90tbupdd

/etc/rc5.d/S90tbupdd

These automatically load the daemon on system boot

/etc/X11/XF86Config-4 or /etc/X11/XF86Config or /etc/X11/xorg.conf

(depending on X version used)

This pre-existing file gets modified to add a section to load the UPDD XFree86 module 

Virtual Device and multi-touch interface

Introduced in Dec 2012 as part of our multi-touch investigations, UPDD version 5.0.2 build 2372 now creates a virtual touch device that is registered with the system as a multi-touch capable device. This device fits in to the Linux input stack schematic as follows:

The utilisation of the virtual touch device replies on ‘uinput’ support (path /dev/uinput should exist) being part of the Linux kernel and enabled at startup. This function will be part of most recent standard distributions but may need to be added to custom Linux builds. The driver issues the error ‘CLXMousePort failed to open virtualinputpath’ (in a terminal window) if uinput is not available.

Given this is a new interface, currently only proven to work in our own internal tests on a few recent Linux distributions, we have not enabled this interface by default and a command line must be used to enable the interface. Once we are satisfied this is a stable implementation and works as expected this will become the standard, default interface for posting touch data into the kernel.

To utilise this interface, open up a command window and run the commands:

With this enabled, UPDD driver posts all received touch data into the Linux kernel via the virtual touch device rather than the user mode X interface TBlinuxmouse.

Using the lsinput command you can view the UPDD virtual multi-touch input device. On most systems LSinput is not installed by default. Under ubuntu/debian lsinput is part of the input-utils package. To install it, run the command “sudo apt-get install input-utils”. Under other Linux distributions the command for installing LSinput may be different.

Now run ‘sudo lsinput’ to list the devices (note the event number will vary between systems):

/dev/input/event13
   bustype : BUS_VIRTUAL
   vendor  : 0x1
   product : 0x1
   version : 1
   name    : "updd"
   bits ev : EV_SYN EV_KEY EV_ABS

To ensure touch is being handled by the virtual device and not tblinuxmouse you can terminate tblinuxmouse with the command sudo killall tblinuxmouse entered in a Terminal window.

In theory this interface method should satisfy both X and touch event driven services and applications.  The current implementation posts both single and multi-touch input via the multi-touch interface and therefore to utilise this virtual device the Linux distribution must support native multi-touch. The virtual device interface does cater for a different method of posting single touch touches and this may be supported in a future release of our driver to cater for legacy or non multi-touch distributions.

Our tests were conducted with ubuntu 12:10 and the gesture aware Unity Windows Manager (https://wiki.ubuntu.com/Multitouch). In this distribution, using kernel 3.5, device test software showed the touch device and reported single and multi-touch input and both X and Unity gestures worked as expected.

Testing in Suse 12.2, kernel 3.4, the supplied test software did not show single or multi-touch input albeit the single touch X interface worked well which implies that this interface is likely to be working in this distribution.

There are utilities, such as evtest and mtdev-test, which can be used to show certain device information handled by the multi-touch device.

It is important to acknowledge that the virtual device implements a solution for native multi-touch support not MPX. MPX provides multiple independent pointers (mouse cursors) at the windowing system level. Please contact us if you require MPX support.

Calibration

After the restart and if using the KDE or Gnome window manager, there should be an icon on the desktop to calibrate (unless the installer requested no shortcuts):

If using a different window manager, open up a shell and type:-

/opt/tbupddlx/upddcalib

or

cd /opt/tbupddlx

./upddcalib

or alternatively create a link to it using the window manager.

To calibrate, double click the calibration icon on the desktop or run the calibration program and touch the calibration crosses, or arrows, as they appear. Important note: If the calibration screen does not cover the full desktop area see calibration notes above. Full calibration procedure information can be found in the Calibration document.

Calibration can be performed in any screen resolution and the calibration data held is relative to the screen resolution. However, if the screen resolution is changed then a new calibration will be required as currently we do not automatically track screen resolution changes.

Driver/Controller settings

The UPDD Console defines the functionality of the pointer device(s) and the UPDD driver environment.

If using the KDE or Gnome window manager, there should be an icon on the desktop to invoke the UPDD Console (unless the installer requested no shortcuts).

If using a different window manager, open up a shell and type:-

/opt/tbupddlx/upddconsole

or

cd /opt/tbupddlx

./upddconsole

or alternatively create a link to it using the window manager.

To configure the UPDD settings invoke the UPDD Console program and change the setting as required.

See the UPDD Console documentation and on-line help for further information.

All settings, including calibration data, are held in the UPDD settings file.

Serial port notes

Change serial port connection

The UPDD Console - Hardware tab allows the COM port name to be reassigned after installation.

Standard serial ports

If using a standard serial port, Select Com1, Com2 etc in the COM port selector. Serial ports should be registered in the system as ttySn which is mapped to our driver to COMn+1 (e.g. COM1 = ttyS0)

Serial to USB adaptors

If using a serial to USB adaptor, select Adaptor 1, Adaptor 2, etc in the COM port selector. This has only been tested with the Keyspan adaptors so far but the Linux documentation states that the interface is the same for all serial adaptors; hence UPDD should work for all serial/USB adaptors. Serial to USB adaptors should be registered within the system as ttyUSBn which is mapped by our driver to Adaptor n+1. (e.g Adaptor1 = ttyUSB0)

Serial port reassignment

The driver handles serial devices via standard COM port names (/dev/ttySnn) or USB to serial adaptors (/dev/ttyUSBn), so to use a serial device with a different name it is required to create a symbolic link to one of these port types.

Example: Assuming you have a serial port referenced as ttyC1P3 to be reassigned. You need to open a terminal with root privileges and type the following:

ln -s /dev/ttyC1P3 /dev/ttyUSB0 (for Adaptor 1)

or

ln -s /dev/ttyC1P3 /dev/ttyS0 (for com port 1)

You will then need to open up the UPDD Console and change the COM port for your device to "Adaptor 1" or “Com 1”.

Serial port testing

Should the serial port connection not be working there are a number of procedures to follow to help identify the problem as described in the knowledge base article here.

Serial port issues

One customer reported that the serial touch screen stopped working after the initial boot.  Further investigations showed that the root cause was the Bluetooth manager using the modem-manager to close all serial ports even though they had no Bluetooth devices on their system!!!

Uninstall

Automatic (4.1.1 - 26^th Sept 2008 onwards)

Note: The automated uninstall will only fully remove installations that have been installed from this build and later. If installing this build over an earlier build and then uninstalling using the “uninstall” program the changes to /etc/X11/xorg.conf will not be removed correctly. In the case of installing this build on a system which has had another build on it, the best scenario is to manually remove the old software and then install the new.

Removal of the driver must be performed as the "root" user. It is usually possible to "become" the root user by typing command "su root" or preceding the setup command with “kdesu” or “sudo”, but we have found on some systems this is not sufficient in which case you must log on at system start as root. Note that on SuSE 10.3 and SLED 11 “sudo” does not allow the uninstaller to work and you must use either “su” or, optionally on SuSE 10.3, “kdesu”.

To uninstall the software open a terminal window and either use “su” or “kdesu” to become the root user then type “/opt/tbupddlx/uninstall”. Alternatively type “sudo /opt/tbupddlx/uninstall” and enter your password (not on SuSE 10.3 and SLED 11; see note above). This will launch the uninstall program:

To continue and remove the software click on “Uninstall”. To cancel, click “Cancel” and the system will remain unmodified.

Manual Uninstall

Type the following commands being careful to use the same case and spacing.

su

*Enter the root password*

rm -rf /tbupddlx *If this is mistyped, the whole system could be wiped.

rm /usr/X11R6/lib/modules/input/xf86_tbupddlx.o

For Systems using X11R6

rm /usr/X11R6/lib/modules/input/xf86_tbupddlx.o

For Systems using X11R7

rm /usr/lib/xorg/modules/input/xf86_tbupddlx_drv.so

rm /etc/rc.d/init.d/tbupddlx

rm /etc/rc.d/rc2.d/S90tbupddlx

rm /etc/rc.d/rc3.d/S90tbupddlx

rm /etc/rc.d/rc5.d/S90tbupddlx

Edit the file "/etc/X11/XF86Config-4" for Xfree86, or “/etc/X11/xorg.conf” for x.org and remove the following section:-

Section "InputDevice""

   Identifier "Updd0"

   Driver "xf86_tbupddlx"

   Option "Device" "/tbupddlx/comReadPipe"

EndSection

In the section that begins with:-

Section "ServerLayout"

Remove the line:-

InputDevice "Updd0" "SendCoreEvents"

Multi-monitor and multi-device support

Support for multiple monitors was added in UPDD Version 4.0.4 and is covered in full in the multi-monitor and device document, Linux section.

Display rotation considerations

Linux supports rotated video modes for supported video cards under both Xfree86 and X.org. UPDD will work with rotated video and this is explained in detail in the separate rotate documentation.

Display resolution / calibration considerations

The calibration mapping is based on the screen resolution setting at the time of calibration so if the resolution is changed the calibration will be inaccurate. To cater for this you will need to manually recalibrate after changing video resolution.

Future releases of the driver may well introduce a daemon process to automatically monitor video resolution and adjust automatically but until such times as this is available manual intervention is required.

Mouse settings

Double click capabilities are affected by the system’s Mouse settings. To achieve a double click using the pointer device these settings need to cater for the type of device in use. A touch screen may well require different settings to that required by a mouse. The main setting that affects the ability to double click is the double click speed. If this is set too fast it may be impossible to produce a double click. Ensure this is set to an appropriate value in the mouse settings to allow for double clicks via a stylus. In this example the mouse settings screen is from the KDE Control Centre. Other window managers will have different ways of configuring the settings.

The UPDD Console, Click Mode dialog, System Mouse settings will invoke the Mouse settings for KDE and Gnome desktops, as shown in the following example:

Touch Utilities

Virtual Keyboards

A number of Virtual keyboards are available on the Web for Linux as detailed in the UPDD Virtual keyboard documentation.

Mouse Cursor

At the time of writing we are not aware of any specific end user utility to change the mouse cursor or turn it on/off.  Please contact us if you find such a suitable utility that we can document for other users.

Current Limitations

UPDD was originally developed for Windows and has since been ported to other OS. Not all features have been ported to Linux, they include:

• Dynamic detection of system language.
• Serial port auto-detection
• Interactive touch – visual notification of right click count down
• Anchor mouse function
• Light pen calibration (the white lines on black mode)
• Toolbar actions
• Extensions

Contact

For further information or technical assistance please email the technical support team at technical@touch-base.com