Installation

Options

General notes

Platform notes

Calibration

UPDD Version 4 - Software installation and general notes

Version 4.0.2

1^st October 2006

Welcome to UPDD version 4. Although the underlying driver is fundamentally the same as the version 3 driver this release addresses the issue of cross-platform compatibility of the driver’s utility programs therefore the same utility programs now run under all OS. A new calibration program has also been written to remove java dependency under Mac OS X and Linux. Over the coming months we will also be enabling a number of embedded touch utilities that have been written but are not sufficiently stable for release.

Not all version 4 programs are available in this early release as it has been necessary to release this driver to deliver recent development that has only been implemented in this version. Version 4.0.0 was the first cut for Windows and version 4.0.2 added support for Mac Intel processors along with the previously supported Mac Power PC processor. Version 4.0.4 will support Linux and 4.0.6 will offer some useful touch utilities.

The UPDD suite of utility programs are as follows:

Program

Status

Description

User Console

First release

Driver’s control program aimed at general, non technical, users

Calibration

First release

New calibration program

Extensions

Under test

Touch utilities, to be released under 4.0.6

Activator

Under development

Quick access utility to touch related functions

Advanced Console

Under development

Advanced driver and device settings for technical users

SDK assistance

Under development

UPDD SDK API programmers guide and example code

Language files

First release

Common language files are under construction and will be release as and when available. A completed language file will allow all utility programs to be localized to the language of the system.

The installation program will install the driver, calibration program and the new UPDD Console. It will normally be delivered by email. Touch-Base utilises virus detection software on all of our systems but recipients of the software should pass the files thought their own virus checking software before proceeding with installation.

Limitations

Release Status

This software is beta software and therefore under development and test. It has been shipped earlier than appropriate to cater for a number of users requiring support for the new Mac Intel processors. In the coming weeks we will be working on the known problems and any issues reported by beta testers and users. The UPDD Console settings and calibration programs are new. Most of the known issues are cosmetic or functional issues with the settings program. Most of the toolbar options in the settings programs are related to Windows functionality and these functions are being tailored to the similar functions in the various OSes. Unless you are using toolbars in Windows it is recommended you do not use any of the toolbar functions.

We hope to be in a position to release the next beta version at the end of April and production software very soon after.

Evaluation software

If you are installing evaluation software then mouse clicks will be inactive after you have touched 100 times. A further 100 clicks are available after each reboot or calibration. This restriction is removed on licensed software.

Deliverables

For standard desktop Windows the software will be delivered in the file UPDD.ZIP to avoid the rejection by many mail servers of .exe files. If the zip file is password protected the password is touchbase. UPDD will be supplied as a single setup.exe program. It can also be supplied as multiple files – setup.exe, maindir1.cab and sysdir1.cab files – created to allow installation from diskettes.

For Mac OS X the program is delivered as a single file macx.sit. We are aware this is an old Mac OS X compressed format but we use a Windows system to create the drivers and it is currently easier to create .sit files than the new format in our Windows application but we hope in a future release to deliver in the new format – sorry for any inconvenience this may cause.

We are not currently able to create a universal driver that supports both Power PC and Intel processors so we are shipping separate drivers. Please make sure you have the appropriate install for the processor.

Version 4 not yet available. Contact Touch-Base for version 3 and a separate installation guide.

For Windows CE UPDD the software can only be supplied in component form for Win CE 3.x through 5.x (.Net) with full embedding instructions. See Win CE embedded documentation.

Under Windows XPe the standard Windows installation files can be used on XPe systems. If UPDD is installed on an XPe system using the standard setup.exe file, typically to test the driver prior to embedding, UPDD installation has certain dependencies that need to be present for successful installation. One of the less obvious dependencies is the use of RegEdit during install to set up the registry. If RegEdit is not present all selections and dropdowns are blank.

If you are creating an XPe system from embedded components UPDD can be supplied in component form with full embedded instructions. See Win XPe embedded documentation.

UPDD is available for VxWorks real-time operating system. See VxWorks Integration guide.

System Requirements

Supports serial, USB and PS/2 devices. For serial and PS/2 devices Win 95 thro XP. For USB devices Win 98, 2000 and XP. Third party USB stacks are available for Windows NT but driver changes are required so this is not currently supported. We do not currently support Windows 64 bit processors.

Winzip or equivalent is required to decompress the software.

