Linux source option

There are potentially two sets of costs involved.

1. The cost of the source code – which we do not distribute under a GNU GPL license. Our license allows you full access to the source code for your own use as you see fit, including modifications, and caters for unlimited distribution with your systems, hardware etc. The license fee includes adding support for the touch device support in your project. It does not allow for onward distribution of the source code.
2. Cost of any modifications required to satisfy your requirements not covered by the license fee, such as a touch interface method not supported or specialised requirements, such as a new operating system.

Copyright

This document describes the current implementation of our source offering, initially for Linux. Others will be documented as appropriate.

Linux

Our standard Linux driver installs binary modules and this is very useful for pre-configured Linux systems, non technical user, UPDD API interface, multiple controller support, simple installation etc. However, we recognise that some Linux integrations require the driver to be available in source code. To this end we have written an extensible source solution that can be modified to interface with Linux touch implementations as requested. This driver is made available, at a cost, to touch screen manufacturers and integrators on a per request basis.

Release Notes

Linux has a number of touch interfaces such as X – single and multi touch, TSlib, TUIO, evtouch, evdev and others. Then of course there are the 100’s of different touch protocols implement by different touch devices. These release notes reflect the support we have implemented with each release:

Deliverables

Interfaces

Tslib

X

The X Window System (commonly known as X or X11) provides a windowing layer and manages the pointer device.

We have written an X interface to generate system pointer motion and mouse click emulation.

Virtual HID

Creates a Virtual touch device and passes stylus data via this device.

Library utilisation

ACE

ACE is a low level inter process communication library used by the driver and its modules. For basic processors, such as X86, we can supply the ACE library in binary format if required.

Download from the LibACE Web page

OPDD uses ACE lib 5.6.2

This is considered an old version of the ACE library which is currently available from

http://download.dre.vanderbilt.edu/previous_versions/ACE-5.6.2.tar.gz

A convenient way to get this file is

wget http://download.dre.vanderbilt.edu/previous_versions/ACE-5.6.2.tar.gz

Build instructions are here http://www.dre.vanderbilt.edu/~schmidt/DOC_ROOT/ACE/ACE-INSTALL.html
There are compatibility issues with later versions of ACE so it is likely that ACE libraries supplied as part of a Linux distribution are unlikely to be compatible.
One customer reported patches (with GCC 4.4.4) were needed before they were able to build ACE.

Another customer had issues building the ACE library in their environment and based on these issues we make these recommendations:

1)    ACE offers two build methods, autoconf and traditional. We generally find the traditional makefile method works best.
2)    If using the traditional makefile method then we suggest config-linux.h be used unless there is a more obviously relevant header for your target.
3)    Some C++ compilers have trouble compiling the “dirent” functions. If compilation errors are seen that reference dirent then please use the patched file here.
4)    Add the following macro to the start of config.h. This excludes an un-needed part of the ACE library that gives compile issues in some cases.

#define ACE_HAS_POSITION_INDEPENDENT_POINTERS 0

5)    If compiling on an unusual target using the traditional makefile method you might need to make changes to the ACE option macros to enable the software to build correctly.

Centos 7

The following specific configurations were found to be needed to build ACE on Centos 7

1)      Create an empty file /usr/include/stropts.h
2)      In config.h add the following

#define ACE_LACKS_STROPTS_H
#undef ACE_HAS_STRBUF_T
#undef ACE_SCANDIR_CMP_USES_CONST_VOIDPTR
#undef ACE_SCANDIR_CMP_USES_VOIDPTR
#define ACE_LACKS_STRRECVFD

LibUSB

If this library is not installed edit the file opdd.pro, to remove references to USB.

From opdd.pro remove
SOURCES += linuxusb.cpp
HEADER += linuxusb.h

And all occurrences of -lusb and OPDD_LINUX_USB

# cd libusb-1.0.0
# ./configure
# make
# make install
# ln  -s  /usr/local/lib/libusb-1.0.so.0  /usr/lib/libusb-1.0.so.0

These commands may differ depending on distribution. Complete configuration information is available from the libusb links or distribution suppliers.

Users of libusb should take care to comply with the terms of the GNU LGPL as it applies to the intended usage,  details are available from https://libusb.info/

QT library

Version 4 required:
4.6.3 was used in our initial development - this was available at https://www.qt.io/
4.7.1 was used for more recent deployments - https://download.qt.io/archive/qt/4.7/qt-everywhere-opensource-src-4.7.1.tar.gz

Configure build and install qt as follows:
./configure -opensource -no-webkit -nomake demos -nomake examples

gmake
gmake install

If it is necessary to download and build the library then building and configuration information is available from the suppliers.

Integration

TSlib

Integrate OPDD module into Tslib

This optional module is only required if tslib support is required. If you don’t know what this is you likely do not require it.

pluginexec_LTLIBRARIES = \
$(LINEAR_MODULE) \
            …
            …
            $(OPDD_MODULE) \
$(INPUT_MODULE)

opdd_la_SOURCES =          opdd.c
opdd_la_LDFLAGS =          -module $(LTSDN).

 “input_la_LDFLAGS =          -module $(LTSDN)”

