Mac

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.

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.

We have observered a few cases where the install failed:

1. Unable to terminate running driver
   One such detected failure 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 updd before installing
   
   In this instance it would appear that installer couldn't force updd (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 updd survived this request! However, it is likely that it did eventually quit as the user reported everything as working.
   
   
2. Application binary file did not have write access.
   Running UPDD installer requires that the current user has permission to access folder /usr/local/bin. If permissions on this file are corrupted or set to write only the install will fail as described here.

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:

Corrupted Kext file preventing install

A customer reported that UPDD failed to install. 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. Its possible that the kext is an earlier version and it doesn't work with later versions.

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

Kext load error preventing install

Kextcache error 71 return code seen when loading UPDD kext.

The install log showed that the kext had failed to load with the error:

2018-06-04 18:27:57-07 mil-dmv3mx1 installd[504]: kextcache: Kext rejected due to insecure location: <OSKext 0x7fbf3315f0d0 [0x7fff85660af0]> { URL = "file:///Library/StagedExtensions/Library/Extensions/tbupddmxhid.kext/", ID = "com.touch-base.tbupddmxhid" }

This is unusual in that we believe this to be the location used by MacOS to copy proper signed kernel extensions (from Library/Extensions) as part of the load process. This implies that MacOS rejected its own location during the load process.

SIP can be disabled / enabled using the csrutil command in recovery mode albeit you really need to address the underlying system issue.

To enable or disable System Integrity Protection, you must boot to Recovery OS and run the csrutil command from the Terminal.

1. Boot to Recovery OS by restarting your machine and holding down the Command and R keys at startup.
2. Launch Terminal from the Utilities menu.
3. Enter the following command:
   $ csrutil disable or enable 

Unable to boot system after installing UPDD

This has only been reported once. The system could be kernel panicking and if so there would be logs in /Library/Logs/DiagnosticReports, with a filename starting with "kernel".

Note this is the Library folder in the root of the hard drive.

In this case you can boot the Mac system in safe mode and then remove our driver and then see if any crash logs exist as suggested above.

Driver won't load after install

For whatever reason the UPDD settings database file did not get created during the install.  In this case touch did not work and the UPDD utilities menu bar icons show an exclamation mark in the log indicating that they could not communicate with the driver: .

In this instance a reboot recovered the situation.

MacOS 10.13 and above system extension issues

MacOS 10.13 introduced additional security features for the installation of system (kernel) extensions that affect the usage of .kext files. All 3rd party kexts now need to be explicitly allowed, regardless of whether they're signed with a valid key. This is explained further in our installation document but there have been cases where the installation of the new kext has failed in 10.13 and these notes explain possible resolutions.

Failure of the kext to load normally results in the UPDD Status dialog showing 'No devices found' despite the fact that the USB device is listed in the system and supported by the software.

We genuinely believe this to be a MacOS issue/bug in the way it is handling replaced or updated kext files. After all the UPDD components are placed on the system the kext file should be automatically activated as part of the install process. As a fail safe when the driver starts up it also issues a kext load request. Since UPDD version 6.0.315 the return code is retained in setting 'private.kextload.status' and shown in the settings section (report.txt) of the diagnostics report file. In failing situations we have seen return code 27. Further, the debug log (updd.log) will show the message:

2018/04/26-16:49:40: ERR: USB error: (claiming interface) Access denied (insufficient permissions)

In this case the kext load request return code is normally 27 and specifically means that the kext doesn't yet have permission to load from the user. It's related to the new macOS security features introduced in 10.13 and consequently only appears in macOS 10.13 and above.  Error code 71 is also occasionally seen indicating that a 'system error' is preventing our kext from loading, albeit the error message in the log still relates to 'insufficient permissions'. In this case it is likely that a corrupted kext file is preventing our driver from installing or the system has rejected the UPDD kext load request. Check the install log to see if this is the case.

You can also see the results of the installer's kextload request by running the command 'sudo kextload /Library/Extensions/tbupddmxhid.kext; echo $?' in a terminal window. If the kext permissions dialog hasn't appeared this should trigger it.

