$Revision 3.12 – 6th July 2015 www.touch-base.com\documentation\drivers$

Installation procedures

Welcome to UPDD Mac OS X platform specific installation instructions and related notes for UPDD version 5. This version is based on the latest code base of the UPDD driver and significantly for Mac introduces a native Mac installer. The native installer only works on Mac OS X 10.6 and above. If using 10.5 or earlier you need to install UPDD version 4.1.10 as covered in the previous Mac OS X installation instructions.

Development history can be viewed from the UPDD Console and can also be viewed here.

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

For convenience a Quick Installation guide is available here.

License Notice

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

Evaluation version restrictions

Evaluation software, which is available from our Download Centre, is mainly used to test the touch function is working and has certain restrictions:

Clicks on the touch screen do not work after so many touches, only movement. With UPDD version 5.1.x a nag screen is shown.
Selecting OK on the nag screen offers a further number of clicks.
The nag screen is processed by the driver’s daemon task, aidaemon, so if this process is not running the nag screen will not be shown and the counter will not be reset.
Multi-touch gestures are not available in the evaluation version as the gesture software checks that a licensed version is installed.

Deliverables

Unless otherwise requested, the software is distributed via email as an HTTP link that references a single compressed file updd.dmg. The name of the file reflects the version of the driver being installed.

The UPDD software comprises of an installer package updd.pkg which, by default, is handled by the standard installer application.

Alternative methods to install do exist as referenced in the Installation Notes below.

System Requirements

Supported touch device	A supported USB or Serial touch device
Processor	Intel UPDD version 5.1.x supports 64 bit systems only. UPDD version 5.0.2 supports 32 and 64 bit systems. For Power PC users you need to run UPDD version 4.1.1
Mac OS X	Version 10.6 and above. For earlier versions (10.3 and 10.4) you need to run UPDD version 4.1.10.
Access to TCP IP port 4141	The driver requires access to TCP IP port 4141 for internal computer processing only.
USB Mass storage enabled	Required to install the software. If this is disabled the install will fail with various references in the install log: NSLocalizedDescription = "An error occurred while updating system extension information. NSUnderlyingError = "Error Domain=kextcache Code=71 \"The operation couldn’t be completed.

Installation Notes

1. Size requirements
The installer for release 5.1.x standard driver software is approximately 24MB and reports 60MB will be used to install all driver components, utilities and libraries.

2. Install over previous versions
Although this driver removes any previously installed 4.1.10 components it is still our recommendation, where you have an earlier version of the driver, 4.1.10 or otherwise, to uninstall the previous driver and reboot before installing this driver.

3. Removal of other touch drivers and hardware settings
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.

4. Installing on 10.8 – Mountain Lion / 10.9 – Mavericks / 10:10 - Yosemite

· If installing 5.0.2 on Mac OS X 10.8 and above the Installer.app runs in 64-bit mode by default and will display a message saying it has to quit and reopen in order to run our installer due to the use of a 32bit library. This is a minor issue in that it doesn’t stop the installer. This issue is overcome in version 5.1.x which is 64 bit only.

· Mac OS X 10.8 and above has a new security feature called Gatekeeper such that software installs can be restricted to trusted sources. Our installer carries a genuine Apple developer certificate and will install with the default Gatekeeper setting of “Allow applications downloaded from: Mac App Store and identified developers”. It will not install if the Gatekeeper setting is set to “Mac App Store” only.

5. Installation failure and logs
If installing via the standard installation application (Installer) and the installation should fail and the failure is detected by the installation then a dialog window will appear requesting that you email the installer log to technical@touch-base.com.

Please review the troubleshooting section for issue(s) that have prevented installation.

Should the install hang or fail undetected by the installer then the install log can be invoked / viewed manually from the Installer Menu as shown here:

The only hang we have experienced during development or testing is when a previously installed driver is in such a state that the installer hangs waiting for the currently installed driver to terminate. In all cases the install was successful once tried again after a reboot hence our recommendation to uninstall any previously installed UPDD drivers prior to installing this driver.

