Quick installation guide

Welcome to the Mac OS X Quick Installation Guide which covers the key elements for installing the UPDD Mac OS X version 6 that supports Mac OS X 10:7 thru Ventura 13.x, and version 7 that supports 10.14 thru Sonoma 14.x.

The software is installed from an application contained within the supplied .dmg file. You just run the .dmg file and follow the instructions.

If your system is controlled by remote management software it is likely there are restrictions placed on driver installations that block kernel / system extensions. If this is the case please check out our notes on MDM Configuration considerations. These notes also indicate how to extract the .pkg file embedded in the installer  application.

Please be aware that if you are upgrading to a newer version of UPDD V6 and you have a personal license the installer checks the warranty expiry date on the licence prioy to begining the installation. If your software is out of warranty the install will cease and issue this message: "Your UPDD warranty has expired. Upgrading to this version is not permitted". Please contact sales@touch-base.com to purchase a license upgrade.

During the installion procedure the OS security is likely to ask you to allow the software to be installed.

At the end of the install the touch should be working. If this is not the case, or touch is not performing as expected, please see the troubleshooting guide here.

The rest of this document covers the installation procedure in greater detail.

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 extensions. All 3rd party extensions 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 kernel extensions (kext) 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 kernel extension is now installed in 10.9 and above. Only 10.7 and 10.8 use the old kext file. Further, since 698 we use a new system extension (dext) that is installed in 10.15 and above. These installation notes have been updated to show the additional manual installation approval 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. Since version 704 we have made changes to the manner in which we manage system extensions and by in large this has reduced the number of system / kernel extension installation issues.

Installing over an existing installation

This UPDD Commander utility, part of the driver installation, 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 kernel / system extension file to be installed and give accessibility permissions to our applications.

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 either load up a UPDD Installer app, to check license warranty status, or directly expand to a package file updd_n_n_n.pkg
(this step may be invoked automatically when downloading the .dmg file).

The Install UPDD checks whether the installer is being used to update an existing driver and if the update is within the driver's maintenance period. If outside the warranty period the install will be blocked (as shown) otherwise the .pkg file will be presented to continue with the installation.

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.

When installing on macOS 13 you will see this notification that can be safely dismissed:

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:

macOS 10.13 - 12.x	macOS 13 and above

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.

For macOS13 selecting the Open System Settings opens the new System Settings app to the correct section and shows the button to click to grant our extension permission to load.

macOS 10-13 - 12.x	macOS 13 and above

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.

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 these examples showing the UPDD components that have been granted permission.

The '+' control can be used to add a component. UPDD and UPDD Commander reside in the UPDD application folder /library/application support/updd.

Please check the component to be granted permission:

macOS 10.9 - 12.x	13.x

 macOS 10.7/10.8

For these earlier versions the instructions are:

1. Open System Preferences
2. Click Accessibility
3. Check the box for "Enable access for assistive devices"

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

Should UPDD Commander issue any warning messages at startup, such as '...failed to set up keyboard event filtering and cannot run' it could be that the enabled 'UPDD Commander' relates to an old version. This being the case use the '-' option to delete Commander from the permissions list and readd the application as located in folder /library/application support/updd.

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. A reboot will be necessary in the following cases:

• When installing in Big Sur for the first time.
• 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)