C++ run-time library shipped as standard with Mac OS x 10.4 (Mac Intel support started at OS X 10.4). Please contact Touch-Base for a separate 10.1, 10.2 or 10.3 (Power PC) driver if required. A user has installed with 10.3.9 so it is possible that the C++ libraries shipped with later versions of 10.3. When the libraries are missing the set up program bounces in the dock. Running setup from a terminal command line shows the actual system error which is not seen when running it from the desktop.

Supports serial and USB.

Stuffit is required to decompress the .sit file. This utility does not ship with latest Mac OS and can be downloaded from www.apple.com/downloads/macosx/system_disk_utilities/stuffitexpander.html. If using Mac Intel we highly recommend you use Stuffit 10.0.x (at the time of writing the link above is pointing to 10.0.2) 10.1 beta or above as this is the Intel native version of StuffIt. See http://www.stuffit.com/mac/expander/universalbeta.html for more details.

A few customers reported that a stuffit error was reported (using Stuffit 10.x) when trying to unpack the UPDD.sit file. The problem was overcome when they unchecked the preference “Continue to expand if possible”.

We are not currently able to create a universal driver that supports both Power PC and Intel processors so we are shipping separate drivers. Please make sure you have the appropriate driver for the processor.

Supports serial, USB and PS/2 devices. The driver is a user mode application an as such is not linked to a given kernel release. The driver has been tested under Linux kernel 2.4.x and 2.6.x.

The driver supports the XF86config-4, XF86config or Xorg.conf graphical interfaces. If not using a graphics interface the driver will load and work without X allowing for application API interface to driver. Window Manager issues are discussed further in the Linux specific documentation.

Unzip is required to decompress the software.

Many Linux distributions have been tested and found to work fine as long as they conform to the above system requirements. However, we are aware of some Linux distributions that have some issues and these are discussed in detail in the Linux specific documentation. Should the driver not work on your Linux distribution please contact Touch-Base and we will investigate further – often it is subtle file structure differences.

CD Distribution

The setup.exe program is placed on the CD along with a autorun.inf file (which ships with the driver). Insert the CD and the autorun file automatically invokes the setup.exe program. The autorun.inf file contains:

[autorun]

OPEN=.\Setup.exe

The contents of the .sit file are placed on the CD under directory structure /macx.pkg/ ensuring case of the files names is preserved. Insert the CD and it is automounted to the desktop. Double click the CD icon. This is as close as you get to auto-run with the MAC.

To follow.

Installation Procedures

Expand the .ZIP file and extract the setup.exe program. Double click the setup.exe program and select the controller from the list of supported controllers in this build. If you select a serial controller you will be shown a fixed list of serial ports to select the desired port. If the port is not listed this can be entered from the UPDD Console after installation.

Following installation the UPDD Console and calibration utilities will be placed in the UPDD applications folder c:\program files\updd, accessible via the Windows Program Manager, UPDD entry.

Copy the .sit file to your desktop. Double click the desktop icon - stuffit will run and create the setup program on the desktop. Double click the setup program and select the controller from the list of supported controllers in this build.

VERY IMPORTANT NOTES

1) Make sure the file created is called setup. If a previous setup file existed on the desktop the file created will be called setup.1 and this cannot be used to install the software.

2) If the list of controllers is empty DO NOT CONTINUE. Stuffit has failed to unstuff all the required files and the setup program has failed to locate its configuration file. Later versions of the software will issue the following message

Delete setup and use a later version of StuffIt. See System Requirements above.

If you select a serial controller you will be shown a list of serial ports found on your system, as in this example a virtual serial port created by a serial to USB adaptor and driver

If you are installing on a system that does not currently have a serial port installed or wish to define the port at a later time then select the None option. If your serial port is not listed, select None and then refer to the serial port section in the platform specific documents.

Following installation the software will be placed in /TBUPDDMX folder, with UPDD Console and calibration utilities shortcuts placed in the Utilities folder. Shortcut icons will also be placed on the desktop.

Important note: If installing on a Power PC and UPDD V3 is installed it is important that the previous version be uninstalled as per the uninstall instructions in the version 3 user guide.

To follow.

Installation Notes

Serial ports

Serial to USB adaptors: If you are using a serial device via a serial to USB adaptor (needed if the hardware does not have a native serial port) make sure the adaptor has a relevant OS adaptor driver to create the virtual serial port in the system. We use adaptors from Keyspan. Before installing the UPDD serial driver you need to ensure you can identify the virtual serial port in the system. See further serial port notes in platform specific documents.

