TiViPE library and module creation How to create an own software library that

TiViPE has been created originally keeping in mind that users had created a library and wanted to use the available routines of the library within TiViPE without additional programming.

Many TiViPE users however start using TiViPE and the graphical icons, and find it an easy way to program until, they meet the moment that the graphical icon/module they have in mind to use does not exist. So far they never considered even to create a new module, but as soon as a new module needs to be created it is very likely that the required routine call needs to be programmed as well.

Two simple module examples called TVPhelloworld and TVPcopy have been constructed and implemented in a library called TVPexample. All files for this library together with the two TiViPE example modules can be found in TVPlibraryExample.zip. This zipped file contains 7 files:

Readme.txt: to explain how a library is constructed and modules embedded.
TVPhelloworld.ci: TiViPE code information file with content of 10 tabloids.
TVPcopy.ci: TiViPE code information file with content of 10 tabloids.
src.pro: project file. Used to compile files to a ’TVPexample’ library.
TVPexampledefs.h: header file to take care of dll import and export.
TVPexample.h: header file with c++ class TVPexample. The class contains 2 routines: TVPhelloWorld and TVPcopy.
TVPexample.cpp: a c++ source code file with the mplementation of the above 2 routines.

We assume that the user is familiar with or has some basic knowledge of C or C++ programming. Files TVPexample.cpp and TVPexample.h contain the implementation of the routines void TVPhelloWorld () and Data5D TVPcopy (Data5D d).

Note that this example and its code is available in the distribution.

Library construction

The files src.pro, TVPexample.cpp, TVPexample.h, and TVPexampledefs.h make up the source files for the library. Create directory $MYTVPHOME/Libraries/TVPexamples/src for Unix or %MYTVPHOME%\Libraries\TVPexamples\src for windows, and in copy the above 4 files to this directory.
In Windows start a command window (cmd.exe) and goto your TiViPE home directory (C:\TiViPE). Here type

vars.bat
cd %MYTVPHOME%\Libraries\TVPexample\src
qmake
nmake

or for Unix type

cd $MYTVPHOME/Libraries/TVPexample/src
qmake
make

to compile the library. The resulting library can be found in directory %MYTVPHOME%\lib or $MYTVPHOME/lib for windows and Unix, respectively.

Exporting routines for Microsoft Windows

Windows platforms make use of dll (dynamic link library) export and import. In the TVPexample library we made use of TVPEXAMPLE_LIB. It is recommended to create a name in caps that is the same as the name of your library. Note to set this properly in your ...defs.h file.
As for the header files in this case only TVPexample.h be sure to have included:

#include <TVPexampledefs.h>

and start every class with:

class TVPEXAMPLE\_EXPORT ...

The export definition is given in your project file called src.pro it is as follows:

win32-msvc*|win32-icc {
DEFINES += TVPEXAMPLE_LIB
}

Creation of TiViPE modules

A new TiViPE module is created by pressing starting TiViPE and typing Ctrl-N or by selecting create

File->Module->New.

A window pops up where an (M) field needs to be filled out and a ”New module name” which is a unique name needs to be given. After pressing the ok button an new window pops up with 10 tabloids. Six of these tabloids are used for communication and four are used to describe the routine call used. When ok is pressed in this tabloid, all data is saved to a so-called ”code information” file. Pressing the help button provides extensive help on creation and modification
of a module.
Two of these files, TVPhelloworld.ci and TVPcopy.ci are described below.

HelloWorld

The ”hello world” example uses the routine call:

void TVPexample::TVPhelloWorld ()

form the compiled TVPexample library. In the code information file the library and location need to be given, a header file where the routine is given, a description of the parameters used, and the class plus routine call need to be provided. These are all the elements required to embed a routine call into TiViPE:

tabloid libaries: -L$(MYTVPHOME)/lib -lTVPexample
tabloid includes: $(MYTVPHOME)/Libraries/TVPexample/src:TVPexample.h
tabloid GUI: is empty since there is no argument given nor any return value required.
tabloid routine: TVPexample::TVPhelloWorld

Copy

The “copy” example uses the routine call:

Data5D TVPexample::TVPcopy (Data5D d)

it requires the description of an input and an output parameter. Hence the main difference is in the GUI and of course the routine call itself:

tabloid libaries: -L$(MYTVPHOME)/lib -lTVPexample
tabloid includes: $(MYTVPHOME)/Libraries/TVPexample/src:TVPexample.h
tabloid GUI:
- Input("Input", "-in", DATA5D, DATA5D_ANYTYPE) [1];
- Output("Output", "-out", DATA5D, DATA5D_ANYTYPE) [F];
tabloid routine: TVPexample::TVPcopy

The GUI contains one input and one output. To set the arguments properly, the indices are provided [1] for first argument and [F] for function return parameter. The syntax of the GUI is quickly learned by using the available buttons in the GUI tabloid. Clicking these buttons gives a pop up window, where the syntax is described in detail. The syntax of the GUI parameters is described extensively in the documentation that is found by pressing the help button in the tabloid window.

Debugging

Within TiViPE itself there is no way to debug code as you are used to do. The reason is that there is no textual code within TiViPE that is coded by human. TiViPE makes use of internal code generators, so no opportunity to touch code at this level. The aim of TiViPE was to integrate existing (and tested) library calls into TiViPE. Graphical debugging is easy you see a module crash. Once you use graphical modules and merge them to new modules you rarely encounter an error, there is the true advantage of graphical programming in combination with code generators.
Nevertheless a module that has been created might crash. Most of the time this is in the routine you just developed and the crash occurs somewhere in the textual library. How to debug?
As example the TVPexample library is taken where two simple module examples called TVPhelloworld and TVPcopy have been constructed and implemented in a library called TVPexample, as explained before.
Uncomment the line 23 in the file TVPexample.cpp:

