Deliverables

Requirements

CD distribution

Classic Mode

Notes

Install

Calibration

Settings

Serial port issues

Uninstall

Multi-device

Rotation

Mouse issues

Touch utilities

Limitations

Contact

Welcome to UPDD Mac OS X platform specific installation instructions and related notes for UPDD 4.1.x. If using UPDD 5.0.x with the new native Mac installer, released in beta form Oct 2013, please refer to the new Mac OS X installation instructions.

These notes should be followed to install the UPDD pointer device driver on Mac OS X platforms utilising 10.2 and above.

Driver build history

Deliverables

For Mac OS X the program is distributed as a single compressed file macx.sit (pre Sept 09 version) or macx.tgz (since Sept 2009).

We are aware .sit files are an old Mac OS X compressed format which requires StuffIt for decompression and we are sorry for any inconvenience this may cause. This is not required for the latest macx.tgz files!

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

System Requirements

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:

1. Using StuffIt to unpack as this is an old decompression method.  Superseded since 4.1.1 Sept 2009 release.
2. 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.
3. 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.
4. 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 automatic uninstaller avoids this requirement.
   
   

2.    One customer reported that a stuffit error was reported (using Stuffit 10.x) when trying to unpack the Macx.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.

5.    One customer reported a clash between our driver and a HID utility he used to configure HID devices called controllermate which prevented the driver working.

6.    Ensure any 3^rd party touch screen driver is uninstalled before testing UPDD. If touch hardware has a special Mac mode, such as Next Window hardware, you may need to set the device into normal touch mode as reported by this user “Originally I was having trouble getting the equivalent of a 'click and hold' effect from the unit; but by killing the mac mode, leaving the drag function active on the hardware side and setting your driver to point & click all is now OK. 

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 the decompression process will be called setup.1, setup.2 etc 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.
or….
It has occasionally been reported that the UPDD extension, tbupddmxhid.kext, fails to load.  This is not seen on the GUI install but is if you try to manually load the extension in a terminal window:

# kextload -t /System/Library/Extensions/tbupddmxhid.kext
kernel extension /System/Library/Extensions/tbupddmxhid.kext has problems:
Authentication failures:
{
  "File owner/permissions are incorrect" = (
  "/System/Library/Extensions/tbupddmxhid.kext"
  "/System/Library/Extensions/tbupddmxhid.kext/Contents/Info.plist"
  "/System/Library/Extensions/tbupddmxhid.kext/Contents"
"/System/Library/Extensions/tbupddmxhid.kext/Contents/MacOS/tbupddmxhid"
  "/System/Library/Extensions/tbupddmxhid.kext/Contents/MacOS"
 )
}
Resetting permissions on the extensions folder:
# chown -R root:wheel /System/Library/Extensions
Will allow for the extension to be successfully loaded.

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 its 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

Please note UPDD Mac OS X driver release 4.1.1 is a 32 bit driver only.  To use this driver you must be on a 32 bit system or boot a 64 bit system in 32 bit (hold 3 and 2 keys down during boot – see http://support.apple.com/kb/HT3773)

Mac OS X driver release 4.1.10 works in both 32 and 64 bit

Copy the compressed file to your desktop. Note: If the file is downloaded via a browser then some browsers, such as Safari, will automatically extract the .tar file from the .tgz compressed file and create setup.tar. This file should be copied to your desktop.

Now double click the file (macx.sit, macx.tgz or setup.tar).  The associated extraction program (.sit = Stuffit, others = Archive utility) will run to create the Setup program. This must be called setup and should be renamed to setup if the decompression has named it setup.1, setup.2 etc)

Double click the setup program icon, enter your Mac users password and the controller selection dialog will be shown (with version 4.1.x there may be a delay 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.

Important note: If installing UPDD 4.1.10 on Tiger (10.4.x) or Leopard (10.5.x) the after install and reboot load the UPDD Console, Properties page and ensure the Support New Events checkbox  is disabled.  Touch will not work if this setting is enabled in these versions of the OS.  This is meant to be set automatically during install but check this setting if you can calibrate but touch does not work!

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.

Note: If a virtual serial port (via USB) is unplugged and replugged the touch may stop working. If this is the case use the UPDD Console. Status, Reload driver to re-establish connection (or reboot the system).

Uninstall

Automatic (4.1.1 post 17^th Sept 2008)

To uninstall the software open a “Finder” window and on the left hand side click the icon for your hard disk. Double click the folder “tbupddmx” in the main window and then double click the “uninstall” program.

Click “uninstall” to uninstall the program or “cancel” to cancel the uninstall.

You will need to enter your login details to authenticate the uninstall and then the process will start.

Manual Uninstall (4.0.x and 4.1.1 before 17^th Sept 2008)

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.

Touch Interface with Keystrokes

A touch driver has to interface with the OS to move the system pointer and generate mouse clicks.  However, it was discovered that since Mac OS 10.3.6 the interface we used (Interface Method 1 – IM1) did not correctly handle mouse emulation if keyboard keystrokes were being used with mouse clicks e.g. ‘CTRL mouse click’ to select multiple items. We investigated this problem and found another interface method (IM2) which appeared to work well and also handled keystrokes.  

With 10.6.x (Snow Leopard) we discovered that IM2 also had issues with keystrokes and discovered a 3^rd interface method (IM3).

We have found that IM3 does not work at system logon due to enhanced security in OS/X. On the assumption that modifier keys aren’t required on the login screen, we have currently implemented a composite approach where on the login screen we use the “IM1” mode and switch to “IM2” (Tiger/Leopard) or “IM3” (Snow Leopard) mode in other cases.

Both interface methods are in place for support purposes. Switching between methods IM2 and IM3 is supported by the “Support New Events” UPDD Console option. Since Jan 2011 UPDD 4.1.10 release “Support New Events” is automatically set depending on which version of the OS/X is in use. Users of OS/X prior to Snow Leopard ensure “Support New Events” is disabled in the UPDD Console.

A system reboot is required if the Select New Events setting is changed.

Currently the Select New Events interface only works with Intel processors.

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 (10.4/5) and Mouse (10.6).

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

Mac OS X, 10.4 Tiger and 10.5 - Leopard

Snow Leopard

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 following of use:

Mighty Mouse

Used to change cursor, available at http://www.unsanity.com/products.php   

Cursorcerer

Used to hide mouse cursor, available at many links, including: http://doomlaser.com/cursorcerer-hide-your-cursor-at-will/

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
• 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