The 27 return code means that you need to either press the "Allow" button in the Security & Privacy system preferences as detailed here or it is also possible you are experiencing "the bug" where the security feature is broken and you cannot grant the kext permission to load without doing the steps detailed below:

Sometimes allowing our software such that the kernel extension is loaded and the kextload return code is 0 can still result in the driver failing to get access to the device and needs the further steps below to be considered.

Steps to overcome 'Access Denied' issue 

We have investigated a number of these cases and have always managed to find a solution by performing one or other of the steps below:

• If you have Installed on top of an old V6 driver we suggest you uninstall, reboot and reinstall. This seems to be the case that gives kextload status 0 with access denied.
• If you have trouble getting the kernel extension to show up in the security & privacy settings, you can try uninstall and reinstall - we believe this may also have resolved the issue in a number of systems especially in systems installing over UPDD V5 utilising a different kext file of the same name.
• Some users have reported rebooting 2 or 3 times and eventually the driver gets access to the device!

• Use the command to approve our kext using team id  
  
  1. Startup the Mac in recovery mode.
  2. Click the Utilities menu and select Terminal.
  3. Enter the following command:
     /usr/sbin/spctl kext-consent add U86H28HG4S
     Press Enter
  4. Close the Terminal app and restart

• Another driver developer shared this 'work round' with us that apparently works in some cases: 

1. Open "System Preferences", "Keyboard", "Shortcuts" tab
2. Set "Full Keyboard Access" to "All controls"
3. Open "System Preferences", "Security & Privacy", "General" tab
4. Press tab key until the "Allow" button is highlighted
5. Press space bar

This is essentially just using the keyboard to allow access. This has worked for us and is the preferential to the other more invasive options.

• Reinstall MacOS - this was undertaken by one customer and the software then installed correctly - extreme solution but it worked!
• Disable the new system extension security feature as described below. We have done this on systems where the system log reported numerous permissions issues with various kexts.

Disabling the kext consent feature​

Although this seems an extreme solution we are not overtly concerned in suggesting this as the kext consent isn't really necessary and we I don't think there's any other way to solve the issue short of reinstalling macOS!

1. First, you must reboot your system into the recovery environment. To do so, invoke a system restart and hold down the keys Command + R right before it reboots. Don't let go of the keys until you see the Apple logo or a spinning globe.
2. Wait for the system to reboot into the recovery environment. If it works, you should see a window like this:
   
3. Once that window appears, pick the Utilities menu in the menu bar, and then select "Terminal"
4. When the terminal window opens, enter the following command:
   spctl kext-consent disable
5. Open the Apple menu and pick "Restart" to reboot your computer.
6. Open a terminal Window and execute 
   sudo kextload /Library/Extensions/tbupddmxhid.kext
   
   UPDD should now be able to function as normal

• If none of the above work follow the above instructions to enter Recovery Mode and load the Terminal utility but this time disable the System Integrity Protection system altogether with the command 'csrutil disable'.
  Now reboot the system. Touch should now be OK. Once it is remember to re-enable SIP with the command 'csrutil enable' .

Permission granted but still no touch

A customer reported all permissions were granted by still no touch control.

The system security dialog showed UPDD Gestures (now replaced with UPDD Commander) had permission to control the computer and we could see that the gesture log confirms it was receiving touches and trying to control the mouse. However,  for some reason touch was being ignored.

These findings suggested that there are bugs with how apps are granted permission to control the computer. We concluded that our application wasn't promoting the access permission dialog because Apple's API was reporting that it had access but in reality that wasn't the case. Clearing it out from the list and re-adding it fixed the issue as per these steps:
 
1. Open System Preferences
2. Select "Security & Privacy"
3. Select the "Privacy" tab
4. Select "Accessibility" in the list on the left
5. Click the padlock icon and enter your admin password to unlock the settings
6. Find and select UPDD Gestures\UPDD Commander in the list of apps that are allowed to control your computer
7. Remove it using the "-" button.
8. Now select the "+" button.
9. Using the Finder window locate the UPDD Gestures \ UPDD Commander.
10. UPDD Gestures\Commander should reappear in the list of apps allowed to control your computer. Click the box to the left of it so that it is checked.