6. Alternative method of install
It’s possible to install a pkg file using both the command line and Apple’s Remote Desktop application (rather than Installer.app). These are mainly used by system administrators to install a package on many systems at once. Depending on the alternative method used there are some installer plug-ins that will not work in that some dialogs will not be shown, specifically the dialog used to configure the serial port when installing for a serial device. In this case simply invoke the UPDD Console program after install to add the device and configure the serial port. It is also possible that in some circumstances the dialog shown to indicate a reboot is required may not be seen. In this case, if touch is not working after install a reboot is likely required.

7. UPDD settings customisation
The installer will install the driver’s setting file with the initial default settings. Should these need to be different on multiple installs then you can create a custom UPDD setting file (extra.ini) that can be embedded with the updd pkg file (extracted from updd.dmg) to create a new updd.dmg using the disk utility app. The technique can, for example, be used to utilise calibration data taken from a calibrated system in subsequent installs.

8. Licensed monitor considerations
Some OEM versions of the driver supplied by monitor manufacturers will only work on their monitors. If the monitor type is not found the following will be displayed:

The driver looks for the correct manufacturer EDID code as configured in the build being present on the system.

9. ‘Aggressive’ start up error recovery mechanism
UPDD version 5.1.1410 for Mac OS X implements an aggressive error recovery mechanism that forces a USB re-enumeration at driver start up of all connected UPDD supported devices to overcome various reports of touch not working at certain times in certain environments. This is a new feature that may or may not cause some issues with other USB connected devices and can be disabled if required. Touch will not be available during this re-enumeration process and in our test this was negligible but we have had reports of delays up to 2 minutes on some systems! Further details about this feature are available here, including a setting to disable this feature if required.

10. Delay of touch functionality after install or reinstall

Some users have reported a delay in touch functionality or the appearance of the driver menu bar item, sometimes up to 2 minutes. We have not seen this in our tests so can only speculate but, as discussed above, in the latest driver we implement a more rigorous system whereby UPDD can forcibly take control of devices and force them to re-enumerate. This is to deal with a number of cases where hardware and Mac systems don’t cooperate properly and previously this would have been seen as a failure to detect a touch device.

In the case that a device cannot be grabbed this is re-attempted at intervals and during this time the operation of the driver is blocked. We suspect it is taking the driver some time to grab the device and complete the load sequence and a further delay for the driver’s client processes to reconnect to the driver. We do advise on the installer screen that it can take some minutes for touch functionality to work.

Installation Procedures

These instructions relate to the standard method of installation using the standard Installer application supplied with Mac OS X.

Run the updd.dmg file. This may be invoked automatically by some browsers. This will show the updd.pkg install file which should be invoked to initiate the install.

The initial dialog will show the software version and list the touch devices (controllers) supported by the driver. As stated in the dialog, USB controllers will be automatically detected. If the package supports a serial device then the installer will, during the install process, offer an option to configure the serial port.

In the example above the software supports three touch devices, two USB and one serial.

You will then need to accept the license to acknowledge this is licensed software copyrighted to Touch-Base Ltd.

If the package supports a serial controller then you will be presented with a dialog to configure the serial device:

This will list the supported serial devices and allow you to select a single device or allow you to skip the serial selection at this time. It also lists any native or virtual serial ports discovered on the system which can be associated with the selected serial device. A serial port option of None indicates that no specific port is to be assigned at this time.

In the example above two port entries are listed for the same virtual serial port because the virtual serial port driver created two named ports. This issue and other serial port issues are discussed in greater detail in the Serial Port configuration section below.

Package Selection

In most case the installer will be installing the touch driver only. However, some installers carry more that the driver package and can also include gesture and TUIO server packages (which are available as separate installs on our web site). These can be embedded in the installer in a manner such that they are installed without notification. In other cases a Package Selection screen is shown, listing the optional packages that can be installed.

This example shows that the gesture package is part of the installer and has been configured to request user selection:

Installers that include any additional packages will automatically invoke the software (Gestures or TUIO) and also create startup items so that the software is started automatically at login. As of Sept 2013 the installer creates startup items for all user accounts defined in the system so that the software is invoked for all users.

Note: When the installer completes while multiple users are logged in at the same time, the driver will run for all users but the Gestures or TUIO will only run for the current user, not for the other logged in users. We have not found a way to run a user mode application in other logged in user’s graphical sessions. They will, however, start running the next time the user logs in.

This is also true for the driver’s background task in UPDD version 5.1.x, which handles the driver’s menu item.

Following the initial dialog screens you will be requested to enter your login details to authenticate the install request.

The driver will now install and once completed will show that it has been successful:

This indicates that the driver install has completed.

Once the install (s) has completed and all being well the touch should now be active albeit not calibrated. If the cursor does not react and calibration fails then try rebooting the system. If touch is still not working after install and reboot please refer to the troubleshooting section below.

Silent install option

The following command will install UPDD in silent mode without any dialogs being issued:

sudo installer -target / -package UPDD_nn_nn_nnnn.pkg

This is a built in feature of OS X's installation system when using pkg files.

These installation file types also cater for driver roll out to numerous systems at once using Apple's sys admin tools.

Desktop and application touch interaction

Once the driver is installed and calibrated then by default the touch interaction is due to the touch screen being used to perform mouse emulation such that a touch on the screen is emulating a mouse pen down, mouse movement and pen up. In many cases this will satisfy simple single touch usage. However, there are a number of touch interfaces that can be utilized with our driver, as described below:

Interface	Brief description
Mouse emulation	Default interface that offers the most basic touch interface. In a Mac OS X environment the IOHID interface is used to post ‘mouse’ messages into the system.
Gestures	Interfaces with the gesture capability of the Mac OS system and gesture aware applications. This is particularly useful for dual and multi-touch touch devices as it allows common gestures to be performed via the touch screen. In some specialised UPDD driver installs this is installed and invoked automatically.
Gestures in touch enabled web pages	We are aware that UPDD Gestures (above) cannot be used to control touch-enabled web pages. The problem is that OS X doesn’t pass its system-level touch events to web browsers as HTML5 / javascript touches. So while these pages will work with an iPad (and similar) it can’t work in OS X, even when using an Apple’s magic trackpad. However, as of 20^th Aug 2013 we have expanded on some browser extension work, initially written by Boris Smus, to implement multi-touch TUIO interface in Chrome and Firefox browsers. This is described in full here.
TUIO	Allows TUIO Client applications to receive touches via the UPDD TUIO server interface. In some specialised UPDD driver installs this is installed and invoked automatically.
UPDD API	Allows UPDD API based touch applications to receive touches via the UPDD API.
JavaFX	Starting with JavaFX 2.2, users can interact with JavaFX applications using touches and gestures on touch-enabled devices. Touches and gestures can involve a single point or multiple points of contact. The type of event that is generated is determined by the touch or type of gesture that the user makes. This link describes working with events from Touch-enabled devices. We have compiled and tested the Gesture Events example program with our Mac OS X gesture implementation and found it all to work as expected therefore any JavaFX touch event driven applications should work as expected.
Flash	Utilising touch enabled Flash applications under Mac OS X is covered in our TUIO documentation, Interfaces section.

Once install is complete there are a number of driver related utilities that can be invoked to calibrate, configure and test the touch devices.

Driver Utilities

Menu bar item

Introduced in release 5.1.x the UPDD Menu bar item offers links to the main driver utilities:

	Double click on the icon to invoke the UPDD Console or single right click to show the menu:
	Indicates if the driver is to process the touch data for the device – use with caution if touch is the only interface!
	Invokes the touch screen calibration program, UPDD Calibration
	Invokes the driver settings program, UPDD Console
	Invokes the driver test program, UPDD Draw
	Invokes the help system
	Driver version information, Licensee name and Support Contract Number

Note: To hide/disable the driver’s menu bar icon use the UPDD command line utility by running the following command in a terminal window;

tbutils nodevice setting dw "show systray" 0 (set to 1 will re-enable).

Calibration

The Calibrate program can be invoked from the Menu item (5.1.x), Utilities folder or from the UPDD Console program.

