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.
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:
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.
Install over previous versions
Removal of other touch drivers and hardware settings
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.
Installation failure and logs
Alternative method of install
UPDD settings customisation
Licensed monitor considerations
‘Aggressive’ start up error recovery mechanism
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.
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.
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.
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:
Once install is complete there are a number of driver related utilities that can be invoked to calibrate, configure and test the touch devices.
Menu bar item
Introduced in release 5.1.x the UPDD Menu bar item offers links to the main driver utilities:
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;
setting dw "show systray" 0 (set to 1 will re-enable).
The Calibrate program can be invoked from the Menu item (5.1.x), Utilities folder or from the UPDD Console program.
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:
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:
The driver test program can be invoked from the Menu item (5.1.x) and UPDD Application folder (/Library/Application Support/UPDD):
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.
Command Line interface
A command line utility (5.1.x) is supplied that can be used to perform certain configuration or device type functions.
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.
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.
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\.KeySerial* - This entry relates to the serial port listed above
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:
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).
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!)
Following the install the driver’s components are located in the following locations:
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:
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>
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.
Mac OS/X supports "modifier keys" that can be
used in conjunction with a mouse.
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 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.
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:
Used to change cursor, available at http://www.unsanity.com/products.php
Used to hide mouse cursor, available at many links, including: http://doomlaser.com/cursorcerer-hide-your-cursor-at-will/
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.
Mac OS X ships with its own virtual on-screen keyboard but we recommend KeyUp as a superior keyboard.
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
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: kextcache:
Prelink failed for com.freecom.driver.BoulderScsi; aborting prelink.
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
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:
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 3rd party driver installed that is controlling the device.
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.
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/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/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.
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
For further information or technical assistance please email the technical support team at firstname.lastname@example.org