= Tutorial: Writting an OpenPRS demo supervisor for the demo GenoM3 module =

This page explains how to build an [[openprs|OpenPRS]] '''demo''' supervisor using [[transgen3|Transgen3]] to control the GenoM3 module '''demo''' you created following this [[genom3/tutorial/demo|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 [[http://robotpkg.openrobots.org/|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|OpenPRS]] is used to run the supervisor and execute the procedures/OPs.

[[Transgen3|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|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 [[genom3/tutorial/demo|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:

[[attachment:xoprs-demo-xsuperv1.png|{{attachment:xoprs-demo-xsuperv1.png|attachment:xoprs-demo-xsuperv1.png|width="800"}}]]

`demo-xsuperv` is a script which calls [[openprs|OpenPRS]] with the proper arguments which will load the proper files. The {{{-a -A}}} options tell [[openprs|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|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|OpenPRS]]. If ope does not exist, most likely you did not properly install [[openprs|OpenPRS]].

{{{
$ ope demo-superv.opf
}}}
{{attachment:demo-superv-op.png||width="800"}}

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|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:

{{{
#!/bin/bash

@SUPERVBINDIR@/demo-superv -x "@SUPERVUSERDATADIR@/demo-superv.inc" $*
}}}
a script file named {{{user-demo-xsuperv.input}}} (to call the autogenerated demo-xsuperv script) containing:

{{{
#!/bin/bash

@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.

[[attachment:xoprs-demo-xsuperv2.png|{{attachment:xoprs-demo-xsuperv2.png|attachment:xoprs-demo-xsuperv2.png|width="800"}}]]

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.

[[attachment:xoprs-demo-xsuperv3.png|{{attachment:xoprs-demo-xsuperv3.png|attachment:xoprs-demo-xsuperv3.png|width="800"}}]]

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

Enjoy...

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