Utilities folder

UPDD Console

Calibration is a procedure used to align the pointer device with the graphical 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.

Important note: When using extended monitors in Mac OS X 10:10 there is a bug in the graphics library used in the calibration program that results in the menu bar residing on the screen above the ‘full screen’ calibration such that the calibration points are shifted down the depth of the menu. Since UPDD release 5.1.1185 we now adjust the placement of the calibration points if this occurs. It is anticipated that this bug will be addressed in the next release of the graphics library.

Driver/Device settings – the UPDD Console

The driver setting program can be invoked from the Menu item (5.1.x), Utilities folder and the System Preferences, Other section:

Utilities folder

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

The currently selected controller is shown in at the top of the dialog. Where more than one touch device is connected and configured the device list can be used to select the controller against which you want to view or change the settings.

The examples below shows that the driver software supports a number of touch devices and the device list below reflects that all devices are connected to the system:

UPDD release 5.0.2	UPDD release 5.1.x

Test program

The driver test program can be invoked from the Menu item (5.1.x) and UPDD Application folder (/Library/Application Support/UPDD):

A simple test program is supplied to test the performance and accuracy of the touch device as handled by the UPDD driver.

It can be used to view stylus input from single and multi-touch devices.

Radial menu tool

The driver test program can be invoked from the Utilities folder if installed as part of the driver or where appropriate if installed separately.

The Radial Menu touch tool offers instance access to useful functions via a touch tool utility program and is described in full in the UPDD Radial Menu tool documentation.

Command Line interface

A command line utility (5.1.x) is supplied that can be used to perform certain configuration or device type functions.

Useful driver settings under Mac OS X

Edge Acceleration

Certain features in Mac OS X can be invoked when the cursor is pushed to the corners or edges of the system monitor, such as the showing a hidden Dock or the option to run individual applications in full screen mode:

When running in full screen mode you need to be able to push the cursor to the top of the screen to expose the menu bar to be able to select the standard-size option and this may not be possible when using a finger with the active point of the cursor under the centre of the finger.

To cater for the need to be able to place the cursor to the extreme edges there is an advanced setting in UPDD (UPDD Console, Properties, Advanced) to accelerate the cursor toward the edge of the screen as the stylus approaches the edge. The values shown below work well:

These settings are useful to invoke any application or function that is invoked by placing the system point to the edge of the display.

Please note that the option to magnify the system dock items makes it impossible to select the correct dock entry with a touch screen and this function should be disabled if needing to select items from the dock via touch, see Notes below.

Drag setting

When the driver is operating in ‘Click and Drag’ mode the driver sends a Left click down followed by a stream of events reporting the current touch position followed by a Left click up. This occurs even for a tap. It was reported that some applications would reject a pen click request if events occurred between the click down and up, for example we saw this with Quartz Composer. To cater for this we have introduced a setting in UPDD 5.1.1127, minimumDrag, which specifies the minimum number of pixel movement that must occur before the driver starts sending co-ordinate data. This is not defined by default. With this defined there will be a slight delay in drag operations until the touch co-ordinates have moved beyond the pixel threshold. This can be set with the tbutils command, e.g. “tbutils nodevice setting dw minimumDrag A” sets 10 pixels.

Assisted Double Click setting

Typically it is more difficult to double click elements with a touch screen than with a device such as a mouse due to the difficulty touching the same location with adequate accuracy twice and movement of the touch during each of the clicks. UPDD driver supports an “assisted double click” feature. The feature can be enabled In the UPDD Console, Properties, Advanced dialog. This setting is only required if the driver, rather than the gesture software, is handling tap and press functions. Gestures has the same feature enabled by default.

Serial port Configuration

The UPDD Console, Hardware tab allows the serial port configuration to be changed if required:

Use the dropdown to select the name of the serial port. By default, the communication parameters should be setup to the correct values for the device and should only be changed if you known that the serial touch device requires different parameters.

If your serial port is not listed, read on……

Serial port identification and testing

We use a file called serial.dat to define the naming convention of valid native and virtual com ports available on a Mac. Typical virtual serial port names are as follows:

^cu\.USA*

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

^cu\.usbserial*

^tty\.usb*

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. Entries in serial.dat define the serial ports we have encountered thus far.

Please let us know any serial port names that you encounter that should be added so we can update the master file for future use.

The file is write protected in a write protected folder. To edit the file:

1. Update the permissions – chmod 777 “/Library/Application Support/UPDD/serial.dat”

2. Open and edit “/Library/Application Support/UPDD/serial.dat” in TextEdit, save.

Serial port names can be found in the /dev folder (as seen from a Terminal window’s LS command). These are created by the driver supplied with the physical serial to USB adaptor so only adaptors that have a compatible Mac OS x driver can be used.

In the above example two virtual serial port are listed. This is a Keyspan serial to usb adaptor. In this particular instance the Keyspan driver has, for whatever reason, created two device entries. 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 names associated with the device:

Serial port testing

You can use the cat command to determine if any data is being seen on the serial port, as per this example:

After running the command, touching the screen should result in some characters being shown in the terminal window. Ctrl C terminates the command.

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

To uninstall run the “Uninstall UPDD” program from the Utilities folder.

Click “Uninstall” to uninstall the software or “Cancel” to cancel the uninstall.

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

Following uninstall, if the uninstall program remains in the utilities folder this can be dragged to the trash can to remove.

As of 5.0.2, July 2013, the uninstaller now also uninstalls any UPDD extensions that require the driver to be installed, such as Gestures and TUIO Server. Any start up items are removed and the applications are deleted from the /applications/utilites folder (so long as they reside in this folder!)

General Notes

Component Location

Following the install the driver’s components are located in the following locations:

Desciption	Name	Location
Application folder	UPDD	/Library/Application Support
Test program	updddraw	/Library/Application Support/UPDD
Utilities program	tbutils	/usr/local/bin (console program)
Driver	tbupddwu	/Library/Application Support/UPDD
Background process	aidaemon	/Library/Application Support/UPDD
Python script	upddprocesses.py	/Library/Application Support/UPDD
Python script	launchctlutils.py	/Library/Application Support/UPDD
Driver launch script	tbupddwu_start.sh	/Library/Application Support/UPDD
API components	tbapi.h, libtbapi.a, nonwindows.h	/Library/Application Support/UPDD/api
Settings file	tbupdd.ini	/Library/Preferences This is system-wide preferences directory.
Console Program	UPDD Console	/Applications/Utilities
Calibration Program	UPDD Calibration	/Applications/Utilities
Uninstall	Uninstall UPDD	/Applications/Utilities
Plist files	For tbupddwu and aidaemon	/Library/LaunchAgents /Library/LaunchDaemons The LaunchAgents and LaunchDaemons directory contain plist files for automatically launching background processes. Daemons are launched as root at system startup, while agents are launched as the current interactive user. A plist file for both tbupddwu and aidaemon are placed in LaunchDaemons and LaunchAgents respectively. Since UPDD 5.1.1118 the plist file responsible for launching tbupddwu at startup now works by launching a shell script that launches tbupddwu, rather than launching tbupddwu directly, which did not always allocate the resources need by the driver and gave performance issues. Launching indirectly overcame these issues! This shell script is named tbupddwu_start.sh and is included in the UPDD directory.
Kernel extension	tbupddmxhid.kext	/System/Library/Extensions (10.6, 10.7 and 10.8) and /Library/Extensions (10.9 and 10.10) The system-wide kernel extension directory, where all IOKit kernel extensions must be placed. This extension is a codeless Kext with no running code so is not listed by any Kext utilities. Its purpose to register the driver for the supported USB device (s) so that UPDD can take control. This also prevents HID taking control of HID devices to be supported by UPDD.
Shared libraries	LibACE, libQt-mt / libhbutton_tb.	/usr/local/lib (may be hidden from view in Finder window). Location for shared libraries. 5.0.x and 5.1.x 5.0.x only
QT4 libraries	Installed as private frameworks	/Library/Application Support/UPDD/Frameworks
Support files	Various	/installerData Support files needed for building a Mac installer that are not actually installed are placed in here. Such files include the installer background image, the EULA and introduction text.

