Driver debugging

There can be many reasons why touch is not working such that it is necessary to gather information from the system to aid analysis of the problem.

Driver not loading

In rare cases the issue could be that the driver fails to load in which case we need to know why this should be.

The installer process configures the driver to load automatically so driver loading is normally a silent background process hidden from view.

However, if the driver does not load it also means that the driver's API is unavailable so all client applications with fail to connect with the driver.

In the case of UPDD Console it will show the error 'No driver connection'.

Running 'upddutils' command line utility will fail with the error 'Unable to open connection to driver'

In this situation you can manually invoke the driver in a command window and observe any error messages issued when running the driver.

The command to run the driver in the various operating systems is as follows:

 If it fails to load the error should be seen in the command window.

Driver loading 

If the driver is loading OK but touch is still failing then it is important to understand what the driver is doing at the time the issue occurs.

To this end, UPDD V6 has a number of debugging logging facilities built into the driver.

Session logging

To create a debug log for a given session you can enable the file debugging facility via the internal driver setting filedebug as follows:

Command : upddutils filedebug n where n equals:

When enabled, debug data is logged in the updd log file updd.log as created anew or appended to an existing log file if it exists so you may wish to delete a previous log file.

Unless otherwise informed we normally require a log from the command 'upddutils filedebug 3', wait 5 seconds and then touch the screen.

In some operating systems you may need to disable logging to be able to access the content of the log.  Logging is disabled once the session closes, e.g if the driver is stopped or a reboot occurs.

Example

This log shows the point at which a USB read (issued by the driver) fails and the driver resets the USB bus and retries the read.

2017/01/12-08:38:23: TRC: VID:0x457 PID:0x1056 is supported by this UPDD package
2017/01/12-08:38:23: TRC: USB location bus:001a-port:0002
2017/01/12-08:38:23: TRC: Location already connected
2017/01/12-08:38:23: TRC: Found VID:0x5ac PID:0x8215
2017/01/12-08:38:23: TRC: Found VID:0x819 PID:0x101
2017/01/12-08:38:23: TRC: Found VID:0x88e PID:0x5036
2017/01/12-08:38:23: TRC: Enumeration ends
2017/01/12-08:38:24: DBG: updd-tuio Registered callbacks 0x0
2017/01/12-08:38:24: DBG: updd-tuio Registered callbacks 0x0
2017/01/12-08:38:24: DBG: updd-gestures Registered callbacks 0x0
2017/01/12-08:38:24: DBG: updd-gestures Registered callbacks 0x0
2017/01/12-08:38:25: DBG: updd-tuio Registered callbacks 0x0
2017/01/12-08:38:25: DBG: updd-tuio Registered callbacks 0x0
2017/01/12-08:38:26: ERR: USB error: (read) Input/Output Error
2017/01/12-08:38:26: DBG: Issuing clear halt and retrying

In this case the driver will retry the reset 5 times before notifying that the device is 'disconnected'.

USB interface errors are shown as 'Status =', such as 'Status = -9' as returned from LIBUSB.

Alternative log file path

In some OS, such as Android, if the default log file location is unavailable set the environment variable UPDDLOGPATH to the target folder before running enabling logging,  e.g.

export UPDDLOGPATH=/data/alternatelogpath/
./upddenv ./upddutils filedebug 3

N.B. do not omit the trailing slash.

Startup logging

For logging to be permanently enabled over all driver sessions, to enable API logging and to log additional operational information you need to enable permanent logging.

If using UPDD 6.1.396 or above use the command line utility to enable / disable boot logging.

For earlier versions, you need to create the driver's bootstrap file, updd.ini, and add the content:

[updd]
logerrors=y
logdebug=y
logtrace=y

As per this Windows example:

optionally, we may also request that you set these other options

logsql
logdebughigh
logconsole
logtrace

This is useful to log errors that are occurring in a UPDD API based program.

You can download a pre-defined updd.ini file from here - Windows, MacOS, Linux.

The bootstrap file must be placed in the following folder:

The log file is placed in

Log files

The log files upddapi.log and updd.log will be created in the same folder as the bootstrap file, as seen in the above Windows example.

Remember to delete these entries/file to disable logging otherwise eventually a massive file will be created!

API client programs

Starting with build 7.1.155 there are several changes to api logging.

The log files for api based programs take the name of the parent program eg, updd test.log.

On MacOS the log files for api based programs are written to ~/Library/Preferences/updd/log

These files are captured in a standard updd diagnostic.

After enabling api logging the client program(s) to be logged should be restarted.

Note that on Windows the client program must be run “as administrator” so the program has the required access to write the log files.

Either locate the program within c:\program files\updd, right click and 'Run as Administrator
or
run the program in an administrator CMD window as per this example: