|
Revision
1.7 19th April 2013 www.touch-base.com\documentation\installation
SPDD – Source driver |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Linux:- |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Originally
launched as OPDD (Open Pointer Device Driver) for Linux this driver has now
been renamed to SPDD (Source Pointer Device Driver) for two reasons; 1: the
term ‘Open’ can often mean ‘Open source – available to all under open source
licence” and our driver is not open in this sense and 2: the source code can,
in theory, be made available for any OS, not just Linux. This
driver is available for environments where a source driver is required rather
than the binaries installed with the standard UPDD driver. The driver could be made available for any
OS but is currently only available for Linux.
Should a source driver be required for a different OS please contact
us to discuss your requirements. Costs
There are potentially two sets of costs
involved.
Please contact Sales, sales@touch-base.com,
to discuss your specific requirements. The source code and deliverables will
be tailored to your exact needs. CopyrightThe source code is supplied under licence to be used in systems
directly associated with the purchaser of the license or its subsidiaries and
customers. The source is
not supplied under
a GNU GPL license and
therefore should not be made available to a wider audience. Each source module carries the following
copyright notice that should not be removed: /* 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
The
full driver suite is delivered in a compressed file opdd.tgz and consists of
the following files:
Only
those modules relevant to your requirements will be delivered. The software
is distributed in source form. You will need to compile the software and
libraries for the target system. Interfaces
Tslib
The initial paragraph at the Tslib
web site states “Tslib
is an abstraction layer for touch screen panel events, as well as a filter
stack for the manipulation of those events. It was created by Russell King,
of arm.linux.org.uk. Examples of implemented filters include jitter smoothing
and the calibration transform. Tslib is generally used on embedded devices to provide a common user
space interface to touch screen functionality. It is supported by Kdrive (aka
TinyX) and OPIE as well as being used on a number of commercial Linux devices“ We have written the modules
required to interface touch hardware to the Tslib abstraction layer so that
any Tslib based Linux distribution or Tslib based applications will function
as expected. 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
OPDD
utilises a number of software libraries:
You
must install the relevant libraries on your Linux development system as
outlined below. ACEACE 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. To install ACE if
supplied with OPDD:
Note that you will need to copy the ACE library (ACE_5.6/ACE_wrappers/ace/libACE.so.5.6.0) to a directory already included in the library search path (e.g. /usr/local/lib) or to a directory that you add to the search path yourself (e.g. the OPDD install directory). 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/ 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. 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. USB libUtilised when
handling USB devices - libusb 1.0.x required. Version 1.0.6 was used in our
development. This library may be supplied as standard as part of the Linux
distribution as many recent Linux distributions have started shipping this
library by default on their CD/DVD image. You may still need to select and install the
library from the CD/DVD/Internet repository The software is available at http://sourceforge.net/projects/libusb/files/libusb-1.0.
Web site is http://sourceforge.net/projects/libusb/develop You will require gcc version 4.0.0 or later to compile this library.
Extract the library source code and then run the required commands to configure,
compile and install the library from the main library folder. The command
sequence is typically: # 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 http://www.libusb.org.
QT libraryUtilised by the calibration and general utilities program. Version 4 required – available at http://qt.nokia.com/.
Version 4.6.3 was
used in our development. This library may be supplied as standard as part of the Linux
distribution. If using the Qt4 library distributed then it may be necessary
to modify the file "oputils/Makefile.am" to change the search path
for the Qt header files and libraries. If it is necessary to download and build the library then building and configuration information is available from the suppliers. Intergration
TSlibIntegrate OPDD module into Tslib 1. Copy the file “opdd.c” to the
“plugins” subdirectory within your tslib source tree. 2.
Modify the file “plugins/Makefile.in to add the following lines: 3.
Modify the line “pluginexec_LTLIBRARIES = \ …..”
to add “$(OPDD_MODULE) \” E.g. pluginexec_LTLIBRARIES = \ $(LINEAR_MODULE) \ … …
$(OPDD_MODULE) \ $(INPUT_MODULE) -Add the lines:- opdd_la_SOURCES =
opdd.c opdd_la_LDFLAGS =
-module $(LTSDN). You should put the above lines after the line
which reads: “input_la_LDFLAGS
= -module $(LTSDN)” 4. Modify
the file “configure.ac” in the root of the tslib source tree to add the
following lines:- 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") You should add the above lines after the line: “AM_CONDITIONAL(ENABLE_INPUT_MODULE, test
"$input_module" = "yes")” 5. You
can now follow the tslib instructions to build and install the library,
plugins, and demo programs. (e.g. ./autogen.sh && configure
&& make && make install) 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. Uncompress
the file “opdd.zip” into a directory on your system. eg /usr/src -You will
need to decide where you want to install OPDD. The default location is
“/opt/opdd” 2. Open
the file “driver/linuxtslispointer.cpp” and find the line : #define TSLIB_COM_PIPE "/opt/opdd/tslibPipe". 3. Modify
this to reflect your installation location. Build
OPDD Project 1. Open a
terminal 2. Change
to the scripts directory in the source tree. eg “cd opdd/scripts” 3. Type
“perl build.pl Full” to generate a full build (clean, rebuild automake files,
build). or “perl build.pl Partial” to do a partial build (build). If any
errors occur you can check the file “opdd/build-master-linux.log” to find out
more detail (the output is also in ./<project>/.tmp.log.) 4. The
“opdd” binary will be copied to the “opdd/release_linux” directory. You
should copy this file to the installation directory you chose in the previous
section. 5. Copy
the .opdd.ini file to the installation directory. Running
the software OPDD
can be executed in any manner that is appropriate to your implementation -
subject to any limitations imposed by the interface). Typically,
to run the OPDD driver type <installdir>/opdd” e.g. “/opt/opdd/opdd” To run
any of the tslib demo programs you must set the input device first. You do
this by typing the following command into the terminal:- “export
TSLIB_TSDEVICE=/opt/opdd/tslibPipe” You can
change the “/opt/opdd” section in the above command to reflect the
installation path you have chosen. You can now run any of the tslib demo
programs. eg “ts_print”, “ts_demo”, etc. To calibrate, run the demo program
“ts_calibrate”. For
more information about these demos see the tslib documentation. 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. Configure
OPDD Project Uncompress
the file “opdd.zip” into a directory on your system. eg /usr/src -You will
need to decide where you want to install OPDD. The default location is
“/opt/opdd” Build
OPDD Project 1. Open a
terminal 2. Change
to the scripts directory in the source tree. eg “cd opdd/scripts” 3. Type
“perl build.pl Full” to generate a full build (clean, rebuild automake files,
build). or “perl build.pl Partial” to do a partial build (build). If any
errors occur you can check the file “opdd/build-master-linux.log” to find out
more detail. 4. The
“opdd” binary will be copied to the “opdd/release_linux” directory. You
should copy this file to the installation directory you chose in the previous
section. 5. Copy
the .opdd.ini file to the installation directory. Running
the software OPDD
can be executed in any manner that is appropriate to your implementation -
subject to any limitations imposed by the interface. The following notes are for guidance and
refer to implementing on "standard" platforms. For convenience we
supply a script to allow autolaunch of OPDD under X. The
file "driver/startopdd" should be copied to the install directory (e.g./opt/opdd)
and made executable (chmod 755 /opt/opdd/startopdd). The
file /opt/opdd/opdd should be given root permissions ("chmod +s
/opt/opdd/opdd") If X
is only being used by a single user (in the case of a media player device,
etc) then: The
"$HOME/.xinitrc" of the user who will be running X should be
modified to add the line "/opt/opdd/startopdd &" If X
is being used by many users and will be using a display manager then: The
file "/etc/gdm/Init/Default" should be modified to add the line
"/opt/opdd/startopdd &" at the end. User experiences
Useful
user feedback or comment is documented here:
Notes
Serial DevicesYou can
configure the serial port that your touch screen is attached to by modifying
the .opdd.ini file and changing the “port=ttyS0” line. E.g. to connect to the
second com port change the line to “port=ttyS1” Settings file The
settings file opdd.ini contains the settings used by the driver. These are
documented below:
Calibration
A number
of calibration options are available under Linux and will be utilized with
OPDD as required.
Utilities
General
The general utility is called
"oputils". This module implements utility functions as required. This
utility uses the QT4 library. If using the Qt4 library distributed as part of
the Linux distribution then it may be necessary to modify the file
"oputils/Makefile.am" to change the search path for the Qt header
files and libraries. Running
oputils with no argument lists current options. Pass the function parameter as required:
oputils [parameter], e.g. optuils writeeepromcal. Options that return data will output the value to stdio
if not specified.
Specialised
We also
can supply / develop source utilities as required. This section lists
available specialised utilities: Zytronic ZXY100 serial firmware setting updatesUtility used to update firmware
settings in the Zytronic ZXY100 serial controller. This is supplied when
using the ZXY100 serial controller. The list of supported firmware
commands is:-
options that take an optional numeric
value [n] will: #set the value if specified #output the current value to
stdio if not specified Application Programming InterfaceOPDD 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
The following code reads touch data in a worker thread. This is taken from the Scribble example described below. 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.
ContactFor further information or technical assistance please email the technical support team at technical@touch-base.com |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