Processes

In normal circumstances once installation has completed there will be a number of processes running. This is not always the case as some specialised OEM versions of the installer do not start the processes and these are automatically invoked when the touch device is detected. The actual number will be dependant on the installed components held in the installer. The core driver utilises two processes tbupddwu (the user mode driver service) and aidaemon (the background task). If gestures and/or TUIO server is installed these applications will also be running.

In some cases an end user may wish to start / stop UPDD related processes such that they are only running when required. To allow for this we have created a python script, named upddprocesses.py, which can be used to start and stop the various processes. This uses a supporting file ‘launchctlutils.py’.

The script must be run under superuser and the supporting file "launchctlutils.py" should be kept in the same folder. It can be used from the command line, a script, or process by executing it thusly:

python upddprocesses.py start

python upddprocesses.py stop

or running from the UPDD folder

sudo python "/Library/Application Support/UPDD/upddprocesses.py" start

sudo python "/Library/Application Support/UPDD/upddprocesses.py" stop

It can also be used as a python module in another python script like this:

import upddprocesses

upddprocesses.startProcesses()

upddprocesses.stopProcesses()

Prior to Oct 2014 the script can only start all processes or stop all processes, including UPDD Gestures and UPDD TUIO if either is installed.

With builds issued after Oct 2014 we’ve added some command line arguments for ignoring errors and being able to specify specific UPDD processes as described below:

Usage: upddprocesses.py start|stop <options>

Options:
-h or --help	Show this help message and exit
-I or --ignore-errors	Attempt to start or stop all specified processes; do not stop on errors
Processes:	All processes are affected by default. If one or more of these options are used, only the selected processes will be affected.
-d or --driver	Start/stop tbupddwu
-a or --aidaemon	Start/stop aidaemon
-g or --gestures	Start/stop UPDD Gestures
-t or --tuio	Start/stop UPDD TUIO

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

Keyboard Modifiers

Mac OS/X supports "modifier keys" that can be used in conjunction with a mouse.
For example pressing the Ctrl key on the keyboard and clicking the mouse (left button if using a multi button mouse) invokes a context menu and Shift + click allows multiple selections.

When UPDD is used in the normal click and drag mode then these modifiers will perform the same actions as when used in conjunction with a mouse or trackpad.

Please note – for technical reasons this functionality was disabled in UPDD driver version 5.1.x and moved to the UPDD gesture software. Should you require this function install the gesture software. It is intended to be reinstated in UPDD Version 6.

System Dock Magnification issue

When magnification is turned on, the positions of the Dock icons on screen don't actually correspond to where you need to move the mouse to click them, as they scroll to meet the mouse faster than the mouse moves (if that makes sense). This means that when you touch one of the items the cursor instantly moves to the touched location but the Dock icons suddenly jump past where they are expected to be (due to the magnification function). To overcome this to need to turn Dock magnification off.

Technical note: We could probably devise a hacky method of fixing this issue by determining if a touch is in the dock and over what icon and calculating where that icon will actually be on screen when magnified and moving the mouse (touch) to the appropriate position but given there is a solution by disabling magnification we are not sure this is really necessary.

Screen Zooming

Screen zooming has three different settings for how the zoomed portion of the screen will follow the mouse cursor, as listed in the Accessibility system preferences / Zoom / More Options. The only one that works with touch and our driver is "Only when the pointer reaches an edge" due to the fact that synthetic mouse events will go to the correct position on the zoomed screen, so it can be used with the driver’s mouse emulation or UPDD Gestures interface.

The other screen zooming settings, "Continuously with pointer" and "So the pointer is at or near the center of the screen" both move the screen image every time the cursor is moved, so whenever the user touches the screen, the image will jump chaotically, hence is not suitable for touch.

OS X also supports an alternative "picture in picture" zoom, and that's also works with the driver, either by itself or with Gestures.

It may be possibility to determine how the screen is zoomed and support the other two settings but it is unlikely that those zooming methods will be used with touch so we have not pursued this support.

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, Mouse.

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