AC_MSG_CHECKING([whether OPDD module is requested]) AC_ARG_ENABLE(input,AS_HELP_STRING([--enable-opdd],
                [Enable building of OPDD module (default=yes)]),
[opdd_module=$enableval],
[opdd_module=yes])
AC_MSG_RESULT($opdd_module)
AM_CONDITIONAL(ENABLE_OPDD_MODULE, test "$opdd_module" = "yes")

“AM_CONDITIONAL(ENABLE_INPUT_MODULE, test "$input_module" = "yes")”

If, as part of the OPDD integration, you make any changes to the ts_conf file, please be aware it is sensitive to unexpected spaces.

Configure OPDD Project

1.     Extract the opddxxx.tgz, e.g.
        cd ~
        tar -xzf opddxxxx.tgz

        You will need to decide where you want to install OPDD. The default location is “/opt/opdd”

        Note that on some systems we have seen permissions issues when extracting opdd.tgz.
        To avoid this extract opdd.tgz as root then execute the commands

        cd  opdd
        chown -R <yourusername> *

The next 2 steps are only required if tslib is used

Build OPDD Project

Running the software

X Interface

OPDD considerations for X

Users must have permission to be able to connect to the X.org server running on the machine otherwise the driver cannot make a connection to X and subsequently will fail to move the pointer. Further, OPDD needs to be executed by a user who has root permissions.

Running the software

User experiences

Notes

Serial Devices

Calibration

Utilities

General

Options that return data will output the value to stdio if not specified.

Specialised

Zytronic ZXY100 serial firmware setting updates

Application Programming Interface

OPDD supports a programming interface to allow client programs to communicate with the driver.

The API is implemented by the Client class and communicates with the driver using a TCP/IP link bound to localhost (127.0.0.1).

The driver supports a number of commands which are implemented in ./drier/command.cpp.

These are mainly for internal use and not documented. A programmer can use this (and the corresponding client side code in the supplied source) to extent the API as needed.

The supported commands are encapsulated in the public methods of the Client class:

public Client::Client();
    The constructor for the client class.
    Takes no arguments.

public Client::~Client();
    The destructor for the client class.
    Any open session is closed and stream mode terminated (output is directed to the system mouse interface).

public int Client::open();
    Opens the TCP/IP link to the driver.
    Defaults to port 4142, but this can be altered in the.opdd.ini file if one exists in the working directory.
    Returns 0 for success, -1 for failure.

public bool Client::StartStreamTouch();
    Initiates stream touch mode. All touch data is directed to this client instead of the system mouse interface.
    Returns false in the event of an error.

public bool Client:: ReadStreamTouch(int& x,int& y,int& stylus,bool& touching
    Reads data from the touch stream (initiated by StartStreamTouch())
         Arguments
              x – returns the x co-ordinate for the current touch location
              y – returns the y co-ordinate for the current touch location
              stylus – for a multi touch controller returns the stylus number (0 for non multi-touch)
              touch – returns true if contact is currently taking place
         Returns true if data is returned.
         This function is expected to be called in worker thread and returns false ever second or so to allow an opportunity for thread termination.

public bool Client::WriteEEPROM(int aDevice, int address, int length, const unsigned char* data);
    If the device identified by aDevice supports eeprom writes then the data of specific length is written to the address specified.
    The meaning of “address” and the valid values will be dictated by the controller implementation.
    NB opdd currently only supports a single device, so aDevice must be 1.

public bool Client::ReadEEPROMProlog(int aDevice, int address, int length);
    If the device identified by aDevice supports eeprom reads then a read operation for data of specific length at the address specified is initiated. The caller should wait for the completion of this operation using the “eepromcalstate” command, then use ReadEEPROMEpilog to complete the read.
    The meaning of “address” and the valid values will be dictated by the controller implementation.
    See oputils source code for a detailed example of the use of this api.
    NB opdd currently only supports a single device, so aDevice must be 1.

Public bool Client::ReadEEPROMEpilog(unsigned char* data);
    Complete a read operation initiated by Client::ReadEEPROMProlog(). The data  is copied to the addressed by the data argument.
    This must be a caller provided block of memory of (at least) the size specified by the length argument to Client::ReadEEPROMProlog()

Example code

ACE_THR_FUNC_RETURN ReadThread(void* aArg)

{
  Client client;              // construct a client interface object
  if(client.open() == -1)     //open a connection with the driver
  {
    return(0);                // something when wrong, bale out
  }
  if(!client.StartStreamTouch())    // start touch mode
  {
    return(0);                // something when wrong, bale out
  }
   while(theRunReadThread)
  {
    TouchEvent* t = new TouchEvent;
    if(client.ReadStreamTouch(t->x,t->y,t->stylus,t->touching))   // read the touch data
    {
      QApplication::postEvent( (QWidget*)aArg, t);                // do something with the data read
    }
    else
    { // in the idle state ReadStreamTouch() will return false every second or so to allow thread termination to take place
     }
  }
  return(0);
}

Example program

An example program is available to illustrate the use of the touch stream mode.
Scribble, located in ./examples/scribble, is an adaptation of the Qt scribble example.
Full instructions to build Qt examples are available in the Qt documentation, but generally you will use the following commands from the scribble directory

qmake
make (or nmake on Windows)

Run the application to see the application shown below. This is a multi touch aware drawing application.

The current example supports a maximum of 2 touches, but the API itself is unlimited.

Contact

For further information or technical assistance please email the technical support team at technical@touch-base.com