//#define TVPEXAMPLE_DEBUG

by removing the two slashes. Save the file and recompile the library by typing nmake on a windows OS or make on unix or mac. After every routine call a print statement is given.
When running Microsoft Windows you might see not anything until the module is compiled with a console option enabled. For instance, the created TVPcopy module is stored in

%MYTVPHOME%\Modules\<Entryname>\TVPcopy\src

Next open file src.pro and for windows remove the sharp (#) to enable the console

# CONFIG += console

save the file and open a command window (cmd.exe) and compile the module
c:\TiViPE\vars.bat

cd %MYTVPHOME%\Modules\<Entryname>\TVPcopy\src
qmake
nmake

Rerun the module/icon TVPcopy within TiViPE. The module will print “TVPexample::TVPhelloWorld” every time the module is being executed. This output is found, by clicking the lower right rectangle in the graphical icon.

Debugging without TiViPE

A module can be debugged using the standard debug tooling used in for C/C++. This is done by

compiling your library in debug mode by editing the src.pro file in your module directory by removing sharps from CONFIG += warn_on and CONFIG += debug and comment CONFIG += release by placing a sharp (#) at the beginning of the line.
compiling the module in debug mode also by editing the src.pro module in the same way.
run TVPMTVPcopy (Every TiViPE module is prefixed with TVPM.) with a bunch of parameters from your preferred debugging tool.

TiViPE library creation

Yet another example of how to create a library and a module. This case is similar to the former example, but creates an example that can be used as a robot specific module for instance to control a NAO robot.

A module called TVPstateExample has been constructed and implemented in a library called TVPstateExample. All files for this library together with the two TiViPE example modules can be found in TVPstateExample.zip. This zipped file contains 6 files:

Readme.txt: to explain how a library is constructed and the TVPstateExample module embedded.
TVPstateExample.ci: TiViPE code information file with content of 10 tabloids.
src.pro: project file. Used to compile files to a ’TVPstateExample’ library.
TVPstateexampledefs.h: header file to take care of dll import and export.
TVPstateexample.h: header file with c++ class TVPstateExample. The class contains 5 routines, required to used the TVPcommandStateStringExampleSCIS routine.
TVPstateexample.cpp: a c++ source code file with the implementation of these 5 routines.

The files src.pro, TVPstateexample.cpp, TVPstateexample.h, and TVPstateexampledefs.h make up the source files for the library.

Create directory $MYTVPHOME/Libraries/TVPexamples/src for Unix or %MYTVPHOME%\Libraries\TVPexamples\src for windows, and copy the above 4 files to this directory.
In Windows start a command window (cmd.exe) and goto your TiViPE home directory (C:\TiViPE). Here type

vars.bat
cd %MYTVPHOME%\Libraries\TVPexample\src
qmake
nmake

as partially illustrated in Figure 1.

Figure 1: Compiling a library using the command line tool cmd.

For Unix type

cd $MYTVPHOME/Libraries/TVPexample/src
qmake
make

to compile the library. The resulting library can be found in directory %MYTVPHOME%\lib or $MYTVPHOME/lib for windows and Unix, respectively.

Exporting routines for Microsoft Windows

Windows platforms make use of dll (dynamic link library) export and import. In the TVPexample library we made use of TVPSTATEEXAMPLE_LIB. It is recommended to create a name in caps that is the same as the name of your library. Note to set this properly in your ...defs.h file.
As for the header files in this case only TVPstateexample.h be sure to have included:

#include <TVPstateexampledefs.h>

and start every class with:

class TVPSTATEEXAMPLE_EXPORT ...

The export definition is given in your project file called src.pro it is as follows:

win32-msvc*|win32-icc {
DEFINES += TVPSTATEEXAMPLE_LIB
}

The library requires header files from the TVP and TVProbotics libraries, in the project file therefore the following include paths

INCLUDEPATH   = .
INCLUDEPATH  += $(TVPHOME)/Libraries/TVP/src
INCLUDEPATH  += $(TVPHOME)/Libraries/TVP/TVPextension/src
INCLUDEPATH  += $(TVPHOME)/Structures/src
INCLUDEPATH  += $(TVPHOME)/Libraries/TVProbotics/src

and libraries

LIBS          = -L$(TVPHOME)/lib -lTVP -lTVProbotics

are required.

Creation of a TiViPE module

A new TiViPE module is created by pressing starting TiViPE and typing Ctrl-N or by selecting create

File->Module->New.

A window pops up where an (M) field needs to be filled out and a ”New module name” which is a unique name needs to be given, as illustrated in Figure 2.

Figure 2: Construction of a new TiViPE modules called TVPstateExample.

After pressing the ok button an new window pops up with 10 tabloids. Six of these tabloids are used for communication and four are used to describe the routine call used. When ok is pressed in this tabloid, all data is saved to a so-called ”code information” file. Pressing the help button provides extensive help on creation and modification of a module. In the next section the content of the tabloids is provided.

TVPstateExample

The full content of TVPstateExample is given in the file TVPstateExample.ci, the user can copy and paste the text used in this file in the tabloids, as illustrated in Figure 3. The first six tabloids are documentation.

The ‘Libraries’ tabloid contains the path to the created library, since the created library is stored in the MYTVPHOME/lib directory, and the paths to TVPHOME/lib are included by default, the only library and path to be included is the TVPstateExample library.

The ‘Includes’ tabloid contains the path to the TVPstateexample.h where the class and routine call are declared.

The ‘Routine’ tabloid contains the name and class of the routine used.

The ‘GUI’ tabloid describes all parameters used in the routine call, the order of these parameters is given by a number between square brackets.

(a)
(b)
(c)
(d)
(e)
(f)
(g)
(h)
(i)
(j)