Changing port: Following installation the UPDD Console – hardware dialog can be used to change or define the serial port in use.

Auto detection and Auto selection of serial controllers: Many serial devices can receive and respond to controller commands. These commands can be set up using UPDD’s macro language and the macro can be invoked automatically as part of UPDD’s controller initialisation procedure. See UPDD Advanced Console.

An example of a UPDD macro command is as follows:

[HEX]

01 55 FF

[ACK 1000]55 FF[END]

In this example UPDD will send 01 55 FF to the controller. If the controller is connected and functioning correctly it is expected to return 55 FF within 1000ms.

If a UPDD macro contains an [ACK] statement then the driver is able to automatically locate serially connected controllers. If an [ACK] statement has been defined for a controller then the install and serial port hardware dialog will show Auto-Detect and Auto-Select check boxes.

Auto-Detect - If this function is enabled then all serial ports are tested to locate the controller. The defined serial port is the first port tested. This should only be selected if it is known that there are no other serially connected devices that will not be unduly affected by the receipt of the macro command sequence.

Auto-Select - If this function is enabled then the defined serial port is the only port tested to locate the controller. This function is typically used when a customer may have more than one type of pointer device connected to the port and the driver is expected to automatically determine the type connected. In this scenario all possible controller types will be defined in UPDD but they will all be associated to the same port.

General Notes

1. Unless otherwise informed it should not be necessary to reboot the system after installation except when installing the Windows 64 bit driver. The Windows 64 bit driver requires a reboot after installation.

2. For USB HID devices it is recommended that the device is first connected to the system prior to installation. This allows the HID driver to load and take control of the device. During the installation procedure UPDD will register as the controller’s driver and take control of the device from HID. Once installed UPDD will then be associated with the device. Under Windows, should another driver, including HID, ever take control there is an option in the UPDD Console, Hardware dialog, Redetect PnP device to re-associate the device with UPDD.

3. 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.

Installation Options – Windows only

Silent install mode: Running setup –s indicates that no UPDD install dialogs are to be shown. Default settings for the touch controller are used unless a clone file is found in which case the settings in the clone file are used.

Silent reinstall mode: The UPDD installer also supports a silent reinstall option (Setup –sr). The silent reinstall upgrades all software components but leaves all previous settings unchanged.

Clone settings: Once installed the driver can be configured via the UPDD Console. These setting can be replicated (cloned) to a file in the UPDD Console – Status dialog - Dump settings option. This file will create a .reg file. If this file is placed within a sub-folder called UPDD_EXT and renamed to upddclon.reg the install process will use the settings defined in the clone file.

Make INF file: Running Setup MAKEINF can be used to create an INF file to allow for an INF style installation. See separate WHQL documentation for further information.

Signed drivers – Windows only

Windows 2000 and XP will automatically show a warning dialog if an unsigned driver is installed. Some UPDD installs, that are installing an unsigned driver, have been configured to automatically handle the warning dialog. This results in a ‘dialog flash’ during install. Other UPDD installs have been configured to not handle the warning dialog, leaving the user to handle the dialog, as seen below;

Windows 2000 and XP can be configured to not allow the installation of unsigned drivers. Drivers have been identified as one of the major causes for the past instability of Windows. Drivers can be submitted to Microsoft to be approved and ‘digitally signed’ to show that they have passed specific driver acceptance tests. UPDD cannot on its own be submitted for approval. It can only be approved with the pointer device. Where UPDD has been submitted to Microsoft with appropriate hardware it has passed all tests and been approved and digitally signed. You may or may not be installing a signed version of this driver but you should not be unduly concerned if you are installing an unsigned version. For more information the WHQL and digital signature documentation.

Platform Specific Installation notes

Inevitably there are some issues that are platform specific and these issues are covered in platform specific documents distributed with this installation document. The files are supplied separately and are called WindowsPlatformNotes, MacOSXPlatformNotes and LinuxPlatformNotes.

Calibration

Calibration is a procedure used to align the pointer device with the graphically display area or desktop segment. When using the pointer device the mouse cursor should normally position itself under the stylus when it is in contact with the pointer device. If this is not the case then calibration will be required and this is described in full in the Calibration document. The UPDD driver also supports Toolbars, which also require calibrating, and this is covered in full in a separate Toolbar document.

Driver settings – the UPDD Console

This program is used to adjust the driver and device settings.

For Windows, the console can be invoked via the UPDD program group, settings entry or the system tray menu.

