= Tutorial: Writting an OpenPRS supervisor for the GenoM3 modules mobileloco and mobiledisp =

This page explains how to build an [[openprs|OpenPRS]] '''mobile''' supervisor using [[transgen3|Transgen3]] to control the two GenoM3 modules ('''mobileloco''' and '''mobiledisp''') you created following this [[genom3/tutorial/two-modules|tutorial]].

The resulting supervisor can be obtained with:

{{{
$ git clone git://trac.laas.fr/git/robots/demo-mobile-superv
}}}
But you should only do this if you want to skip most of this tutorial...

== What need to be installed? ==
You will need to install (if not already done), the following softwares. The preferred method is with [[http://robotpkg.openrobots.org/|robotpkg]]. We indicate (the robotpkg path / or the git repository):

 * openprs (robotpkg/supervision/openprs / git://trac.laas.fr/git/robots/openprs)
 * transgen3 (robotpkg/wip/transgen3 / git://trac.laas.fr/git/robots/transgen branch genom3 ('''git checkout genom3'''))
 * genom3-openprs (robotpkg/wip/genom3-openprs / git://trac.laas.fr/git/robots/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 two modules mobileloco and mobiledisp. If not, go back to this [[genom3/tutorial/two-modules|tutorial]].

For both theses 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 for both modules (in their build directory):

{{{
$ genom3 openprs/client ../mobile-loco.gen (or ../mobile-disp.gen)
$ cd openprs/client
$ ./bootstrap.sh
$ ./configure  --prefix=${HOME}/openrobots
$ make install
}}}
== Create a directory dedicated to your supervision system ==
{{{
$ mkdir demo-mobile-supervisor
$ cd demo-mobile-supervisor
$ mkdir user
$ touch user/Makefile.am
$ touch user/configure.ac
}}}
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 mobile.tg file ==
containing:

{{{
supervisor mobile {
        module: mobileloco;
        module: mobiledisp;
}
}}}
This declares that we want a supervisor called mobile, to control the module mobileloco and mobiledisp. The modules and their proper libraries 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 mobile.tg
$ ./bootstrap
$ ./configure --prefix=$INSTALL_DIR
$ make install
}}}
At this point, you already have a supervisor with everything one need to control the modules. 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
$ mobileloco-pocolibs -b
$ mobiledisp-pocolibs -b
}}}
If you want to use the ROS middleware:

{{{
$ roscore
$ mobileloco-ros -b
$ mobiledisp-ros -b
}}}
and then type:

{{{
$ mobile-xsuperv -a -A
}}}
You will see a window like this one popping up:

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

`mobile-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 mobileloco/mobiledisp modules) adding one of the following goals (Menu: Oprs->Add Goal or Fact):

{{{
(! (mobileloco_GetSpeed mobileloco))
(! (mobileloco_GotoPosition mobileloco (mobileloco_GotoPosition_input (goto_position (mobilelocointerface_position (x 50) (y -50)))))
(! (mobileloco_GotoPosition mobileloco (VarArg (x 100.0) (y -100.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 modules 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 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 {{{user-mobile-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 user-mobile-superv.opf
}}}
{{attachment:mobile-xsuperv-op.png||width="800"}}

if you are not familiar with oprs tools, just copy the {{{user-mobile-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 {{{(! (mobile-superv mobileloco mobiledisp))}}} (the arguments are the name of the two controlled modules).

When running first, in parallel, it connects the ports and services between mobiledisp and mobileloco.  Then, in parallel, it loops moving the mobile from random positions, and change speed randomly every 3 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 {{{user-mobile-superv.inc.input}}} containing:

{{{
include "@SUPERVUSERDATADIR@/user-mobile-superv.sym"
load opf "@SUPERVUSERDATADIR@/user-mobile-superv.opf"

trace step opf "@SUPERVUSERDATADIR@/user-mobile-superv.opf" on
trace text opf "@SUPERVUSERDATADIR@/user-mobile-superv.opf" on
trace graphic opf "@SUPERVUSERDATADIR@/user-mobile-superv.opf" on
}}}
an oprs symbol declaration file {{{user-mobile-superv.sym}}} containing:

{{{
declare predicate mobile-superv
declare predicate stop-superv
}}}
a script file named {{{user-mobile-superv.input}}} (to call the autogenerated mobile-superv script) containing:

{{{
#!/bin/bash

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

{{{
#!/bin/bash

@SUPERVBINDIR@/mobile-xsuperv -x "@SUPERVUSERDATADIR@/user-mobile-superv.inc" $*
}}}
and finally, edit the {{{Makefile.am}}} and include this in it:

{{{
bin_SCRIPTS = user-mobile-xsuperv user-mobile-superv

DATA_FILE = user-mobile-superv.inc user-mobile-superv.opf user-mobile-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
Makefile     Makefile.in                   user-mobile-superv.input  user-mobile-superv.sym
Makefile.am  user-mobile-superv.inc.input  user-mobile-superv.opf    user-mobile-xsuperv.input
}}}
== Running the complete OpenPRS supervisor ==
You are done... almost.

Go back to directory above and make install again:

{{{
$ cd ..
$ make install
}}}
You can now run the full supervisor with the command:

{{{
$ user-mobile-xsuperv -a -A
}}}
Note that the script name has changed, you are now calling the user enhanced version now (which itself will can mobile-xsuperv).

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

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

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

{{{
(! (mobile-superv mobileloco mobiledisp))
}}}
The two arguments correspond to the name of the two modules (the loco one and the disp one).

You should see the mobile moving in the display window. Wandering randombly around and randomly changing its speed.

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

If you want to play, you can also add once in a while the goals {{{(!(mobileloco_Stop mobileloco))}}} to stop the current !GotoPosition, or {{{(! (mobileloco_GetSpeed mobileloco))}}} to read the current speed.

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

Enjoy...

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