Mouse cursor considerations

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.

The driver will shortly be updated to offer a hide mouse cursor option. In the meantime you can also utilise our gesture extensions software to hide the mouse cursor if required. However, there our other options, such as those discussed below:

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/

Parallels

Parallels is a program that allows you to run a virtualised Windows system on a Mac. Individual Windows dialogs are displayed on the Mac desktop. When using the UPDD Mac driver single touch will be active within the Windows dialog and processed as mouse emulation.

However, if the Windows extended touch features are required in the Windows session (flicks, gestures, multi-touch etc) you need to allow the virtualised Windows session to connect directly to the touch device. At the point of the connection Windows HID (if you have a USB HID touch device) or any other Windows touch driver, such as UPDD for Windows, will take control of the device.

In the example below the Optical Touch Screen device has been selected and Windows HID has taken control and extended touch features work within the Windows dialogs as seen with the dual drawing in Paint. If the device is unchecked the Mac driver gets the device and then touch processing reverts back to the UPDD Mac driver.

Note below that the name of the touch device as listed in the Mac UPDD Console is listed in red text to indicate the device is no longer available on the Mac. It will be displayed in black text once the device is returned to the Mac OS.

Touch utilities

Virtual Keyboards

Mac OS X ships with its own virtual on-screen keyboard but we recommend KeyUp as a superior keyboard.

Troubleshooting

Following successful installation and reboot of the system (if requested/required) the device should respond to UPDD calibration (a moving cursor does not always indicate UPDD driver is in control of the touch device). The key elements to check are:

· Install completed correctly

The touch device is known to be working
The device is plugged into the system and recognised by the OS.
The driver is running
The device is supported and is seen by the driver
Touch data is being received from the device and made available on its API (driver utility program function as expected)
The device is calibrated and associated with the correct desktop
Touch data is being posted into the OS if using one of the standard input interfaces

Follow these steps to help identify the problem:

Install waiting for a previous install to complete

If this happens:

then the previous install is actually hung or stuck or has been killed try this command to recover the situation:

sudo rm /private/var/db/mds/system/mds.install.lock

and then reboot the system.

Corrupted Kext file preventing install

