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++ classTVPexample
. The class contains 2 routines:TVPhelloWorld
andTVPcopy
.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
andCONFIG += debug
and commentCONFIG += 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 withTVPM
.) 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++ classTVPstateExample
. The class contains 5 routines, required to used theTVPcommandStateStringExampleSCIS
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)
Figure 3: Filling out the tabloids for TVPstateExample.
TVPstateExample module
The resulting TiViPE module is illustrated in Figure 4.
(a)
(b)
Figure 4: Resulting TiViPE module called TVPstateExample. (a) The module itself. (b) Parameter settings of the module.