Transcription

1 Page 1 of 10 Mac OS X Installation Revision 1.17, 11 th June 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 Release Date Change April 2006 Initial release for Mac Intel Aug 2006 General bug fixes and stabilisation of new system and Mac Power PC April 2007 Multi-Monitor support and device binding July 2007 System Preference entry plus improved binding in multiple touch devices Nov 2007 Mac OS X 10.5 (Leopard) support added Jan 2008 Improved binding, PnP device support, mouse interface Sept 2008 April 2009 July 2009 Sept 2009 Oct 2009 Uninstall facility added Nov 2010 Support 64 bit Fix. Intel and certain USB controllers intermittently did not respond after reboot. New Events interface allows for Keystrokes and Touch File permission changes to cater for Snow Leopard New install method to remove dependency on StuffIt Removal of touch driver system preferences entry Any application using UPDD API in Snow Leopard could cause crash. UPDD Console and calibration could randomly crash. Fix applied. Code base and associated utility changes Support Multi touch hardware via UPDD API June 2012 Generated Mac driver from latest UPDD code base Deliverables Oct 2012 Native installer introduced with updated documentation 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 attachment. Delivered to an FTP folder for manual download. The FTP link, user name and password details will be sent in an . Automatically downloaded from a HTTP download link as sent in an . The UPDD software comprises: Setup.app The installation program System Requirements Component C++ run-time library Reason C++ run-time library shipped as standard with Mac OS x 10.4 (Mac Intel support started at OS X 10.4). Please contact Touch-Base for a separate 10.1, 10.2 or 10.3 (Power PC) driver if required. A user has installed with so it is possible that the C++ libraries shipped with later versions of When the libraries are missing the set up program bounces in the dock. Running setup from a terminal command line shows the actual system error which is not seen when running it from the desktop. Stuffit (only if supplied the old macx.sit file) Stuffit is required to decompress the.sit file. This utility does not ship with latest Mac OS and can be downloaded from If using Mac Intel we highly recommend you use Stuffit 10.0.x or later. See for more details.

2 Page 2 of 10 Access to TCP IP port 4141 A few customers reported that a stuffit error was reported (using Stuffit 10.x) when trying to unpack the UPDD.sit file. The problem was overcome when they unchecked the preference Continue to expand if possible. The driver requires access to TCP IP port 4141 for internal computer processing only. 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: a. Using StuffIt to unpack as this is an old decompression method. Superseded since Sept 2009 release. b. 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. c. 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. d. 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 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 Upgrading to overcame this issue so we have not investigated further as we believe most users will be on 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 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 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 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

3 Page 3 of 10 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 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 Mac OS X driver release 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

4 Page 4 of 10 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 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.

5 Page 5 of 10 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

6 Page 6 of 10 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 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 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.

7 Page 7 of 10 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

8 Page 8 of 10 ** 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 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 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 Leopard

9 Page 9 of 10 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

10 Page 10 of 10 Cursorcerer Used to hide mouse cursor, available at many links, including: 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 the technical support team at