Quick installation guide

Updated

Welcome to the Mac OS X Quick Installation Guide which covers the key elements for installing the UPDD Mac OS X version 6 driver. At the time of writing this driver supports Mac OS X 10:7 thro’ 10:15 Catalin.

A full UPDD driver installation document is available here and contains comprehensive installation and usage instructions and should be referenced if installation fails or the touch screen does not function as expected and for a greater understanding of the UPDD driver software.

Very important security notice if installing in 10.13 and above:

  1. Apple introduced additional security features in MacOSX 10.13 that affected the installation of system (kernel) extensions - commonly known as a kext. All 3rd party kexts now need to be explicitly allowed, regardless of whether they're signed with a valid key. To cater for this we had to make changes to the UPDD kext file and our installer. These changes were made in UPDD V6 version 304 and were further enhanced in 519 for 10.15. Earlier versions will not work in 10.13. The updated kext file is now installed in 10.9 thru' 10.15. Only 10.7 and 10.8 use the old kext file. These installation notes have been updated to show the additional installation procedures that need to be undertaken in 10.13 and above.

  2. The changes we made in the new kext not only allowed our software to install in 10.13 and above but also addressed a few ongoing issues, such as often needing a reboot after install for our driver to get control of the device. All of this is positive. However, since moving over to the new kext we have had a few customers whereby the kext has not been correctly installed and the touch has not worked and we have investigated these cases in great detail and documented our findings and possible solutions here.

UPDD Commander settings

This utility is responsible for processing the gestures and triggering the actions when the gesture is performed on the touch device. It comes with a default set of gesture and actions and a list of predefined applications. All of these setting can be modifed and configured as required. This being the case, installing over an existing installation retains the current gesture and action settings and application list. These can be removed prior to install if required as descibed here.

Installation procedure

If you do not follow the installation steps in full, especially in 10.13 and above, there is a good chance touch will not work. It is very important that you 'Allow' our kext file to be installed and give accessibility permissions to our applications. Prior to installing please watch the installation video below to see the steps involved to achieve a successful installation.

  

The software is delivered via email as a HTTP download link to a Mac OS X disk image container file updd_06_nn_nn.dmg. The actual name of the .dmg file reflects the version of the driver being installed, e.g.updd_06_00_1.dmg.



The .dmg file will expand to a package file updd.pkg (this step may be invoked automatically when downloading the .dmg file).


To install the software double click on the package file and follow the instructions on the install dialog until the ‘Installation has completed’ screen is seen. During the installation procedure you will be prompted to enter your password.

The driver install dialog will also list any additional software packages that are included as part of the driver install.

In very rare cases the installer will fail and if this failure is detected you will see the following dialog:

Further information on software install failures is available here.

If installing on 10.13 or above then on the first time you install the driver you will be informed that you will need approve the system extension during the installation.

In 10.13 and above if the system extension has not previously been approved you will be presented with the block notification:

A customer reported that installing remotely they were blocked from clicking OK on this dialog. They created an Automator script to press the button!

Once you acknowledge the above dialog the installer will automatically invoke the general section of the Security & Privacy dialog to allow you to approve our system extension to be installed.

Click the lock to make changes and select Allow.

Some customers have reported at this point the 'Allow' option does not work, especially with keyboard only access. In this case you may need to follow the instructions here once installation has completed.

Enabling accessibility features

Starting with MacOS 10.13 and extended in 10.14 the OS now seeks permission for any applications that use system interfaces to control the system. This applies to our components as described below:

Commander / Gestures will seek permission on 10.13 and above. The other components only need permission to be granted for 10.14 and above.

Component Name   From Description 
 Driver  UPDD.app  10.14 UPDD 6.0 591 build and above 
Handles the touch on the login screen and once logged in handles single touch mouse emulation if no other process is controlling the touch (e.g. UPDD Gestures/Commander). Mouse emulation is also needed when running UPDD Annotate and Test programs to activate the dialog controls via touch.
​If permission is not granted touch will not work on the login screen and also when required on the desktop as described above.
UPDD pre 6.0.591 build only used for touch at login and has to be manually added to the Securities & Privacy dialog from the /Library/Application Support/UPDD folder.

 Commander UPDD Commander.app   10.13 The Commander utility that runs as a background process for each logged in use. Handles both touch, TUIO and gesture functions.
When it runs without accessibility permissions, a window will open requesting the user to grant permissions.
Once it has permission the dialog will change to read "UPDD Commander is now ready to run" with a "Start UPDD Commander" button that will launch the application.
 Not required Since UPDD 6.0.591    The applications below are either no longer used or need permission to run.
 Daemon  UPDD Daemon.app  10.14 The driver's daemon process that runs as a background process for each logged in use. Handles single touch mouse emulation if no other process is controlling the touch (e.g. gestures/commander).
 Gestures
 UPDD Gestures.app  10.13 Replaced by UPDD Commander. Handles both touch and gesture functions.
 TUIO server  UPDD TUIO.app  10.14 Replaced by UPDD Commander. Permission is required if you set the 'hide mouse' setting..  

Given the above at some point during the installation you will be asked to grant permission for some of the driver's process, as in these examples, to access the system (in 10.7/10.8 the dialog will be different).

     

Selecting the 'Open ...' option will invoke the Securities & Privacy dialog as per this example showing the UPDD components that have been granted permission.

The '+' control can be used to add a component. Please check the component to be granted permission:

Since UPDD 6.0.591 UPDD Daemon no longer requires permission.

UPDD Commander will not launch until is has permission set. Once set the following dialog is seen.

​In most cases UPDD Commader (previously Gestures) is likely to be the only component processing the touch given that most touch uses don't have touch at login (driver), don't use single touch mouse emulation (daemon) and therefore this is the main UPDD utility requiring permission to be set.
In cases where UPDD test shows touch is OK but there is no touch cursor movement or gesture support outside of test it is likely to be an issue with permission. In this case remove and add UPDD Command (or UPDD Gestures) from the Security dialog as per these instructions and it should start working as expected.

All being well you will then see the installation complete dialog:

Once the driver is loaded it will check to see if the UPDD kernel extension is registered correctly (for 10.13 you must have given permission for the kernel extensions to load). The driver will issue a notification if the kext is loaded but not registered:

If this is seen you need to open up Security & Privacy system dialog and allow the 'Touch-Base' software or, if permission has already been granted, follow the troubleshooting instructions here.

Following install the touch screen should be working and the point of touch activated under the stylus. If the touch is working but the point of touch is not calibrated or controlling the wrong screen then invoke the configure procedure.

If touch is not working you may see a notification to reboot the system. This is issued if the driver fails to get exclusive access to a newly discovered device and will be repeated at 1 minute intervals for 5 minutes.

If there is no touch response after a reboot please refer to the troubleshooting document. Should you need to contact Touch-Base please run diagnostics and send us the resultant file.

The touch hardware and UPDD software can initially be tested with the test utility.

Notes if the touch device is an HID compatible device

1. After install there can be a considerable delay (1 to 4 minutes!) before UPDD is in control as it waits for the native HID driver to relinquish control.  This only occurs at the initial install.  In some extreme cases a reboot may be required.

2. ​We have discovered that on MacOS 10.12 and 10.13 installing on top of an existing UPDD V6 install will often result in the native HID driver staying in control of the touch device (albeit unlikely to be working correctly) with the UPDD Console showing No device connected.  If this occurs a reboot will be required.

Menu Bar Items

There will be Menu Bar item for each UPDD component installed (in some OEM installs these may be disabled):

These are the icons and menus for most recent Daemon and Commander. Older V6 installs may have Gestures and TUIO instead of Commander

Selecting the menu bar icon will list the menu options:

Daemon Gestures




With UPDD version 6, applications that connect to the driver via the driver's API, such as the three above, will receive notification if the connection to the API drops, implying the driver is not available. In this instance the menu bar icons will show an exclamation mark and touch is unlikely to be active, such as the driver's menu bar icon:

- driver disconnected / connected notification

​If installing an evaluation version of the driver then the 'Register' option will be shown in the UPDD Daemon menu. Prior to being registered the driver will work for a certain number of touches (normally 200) per reboot for 7 days. This restriction is removed once the driver is registered. The UPDD Status screen indicates if you are running an evaluation version and shows number of touches remaining for this session and the number of days remaining:

The UPDD utilities programs are placed in the Mac’s Utilities or the UPDD's Application folder. There are a number of utilities related to the driver and one each for Annotate, Commander, Calibrate Test and Uninstall - the latter being used to uninstall the software.

Utilities

UPDD application folder

Following installation the touch should be working and calibrated, if not please review the troubleshooting guide.

Test utility

A simple test utility exist to test the touch mouse interface and the UPDD API and TUIO Server data input.

Calibration

If the registered touch point is offset from the point of touch, or the touch is not associated with the correct monitor, then the touch screen will need to be calibrated with the video area. The simplest way to achieve this is to invoke the Configure option from the Daemon menu.

System Interfaces

A number of System Interfaces are used to post touch data into the Mac OS X system and applications as described below:

Interface
Description
Driver The driver reads all touch data from the touch screen but only posts single touches directly into the system such that the touch screen acts like a mouse type device. All touch data received from the device is made available on the driver’s Application Programmers Interface (API).
Docs The complete documentation is here.
Settings Common settings can be adjusted via the Settings dialog. All user controllers driver settings can be adjusted in the Command Line Utility.
Updates The UPDD Daemon, About box shows the version in use. Contact the driver supplier for any updates.
Commander The Commander application receives touch data from the driver API, performs the action associated with the incoming gesture and then posts the touch data into the OS as native touch events. It also acts as a TUIO server.
Docs The complete documentation is here. TUIO server documentation is here.
Settings The Commander settings can be adjusted in the gesture settings dialog.
Note – The ‘Click nearest clickable UI element’ in the Taps and Presses dialog is a useful setting to enable if you are using the touchscreen to select small buttons, such as the minimise, maximise and close buttons in standard application dialogs as these were not designed for touch screen usage.
Updates The Commander menu bar item ‘Change History’ will show the version in use. Release notes can be found here.

Installation receipts

The UPDD installation will create package and subpackage receipts under /var/db/receipts.

The installer automatically installs either the signed driver subpackage or the unsigned driver subpackage and there will only ever be a receipt for one of the two. In 10.9 and later there will be a receipt for the signed driver and in 10.7 and 10.8 there will be the receipt for the unsigned driver.

Therefore, following installation there will be receipts as follows:

  • com.touch-base.pkg.updd
  • com.touch-base.pkg.updddriversigned  (10.9 and above)
  • com.touch-base.pkg.updddriverunsigned (10.7 and 10.8)
Search