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

This page explains how to build an OpenPRS mobile supervisor using Transgen3 to control the two GenoM3 modules (mobileloco and mobiledisp) you created following this 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 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 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 two modules mobileloco and mobiledisp. If not, go back to this 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:

mobile-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 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 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. If ope does not exist, most likely you did not properly install OpenPRS.

$ ope user-mobile-superv.opf

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

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

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

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.

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