Revision 1.8, 12^th May 2008

Mac OS X Installation

Classic Mode

Notes

Install

Welcome to UPDD Mac OS X platform specific installation instructions and related notes.

These notes should be followed to install the UPDD pointer device driver on Mac OS X platforms utilising 10.2 and above. Drivers for 10.0 and 10.1 are available on request.

Driver build history

Release	Date	Change
4.0.0	April 2006	Initial release for Mac Intel
4.0.2	Aug 2006	General bug fixes and stabilisation of new system and Mac Power PC
4.0.4	April 2007	Multi-Monitor support and device binding
	July 2007	System Preference entry plus improved binding in multiple touch devices
4.0.6	Nov 2007	Mac OS X 10.5 (Leopard) support added
4.1.1	Jan 2007	Improved binding, PnP device support, mouse interface

Deliverables

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.

The software 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.

The UPDD software comprises:

Setup.app The installation program

tbbundle.h The UPDD header files defining the API calls to the driver if writing applications to interface with the driver

System Requirements

Component	Reason
C++ run-time library	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.
Stuffit	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 or later. See http://www.stuffit.com/mac/expander/ 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”.
Access to TCP IP port 4141	The driver utilizes the ACE communications library for process to process connection to transfer data to the driver. The driver requires access to TCP IP port 4141 for internal computer processing only. Depending on your system configuration, particularly firewall settings, you may be asked to accept incoming connections when you install the driver.

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.

CD Distribution

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.

Classic Mode issues

In some instances, with classic mode applications the click emulation is not as good as expected, especially with quick taps on the touch screen. We changed the way our driver was internally handling OS mouse interfacing when in classic mode but unfortunately we could not fine a solution that worked well for both modes so we have introduced a new setting called ‘Support Classic Mode’. Try this setting in the UPDD Console – Properties page if classic mode applications do not respond as expected.

Installation Notes

General

1. Mac purist will note that the software does not follow some Mac development standards. The common issues raised are:

Using StuffIt to unpack as this is an old decompression method. Unfortunately the software is created in a Windows environment and creates a compressed file that only StuffIt can handle. We hope to address this in a future release
Placing 'aliases' on the desktop. These are placed on the desktop for convenience to allow instant access to calibration and the driver’s settings. Can easily be dragged to trash.
Creating a directory (/tbupddmx) off the root folder. This is a temporary requirement in that this version of the driver needs access to a known location. This will be addressed at some point in the future.
Documenting that the root account is used to perform a manual uninstall. Root is required to uninstall kernel extensions used by the driver for HID devices. The proposed 4.1.2 uninstaller will avoid this requirement.

2. One customer 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”.

3. MAC OS X release 10.3.5 has a bug and will not recognise more than one USB controller of the same type unless they are plugged into separate USB hubs.

4. A customer reported that an HID compatible touch USB controller was still controlled by the HID driver after installing the UPDD driver when using Tiger version 10.4.0. Upgrading to 10.4.2 overcame this issue so we have not investigated further as we believe most users will be on 10.4.1 or above or be able to upgrade.

Very Important Notes

1) 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.

2) Reinstalling considerations when installing version 4.1.1 and above:

Ensure all old UPDD desktop icons (if they exist) are dragged to trash – Console, Calibration, Macx.sit and setup program.

a) Installing on a Power PC and UPDD V3 was previously installed
Open up a Terminal window (Utilities, Terminal) and type “sudo killall tbupddmx” – you will need to enter your mac password. It is advisable to also drag the /tbupddmx folder under the root folder to the trash.

b) UPDD 4.0.x previously installed
Open up a Terminal window (Utilities, Terminal) and type “sudo killall tbupddmx” – you will need to enter your mac password. It is advisable to also drag the /tbupddmx folder under the root folder to the trash.

c) UPDD 4.1.0 previously installed
Open up a Terminal window (Utilities, Terminal) and type “sudo killall tbupddwu” – you will need to enter your mac password. It is advisable to also drag the /tbupddmx folder under the root folder to the trash.

d) UPDD 4.1.1 and above previously installed
Reinstallation is OK as the install program calls a UPDD API call to stop the driver thus allowing the new driver to be successfully installed and invoked.

e) After install failure and the setup icon bounces in the dock but does not show the installation screen
Drag to trash the /tbupddmx folder located on the root of the hard drive and reboot the system and retry the install.

See uninstall instructions for further details.

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

4) If, during install, 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.

5) Installs have not always been successful on systems with inconsistent permissions. If unresolved install issues occur please load up the Disk Utility from the utilities folder, select the hard drive and select Repair Disk Permissions and try the install again.

6) 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 below.

Installation Procedures

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 icon, enter your Mac users password and the controller selection dialog will be shown (with version 4.1.x it can take up to 20 seconds before the install dialog appears due to the large size of some of the libraries embedded in the setup that need to be extracted):

Select the controller from the list of controllers shown in your version and wait for installation to complete.

Following installation the software will be placed in /TBUPDDMX folder, with UPDD Console and calibration utilities aliases placed in the Utilities folder and, for convenience, also on the desktop. With 4.1.x and above the UPDD Console will automatically list all USB touch devices supported by the driver and plugged into the system.

Calibration

After installation, the Calibrate icon appears on the desktop and in the Utilities folder.

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.

Driver settings – the UPDD Console

After installation, the UPDD settings icon appears on the desktop, in the Utilities folder and in the System Preferences, Other section.

The driver and device settings can be adjusted with the UPDD Console program and is described in full in the UPDD Console documentation.

