transgen3/tutorial/demo-transgen3

This page explains how to build an OpenPRS demo supervisor using Transgen3 to control the GenoM3 module demo you created following this tutorial.

The resulting supervisor can be obtained with:

$ git clone git://trac.laas.fr/git/robots/demo-transgen demo-transgen-final
$ cd demo-transgen-final
$ git checkout genom3

But you should only do this if you want to skip most of this tutorial... Note: that it is the genom3 branch you will need.

What need to be installed?

You will need to install (if not already done), the following software. The preferred method is with robotpkg. We indicate (the robotpkg path / or the git repository):

openprs (robotpkg/supervision/openprs / git://git.openrobots.org/robots/openprs)
transgen3 (robotpkg/wip/transgen3 / git://git.openrobots.org/robots/genom3/transgen3)
genom3-openprs (robotpkg/wip/genom3-openprs / git://git.openrobots.org/robots/genom3/genom3-openprs)

OpenPRS is used to run the supervisor and execute the procedures/OPs.

Transgen3 will build the proper files to call the supervisor.

genom3-openprs is the template used by GenoM3 to produce the encoding/decoding functions, as well as the OPs to call a particular service of the GenoM3 module. Note that it produces code which use the client/c libraries (either the ROS one, or the Pocolibs one). In any case, OpenPRS will use the one installed at the time you run the module. So you can switch middleware without even recompiling the openprs/client. But you will need to use the same middleware for all the GenoM3 modules controlled by your supervisor.

We assume you already installed the module demo. If not, go back to this tutorial.

For this modules, you will need to instantiate and install the openprs/client. Either you have already given the openprs/client template in the --with-templates argument to the configure when installing these modules with one of these commands in their build directory:

$ ../configure  --prefix=${HOME}/openrobots --with-templates=pocolibs/server,pocolibs/client/c,openprs/client
$ make install

Note that if you want the ROS version, just type:

$ ../configure  --prefix=${HOME}/openrobots --with-templates=ros/server,ros/client/c,openprs/client
$ make install

or if the modules have already been installed (but not with the openprs/client template) you can also just do in the build directory):

$ genom3 openprs/client ../demo.gen
$ cd openprs/client
$ ./bootstrap.sh
$ ./configure  --prefix=${HOME}/openrobots
$ make install

Create a directory dedicated to your supervision system

$ mkdir demo-transgen
$ cd demo-transgen
$ mkdir user
$ touch user/configure.ac
$ touch user/Makefile.am

The user directory will contains the user specific code (basically the OPs you will write to control the modules). We will fill them with more files later.

Create a demo.tg file

containing:

supervisor demo {
        module: demo;
}

This declares that we want a supervisor called demo, to control the module called demo. The module and its proper client_c library are located using pkgconfig. So we assume your PKG_CONFIG_PATH is properly set.

Launch transgen3 on your tg file and install the supervisor

$ transgen3 demo.tg
Module demo.
Supervisor demo, demo.tg
perl ./demo.pl
directory auto created
directory autoconf created
auto/Makefile.am created
configure.ac created
auto/demo-superv.inc.input created
auto/demo-superv.input created
auto/demo-xsuperv.input created
Done.
$ ./bootstrap.sh 
autoreconf: Entering directory `.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal 
autoreconf: configure.ac: tracing
autoreconf: configure.ac: not using Libtool
autoreconf: running: /usr/bin/autoconf
autoreconf: configure.ac: not using Autoheader
autoreconf: running: automake --add-missing --copy --no-force
configure.ac:38: installing `autoconf/install-sh'
configure.ac:38: installing `autoconf/missing'
autoreconf: Leaving directory `.'
$ mkdir build
$ cd build
$ ../configure --prefix=$INSTALL_DIR
checking for pkg-config... /usr/bin/pkg-config
checking pkg-config is at least version 0.9.0... yes
checking for TRANSGEN... yes
checking for demo... yes
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking for a sed that does not truncate output... /bin/sed
configure: creating ./config.status
config.status: creating Makefile
config.status: creating auto/Makefile
config.status: creating user/Makefile
$ make install
...
...
...

At this point, you already have a supervisor with everything one need to control the module. It is still very basic, but you can play with it.

Launch your supervisor

You must start the two modules. I assume here you are using pocolibs as middleware:

$ h2 init
$ demo-pocolibs -b

If you want to use the ROS middleware:

$ roscore
$ demo-ros -b

and then type:

$ demo-xsuperv -a -A

You will see a window like this one popping up:

demo-xsuperv is a script which calls OpenPRS with the proper arguments which will load the proper files. The -a -A options tell OpenPRS to NOT connect to the message passer and NOT connect to the oprs-server.

You can then play with it (assuming you have launched the demo module) adding one of the following goals (Menu: Oprs->Add Goal or Fact):

(! (demo_GetSpeed demo))
(! (demo_GotoPosition demo (demo_GotoPosition_input (posRef 1.0))))
(! (demo_GotoPosition demo (VarArg (posRef -1.0))))

The VarArg form allows you to pass parameters in a much more compact way, using the name of the last field. In the possible case of name conflict, you will need to prefix with sufficiently discriminant field name (e.g. goto_position.x). Note also that the VarArg format does not require you to give optional arguments.

Improving your supervisor

In any case, this supervisor is rather useless, and we need to add at least a procedure to control the module in a smarter way. This is where the user directory becomes useful. The user directory contains a number of files which are "user" defined (OP, scripts) to "specialize" your supervisor. As said before, Transgen3 only synthesizes a number of .inc and scripts files which load and start a basic supervisor. But still, you need to specify the particular OPs you want to write to run the demo.

Go in the user directory (which only contains an empty configure.ac Makefile.am and Makefile.in, Makefile generated by the autotools).

$ cd user

If you are familiar with oprs tools, call the OP editor (ope) and recreate an OP such as this one in a file named demo-superv.opf. Note that ope is the op editor installed when you installed OpenPRS. If ope does not exist, most likely you did not properly install OpenPRS.

$ ope demo-superv.opf

if you are not familiar with oprs tools, just copy the demo-superv.opf file from the git version of this tutorial (see above how to retrieve it).

Without going into the details of OpenPRS, this OP is rather simple, yet it illustrates how can one supervise GenoM3 module. It will be called with the goal (! (demo-superv demo)) (the argument is the name of the controlled module).

When running first, in parallel it starts in parallel one thread waiting for (stop-superv) to stop the demo, one looping thread to move de the mobile from -1.0 to 1.0, one looping thread which sets a monitor when the mobile passes the position 0.0, one looping thread which change the speed from FAST to SLOW and back every 3 seconds, and one last loopsing thread which read the Mobile port and put the result in the database every 2 seconds. The demo stops when you add the fact (stop-superv) (see the branch in the OP waiting for this fact which then delete it, and fails the procedure).

To complete the setup, you need to create an oprs command file demo-superv.inc.input containing:

include "@SUPERVUSERDATADIR@/demo-superv.sym"
load opf "@SUPERVUSERDATADIR@/demo-superv.opf"

trace step opf "@SUPERVUSERDATADIR@/demo-superv.opf" on
trace text opf "@SUPERVUSERDATADIR@/demo-superv.opf" on
trace graphic opf "@SUPERVUSERDATADIR@/demo-superv.opf" on

an oprs symbol declaration file demo-superv.sym containing:

declare predicate demo-superv
declare predicate stop-superv

a script file named user-demo-superv.input (to call the autogenerated demo-superv script) containing:

@SUPERVBINDIR@/demo-superv -x "@SUPERVUSERDATADIR@/demo-superv.inc" $*

a script file named user-demo-xsuperv.input (to call the autogenerated demo-xsuperv script) containing:

@SUPERVBINDIR@/demo-xsuperv -x "@SUPERVUSERDATADIR@/demo-superv.inc" $*

and finally, edit the Makefile.am and include this in it:

bin_SCRIPTS = user-demo-xsuperv user-demo-superv

DATA_FILE = demo-superv.inc demo-superv.opf demo-superv.sym

DATAROOTDIR = $(datarootdir)/superv/user

supervdatadir = $(DATAROOTDIR)
dist_supervdata_DATA = $(DATA_FILE)

%: %.input ../config.status
        $(SED) \
        -e 's|@SUPERVBINDIR@|$(bindir)|' \
        -e 's|@SUPERVUSERDATADIR@|$(DATAROOTDIR)|' \
        $< > $@

The various *.input files are modified by the installation to take into account where are the other scripts/files installed.

Your user directory should now contains:

$ ls
configure.ac           demo-superv.opf  Makefile.am  user-demo-superv.input
demo-superv.inc.input  demo-superv.sym  Makefile.in  user-demo-xsuperv.input

Running the complete OpenPRS supervisor

You are done... almost.

Go back to directory above and make install again:

$ cd ../build
$ make install

You can now run the full supervisor with the command:

$ user-demo-xsuperv -a -A

Note that the script name has changed, you are now calling the user enhanced version now (which itself will can demo-xsuperv).

An xoprs window should appear again, and you can display the Demo Superv OP (Ctrl-P should show it to you) you have written.

To start the demo, just add the goal with the menu: Oprs->Add Fact or Goal:

(! (demo-superv demo))

The argument correspond to the name of the module demo.

You should see in the window where you started the demo module, traces showing what the mobile is moving, changing its speed, etc.

If you want to stop the demo, just add the fact: (stop-superv)

Enjoy...

Questions? comments? mail me: felix@laas.fr