A customer reported that UPDD failed to install on Mountain Lion. The install log revealed that there was an error when OS X was rebuilding the cache of kernel extensions as shown below. This was a known problem with this particular .kext extensions with various reported incidents on the web (e.g. https://discussions.apple.com/thread/4269472?start=0&tstart=0)

May 2 15:00:42 MacLollo.local installd[730]: kextcache: Prelink failed for com.freecom.driver.BoulderScsi; aborting prelink.
May 2 15:00:42 MacLollo.local installd[730]: kextcache: Failed to generate prelinked kernel.
May 2 15:00:42 MacLollo.local installd[730]: kextcache: Child process /usr/sbin/kextcache[762] exited with status 71.

We understand that kextcache error 71 indicates the OS is failing to rebuild its cache of kernel extensions, which in turn is preventing the installation of UPDD. In this example, the problematic kext appears to be "BoulderScsi.kext".

Should a similar issue occur it is our recommendation to remove the kext if it's not needed, or if it is, to try updating / reinstalling it. In this example it is possible that the kext is an earlier 10.6 version and it doesn't work with 10.8."

To remove a kext extension it should be as simple as opening /System/Library/Extensions, finding the .kext file, and deleting it / moving it to the trash. Alternatively:

1. open terminal
2. $ sudo rm -rf /System/Library/Extensions/BoulderScsi.kext
3. reboot

Installer Log

The UPDD installer creates an installer log file, and will report any errors that is detects during install. Depending on the nature of the error the driver may or may not be working. One such detected failure that allowed the driver to work was the inability of the install program to kill the active UPDD driver when reinstalling UPDD. This error is explained in the log as:

./preinstall: preinstall warning: Cannot terminate tbupddwu before installing

In this instance it would appear that installer couldn't force tbupddwu (the driver) to quit or took longer than expected to quit. The installer uses the strongest possible method to kill a process (sending it SIGKILL) if it doesn't terminate as requested and we are surprised that tbupddwu survived this request! However, it is likely that it did eventually quit as the user reported everything as working.

Check the device is seen by the system

Ensure the device is plugged in and run the System Profiler/Report to list the USB devices plugged in to ensure the device is seen by the system and also identify if the device listed (by Manufacturer, USB Vendor id and Product id) is that expected by the driver.

We have had reports the some touch devices will not be recognised in USB 3.0 port. Try plugging into a USB 2.0 port or use a USB 2.0 hub

Check the device is seen by the driver

The UPDD Console will indicate the connection status of the touch device as shown below:

USB device found or configured serial port connected

USB device unplugged or serial port missing

Red text listing can be because a serial port is incorrectly defined or not available or a USB device is no longer connected. If a USB device is plugged in it may not be supported by the driver or the device is being handled by another 3rd party driver, such as the standard HID driver. If using a serial device ensure the serial port is defined in the system and correctly set in the UPDD Console, Hardware dialog.

No USB device found

The text ‘No devices found’ will be displayed if none of the devices configured or supported are found on the system. Ensure no other 3rd party drivers are trying to handle the device. If you have just installed, try rebooting, especially if no name is listed in the console. Further advanced checks are documented here.

No cursor movement and cannot be calibrated

We’ve had reports whereby all looks OK, where the UPDD Console lists the device in black text, but the touch does not work. Sometimes a simple replug of the USB touch screen or a monitor power on / off has resolved the issue. In both these cases the driver would attempt to re-enumerate the device and re-establish connection, the implication being that the previous attempt had failed.

We have had reports whereby there has been USB clashes between touch and mouse devices preventing the touch screen working. Once such report was that a wireless mouse caused a clash and once disconnected the touch worked.

Cursor is moving but cannot be calibrated

If the cursor is moving when you touch the screen then ‘something’ is in control of the device. If you cannot calibrate with our calibration program or the cursor is moving when our calibrate program is displayed then UPDD is not in control of the device.

This often indicates that the device is HID compatible and that the Mac OS X HID driver has retained control - despite the fact that UPDD is programmed to take control from the HID driver or you have a 3^rd party driver installed that is controlling the device.

Driver components are loaded

Obviously the touch will not work if the driver component fails to load (some custom installs deliberately do not start the processes). However, in the Mac OS environment, the daemon process performs a number of functions, such as sound, rotate and mouse interface for the logged in accounts (this is performed by the driver pre logon) so it is important this is loaded if these functions are required.

Check that both the driver (tbupddwu) and its daemon process (aidaemon) are loaded by running the Activity Monitor located in the utilities folder:

If the processes are not running try running them manually as described here.

Crash logs

If a crash occurs, or is thought to have occurred, with one of our components, be it a driver component or an add-on component such as the TUIO or Gesture extensions then the system may create a crash log located in one of two areas, depending on a user or system component crash:

User component crash (user components: UPDD Console, UPDD TUIO, UPDD Calibration, UPDD Gestures, aidaemon etc)

~/Library/Logs/DiagnosticReports

~/Library/Logs/CrashReporter (alias of the above folder)

It will include the name of the crashing component, such as: "UPDD Console_[timestamp]_[computer name].crash”

System component crash (driver)

/Library/Logs/DiagnosticReports

/Library/Logs/CrashReporter (alias of the above folder)

It will include the name of the crashing component, such as: "tbupddwu_[timestamp]_[computer name].crash”

Depending on the OS in use the ‘Library’ folder may be hidden by default. To locate the Library folder, choose 'Go to Folder' from Finder’s 'Go' menu and type:

~/Library/Logs/DiagnosticReports/ or /Library/Logs/DiagnosticReports/

Should you wish to make the Library folder permanently visible type the following command in Terminal:

e.g. chflags nohidden ~/Library – this works for in Mac OSX Lion – it may be slight different for other OS versions.

Current Limitations

UPDD was originally developed for Windows and has since been ported to other OS. Not all features have been ported to Mac OS X, 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

Contact

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