Serial port issues

The UPDD Console, Hardware tab allows the serial port name to be changed after installation, if required. E.g.

Use the dropdown to select the name of the serial port.

If your serial port is not listed, read on.

Serial port identification and testing

We use a file called serial.dat to define the structure of valid native and virtual com ports available on a Mac. If your serial port is not listed then the file structure is not defined in the serial.dat file.

Serial port names can be found in the /dev folder (as seen from a Terminal window’s LS command).

In the above example a virtual serial port is listed as cu.KeySerial1. This is a Keyspan serial to usb adaptor.

If you have a serial port entry that is not being shown in the serial port dropdown you need to modify serial.dat file, adding an entry that reflects the port structure seen. Typical entries in serial.dat that define the serial ports we have encountered this far are:

^cu\.USA*

^cu\.KeySerial* - This entry relates to the serial port listed above

^cu\.usbserial*

^tty\.usb*

The file is write protected in a write protected folder. In this instance it is normally easier to take a copy to another folder, use “CHMOD 777 serial.dat” command to modify permissions, update the file with textedit and then “sudo cp serial.dat /tbupddmx” to copy back the updated file.

Please let us know what serial port structure you have so we can update the master file for future use.

A Universal Binary (a driver that runs on both Intel and Power PC Macs) Keyspan USB serial adaptor Mac OS X driver is available on the Keyspan web site, downloads page. Keyspan drivers also install a utility program which will list the name of the com port. In the following example the utility Keyspan Serial Assistant is invoked to list the port name:

The OS adds a number to this name to give each adaptor a unique identifier, 1 for the first port, 2 for the second etc

If you need to use a Serial to USB adaptor, only those supplied with a Mac OS X driver will work. At the time of writing (Sept 2005) Belkin and PalmConnect do not have such drivers. Keyspan and adaptors using the Prolific chipset (branded by iogear and dynex amongst others) do have such drivers. One customer noted that the Prolific drivers are available in .dmg and .hex format and for him only the .hex file worked. He also reported that the adaptor must be connected to the Mac during install. The com port name given to many of these adaptors in the Mac OS X system is /dev/cu.usbserial.

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.

Uninstall

Currently you can only manually uninstall. An automatic uninstall will be available with UPDD 4.1.x. Sorry for any inconvenience this may cause.

To uninstall the driver requires the Root User account to be activated as it is necessary to login to this account to uninstall the driver automatically or login as a Super User (with root privileges) in a Terminal session to manually uninstall the driver.

If the root user account is not active on your system it can be activated as shown below. If it is active you will need to know the password to allow you to log in as the root user/super user.

Activating Root User

These instructions apply to Mac OS X 10.2.8 and above – for earlier versions replace the NetInfo Manager navigation path ‘Security >’ with ‘Domain > Security >’

Start the NetInfo Manager application. From a Desktop Finder window, locate and launch the NetInfo Manager application, found at /Applications/Utilities/NetInfo Manager.

Choose Security > Authenticate and enter the password you use for your local account.

Choose Security > Enable Root User.

Now choose Security > Change Root Password to set a password for root.

If the Root user has been previously activated you will need to enter the old password before you can select a new password. If it was not previously activated you will be asked to select a new password.

Now that you have activated the Root user you will either be able to login as the Root user at the login screen to perform Automatic uninstall or run as a Super user (typing ‘su’ in a Terminal window) with root privileges to perform a manual uninstall of the driver.

Note: Running as a Super User in a terminal window is not the same as logging in as a Root user. Logging in as a Root user gives system wide root privileges whereas logging in as a Super user in a terminal session only gives root privileges to the terminal session and the command typed within the terminal.

After you’ve completed all tasks requiring root access, you can relinquish root privileges by choosing Security > Disable Root User

Manually

To uninstall the application simple drag the UPDD icons (initially installed in the utilities sub-folder within the Applications folder) to the trash can and delete any related icons from the users desktop.

Uninstall the driver

To uninstall the driver, the “root” account must be activated on the system, see activation section above.

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 (UPDD version 3 and 4.0.x)

Type “rm –r TBUPDDWU (UPDD version 4.1.x and above)

Type “rm /usr/local/lib/libhbutton.dylib”

Type “rm /usr/local/lib/libqt-mt.3.dylib”

Type “rm /usr/local/lib/libACE.dylib (UPDD version 4.1.x and above)

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.

Automatically

To follow.

Multi-monitor and multi-device support

Multi-monitor and multi pointer devices are supported with this driver and this functionality is covered in full in the multi monitor and device document, Mac section.

Display rotation considerations

Mac OS/X version 10.4 (Tiger) introduced video rotation where the video hardware supports it. 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 either need to;

1) Manually recalibrate after changing video resolution.

2) Call TBcalib /screenresupdate to request the driver readjusts calibration to cater for current video resolution. For further details, click here.

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. In the Mac environment the main setting 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. This setting is found in the System Preferences dialog, under Keyboard and Mouse.

The UPDD Console, Click Mode dialog, System settings will invoke this dialog as shown below:

Touch utilities

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

Mouse Cursor utility

Touch screen interfaces do not necessarily require a desktop cursor to be used or prefer a different cursor, such as crosshair, to the standard arrow associated with mouse usage. Should you require a mouse cursor utility you may find the Mighty Mouse utility of use, available at http://www.unsanity.com/products.php

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
Multi-monitor support only supports monitors defined left to right in the system
No sound on touch or during calibration
No automatic uninstall
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