For Mac and Linux locate the UPDD Console program or double click the Console icon on the desktop.

The new look console is shown below and has three main users areas; the device display/selection, the function selection and the display area which is described in detail in the on-line help files installed with the driver.

For most systems it is unlikely that any changes will need to be made to the driver configuration as the default settings are optimized for best performance. Great care should be made in changing any of these settings as they may have an adverse effect on the performance of the pointer device.

All UPDD settings are stored in a ‘registry tree’ structure. In Windows this is stored in the registry. On other operating systems this is stored in a file called TBUPDD.reg. All settings and there meanings/functions are described in the Advanced technical console. The active settings are found in the following branch:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{…}\1

Calibration information is also held in this file unless stored in the controller’s EEPROM. The settings held in this file can be changed manually or the more common settings can be adjusted via the UPDD Console.

API calls are made to the driver to read and write the settings and in some UPDD Console dialogs there are many settings to be accessed before the dialog is displayed. In some cases, especially slow systems, there is a noticeable delay whilst waiting for the dialog to be shown.

The UPDD Console functions are described in the UPDD Console on-line help, as shown below.

On-line help

The Help option can be used at any time to invoke the context sensitive on-line help.

Mouse emulation

Most pointer devices emulate the actions of the mouse; cursor movement, left click, right click, double clicks etc. These actions have to be derived from the events generated from the pointer device. In the case of a touch screen these events are initial touch, movement, stationary and last touch.

The driver implements a number of different emulation methods to cater for the different ways mouse emulation is likely to be used. These emulation methods are shown in the UPDD Console, Click Mode dialog and described in full in the on-line help.

Emulation mode	Initial touch	Movement	Stationary for short period	Last touch	Default Primary Event	Default Secondary Event	UPDD Version 3 reference
Click and drag	Pen down	Move with pen down	None	Pen up	Left click	Right click	Touchdown Left / Touchdown Right
Drag then click	None	Move	None	Pen down/up	Left click	Right click	Liftoff Left / Touchdown Right
Point and click	Pen down	off	None	Pen up	Left click	Right click	N/A
Interactive Touch	Left Pen down	Move with pen down	Left Pen up Right pen down / up	Pen up or no action	Fixed	N/A	Interactive Touch

When the stylus is used, it will, by default, perform its primary event click emulation as shown above. However, in some circumstances it is required to perform the associated secondary event and this is achieved by using the Event Selector to switch between Primary and Secondary events.

Event Selector

The Event Selector is currently Windows only but is being rewritten to be cross platform compatible.

Under Windows the desktop Event Selector can be invoked in various ways:

· Single click the UPDD System Tray Utility and select ‘Event Selector’ from the menu items;

· Directly calling the Event Selector from an application, desktop icon or, as shown below, the Windows Program Manager;

Switching Events

Clicking on either of the event selectors will toggle between the primary (left) and secondary (right) action. By default, the Event Selector automatically switches back to the primary setting after a single secondary action has been performed..

Event Selector Settings

Event Selector settings can be changed in the Event Selector menu. The menu can be viewed by clicking on the title bar mouse icon on the desktop Event Selector:

One hit: Indicates if the Event Selector automatically switches to the Primary setting after a single secondary use.

Icon: Indicates the size of the mouse icon displayed in the desktop event selector.

Text mode: Indicates that text be shown instead of a mouse icon.

Manual Installation Instructions

To follow.

Uninstall

Automatically

The driver can be removed via the Windows Control Panel, Add/Remove Programs option:

Select the ‘Universal Pointer Device Driver’ entry in the Add/Remove Programs dialog.

Under development

Manually

To uninstall the driver, the “root” account must be activated on the system and you must know the root password.

Perform the following steps to uninstall the driver:-

Start a “Terminal” session and login as root:

Open a “Finder” window
Click “Applications” at the top (10.2.x) or at the side (10.3.x), or navigate to the “Applications” directory on the system disk
Open the “Utilities” folder
Double click “Terminal”
Type “su”

Enter the root password that was selected when the Root user was activated.

Type “rm –r /tbupddmx”

Type “cd /System/Library/Extensions”

Type “rm –r tbupddmxhid.kext”

Type “cd /Library/StartupItems”

Type “rm –r TBUPDDMX

Type “exit”

Close the terminal

** It is very important that the commands are entered exactly as above (same capitalisation, no spaces in the filenames) otherwise other data could be removed from the hard drive.

Controller specific notes

3M SCXXX range

The 3M range of controllers commonly known as the SC5 (SC40n, SC50n, SC80n) may need initialising before they generate the full range of touch coordinates. With un-initialised controllers, coordinates are not generated across the entire screen which can result in dead touch areas at the edges. If you are using these controllers and find that, after calibration, there is no reaction to touch around the edges then either use 3 point calibration in UPDD Calibration and check the EEprom check box (this hardware initialises the controller and stores calibration in the controller’s EEprom) or run the Windows initialisation program available on the 3M web site at http://www.3m.com/3MtouchSystems/downloads/drivers/HIDCalibUtility.zip and then recalibrate with the UPDD calibration utility.

OneTouch USB

The OneTouch USB controller is actually an onboard Prolific PL2320 serial to USB adaptor so requires an appropriate driver to create a virtual serial port. For Mac OS X, OneTouch sent us file md_pl2303H_HX_X_dmg_v1.1.ob1.zip for testing which worked fine. Once this driver is installed use the OneTouch UPDD serial driver to support the device.

Zytronics X-Y

A UPDD Console firmware dialog is enabled if this controller is configured. If EEPROM storage is used the calibration data is stored in EEPROM and must be retrieved with the TBcalib command ‘tbcalib eeprom’ at system startup. This is mainly used for embedded systems. See EEPROM documentation for more details.

Software Development Kit and Application Programming Interface

UPDD supports an application program interface (API) on all supported platforms. This allows user written programs to interact directly with the driver or pointer device handled by UPDD. It is assumed that the reader is familiar with the various functions and parameters of TBUPDD, since that information is not duplicated here.

The API calls work exactly the same in all environments except obvious operating system specific calls.

Registry get and set setting calls work exactly the same in all environments. In Windows they access the registry whereas in other operating systems they access the files holding the registry structure.

Depending on which operating system and client language is used the user has a choice of linking to the API statically or dynamically. For example on Windows both static and dynamic libraries are available, however Visual Basic only supports dynamic linking.

Depending on the OS in use the following files implement the UPDD API:

and

TBapi.h

TBbundle.h

Tbapi.lib

Tbapi.dll

Tbapi.bas *

Tbbundle.bas *

function declarations.

contains bundle-specific data (file supplied with driver).

statically linked implementation.

dynamically linked implementation.

contains DLL function declarations, constants and data types and helper functions for VB.

contains VB bundle specific data.

* both these files are required in a VB project

TBapi.h

TBbundle.h

lTBApi_[proc].lib

function declarations.

contains bundle-specific data (file supplied with driver).

statically linked implementation for a given target processor

[Proc] = x86, mips, arm etc

TBapi.h

TBbundle.h

libTBApi.a

function declarations.

contains bundle-specific data (file supplied with driver).

statically linked implementation.

TBapi.h

TBbundle.h

libTBApi.so

function declarations.

contains bundle-specific data (file supplied with driver).

dynamically linked implementation.

Java applications will need to use the Java Native Interface (JNI). This can link using either the DLL or the static library. A partial JNI interface is available, but not yet supported - this is supplied in source form to simplify JNI implementation.

Full details of the version 4 SDK and API are currently being documented in the advanced technical SDK dialog. Please contact Touch-Base if you require further details in the interim period.

Software History

Release

Date

Description

4.0.00B

15^th Jan 06

First release of version 4. Supports Windows only. Uses old version 3 calibration program. Release for initial customer feedback

4.0.00P

1^st Feb 06

Production release required by key customer

4.0.02B

28^th Apr 06

Early Beta release to support Mac Intel processor. Also supports Mac Power PC processor. New calibration program.

4.0.02B

15^th May 06

A number of cosmetic changes

Fixed calibration issue if screen orientated during calibration

Fix reinstall issue. Installing on top of previous install could cause problems

Software Differences

Although it is our aim to make the software as compatible as possible it is not always possible to implement all functions across all platforms, either because of time / resource constraints, inappropriateness or incompatibility. This section documents features that have not been implemented in a specific platform.

All documented features supported.

Dynamic detection of system language.

Serial port auto-detection

Interactive touch – visual notification of right click count down

Anchor mouse function

Multi-monitor support only supports monitors defined left to right in the system

No sound on touch or during calibration

Dynamic detection of system language.

Serial port auto-detection

Interactive touch – visual notification of right click count down

Anchor mouse function

Multi-monitor support only supports monitors defined left to right in the system

No sound on touch or during calibration

Contact

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