Robot Simulator of the Robotics Group for Self-Organization of Control: Documentation of lpzrobots

# Documentation of lpzrobots

### 0.7.0

Organization:
  Max-Planck Institute for Mathematics in the Sciences
  Inselstr. 22, 04103 Leipzig, Germany
  Dr. Georg Martius & Prof. Dr. Ralf Der
  University Leipzig
  Institute for Computer Science
  Dept. Intelligent Systems
  Frank Güttler
  Research Group: Technische Informatik

People:
  Georg Martius, Ralf Der, Frank Hesse, Frank Güttler, Jörn Hoffmann
  Former Contributors: Antonia Siegert, Marcel Kretschmann, Dominic Schneider, Claus Stadler

## General

This is a collection of algorithms, simulations, and tools developed by the Robotics Group for Self-Organization of Control (http://robot.informatik.uni-leipzig.de).
It consists of the following directories (click for details):

- selforg : controllers together with a small framework for using them, developed in the robotic group of Leipzig university yielding at self-organized behavior for various kinds of machines.
- ode_robots : physics simulator based on ODE (Open Dynamics Engine, see http://www.ode.org). This includes such as robots, obstacles, utilities, stuff for visualization with OSG (OpenSceneGraph, see http://www.openscenegraph.org) and so on.
- guilogger : application that coordinates multiple gnuplot windows and allows for an interactive display of data that is sent per pipe from another - matrixvix : application for interactive display of changing matrix and vector data
- configurator : a library implementing a GUI to change the parameters interactively which is otherwise done on the console
- ga_tools : genetic algorithms framework that can be used to together with ode_robots or for independent simulations (not well maintained) program
- opende : directory with a snapshot of the open dynamics engine (release 0.11.1) renamed to ode-dbl in order to avoid conflicts with packaged single precision versions. It contains the capsule-box collision bugfix which is upstream (in svn) (please follow the link for installation hints)

## Installation & Startup

You have two different ways to get the simulator to work.

- A) Install a package for your distribution. This is the quick 'n' easy way if you have root permissions, see Way A: Package installation.
- B) Download the source tar ball and compile the simulator yourself, see Way B: Installation from source

### Way A: Package installation

#### Ubuntu

A package repository is hosted at https://launchpad.net/~georg-martius/+archive/lpzrobots
Do on a terminal (or read the link: "read about installing" on that page):

    sudo add-apt-repository ppa:georg-martius/lpzrobots
    sudo apt-get update

Then you can install `lpzrobots` as any other package do:

    sudo apt-get install guilogger lpzrobots-oderobots

This will automatically install all other dependencies.

That's it!

Now you can copy the sample simulations from `/usr/share/lpzrobots/` to your home directory and continue reading in section Run example Simulations.

#### debian based systems (deb)

There is an install makefile located here: http://robot.informatik.uni-leipzig.de/software/packages/deb/install_deb_source.makefile . Save it on you disk in an empty directory and run on the console

    su -c apt-get install make
    make -f install_deb_source.makefile

That will download the newest packages, compile them and install it. If something fails you can also redo parts of the process, see "make -f install_deb_source.makefile help".

The packages are: guilogger, matrixviz, ode-dbl, lpzrobots-selforg, and lpzrobots-oderobots You can uninstall them later using the package manager (apt-get or synaptics)

####

You can do it step by step as follows: Download all files from http://robot.informatik.uni-leipzig.de/software/packages/deb/current/
Then do

    # here you should not be root
     dpkg-source -x guilogger-0.*.dsc
     cd guilogger-0.*
     dpkg-buildpackage -rfakeroot -b -uc
     cd ../
    # become root (e.g. with su or sudo -s)
     dpkg -i guilogger-0.*.deb

This you have to repeat for each package (e.g. replace guilogger by ode-dbl, lpzrobots-selforg, and lpzrobots-oderobots)

### Way B: Installation from source

#### Linux

Check the `Dependencies` file for required packages.

#### MAC

We recommend to install the ODE and OSG via macports (http://www.macports.org) (after installation of macports type on a console `sudo port install osg OpenSceneGraph`) and see the `Dependencies` file. We will update the mac-related install procedures soon.

#### Instructions

- Download the source tar ball from http://robot.informatik.uni-leipzig.de/software/current .
- Unpack file (`tar -xvzf lpzrobots*.tar`).
- Change into `lpzrobots` directory
- Call `make help` to get a help display and continue with `make all`. This will do everything. The first time you call it it will configure your build (you can reconfigure later with make conf). The following modules are compiled:
  - matrixviz (not strictly necessary, only for displaying neuronal network parameters online)
  - guilogger (not strictly necessary, only for displaying parameters online (recommended))
  - configurator library (not strictly necessary, only for changing parameters conveniently)
  - Please note, that the make call will not fail if either of them failed to compile, because they are optional. You can type `make guilogger` and `make matrixviz` to compile them separately.
  - selforg
  - opende (our ode version with double precision) (required)
  - ode_robots
  - ga_tools

if you do it step by step as display with `make help` you need to use `sudo make xxxx` if the installation is into a system directory. (make all will do use it automatically if required). Note that the `PATH` variable needs to contain the PREFIX`/bin` (as checked by the configuration process). If you have multiple lpzrobots installations make sure the prefix for the current lpzrobots comes first in the `PATH` variable

- Now you are done with the installation and you can try a sample simulation see next section.

### Run example Simulations

- Simulations are located in `ode_robots/simulations/`,`ode_robots/examples/`, and `selforg/simulations/`. This folders you can find in the lpzrobots tar files or if installed on your system under `/usr/share/lpzrobots`or`/usr/local/share/lpzrobots`. In the latter case copy the simulations to your home directory first.
- To start a simulation go into a simulation directory.
- Call `make` to compile it.
- You can start the simulation by `./start`.
- For example when you want to start the template_sphererobot simulation type:

      cd ode_robots/simulations/template_sphererobot
      ./start

- for optimization you can also use `make opt` which produces and `start_opt`. This is recommended to use after testing the code.
- The following command line options are available (type ./start -h for a full list of options):

      Usage: ./start [-g [interval]] [-f [interval]] [-r seed] [-x WxH] [-fs]
                       [-pause] [-shadow N] [-noshadow] [-drawboundings] [-simtime [min]] [-threads N]
                       [-odethread] [-osgthread] [-savecfg]
              -g interval     use guilogger (default interval 1)
              -f interval     write logging file (default interval 5)
              -m interval     use matrixviz (default interval 10)
              -s "-disc|ampl|freq val"        use soundMan
              -r seed         random number seed
              -x WxH          * window size of width(W) x height(H) is used (default 640x480)
              -fs             fullscreen mode
              -pause          start in pause mode
              -nographics             start without any graphics
              -noshadow       disables shadows and shaders (same as -shadow 0)
              -shadow [0..5]]         * sets the type of the shadow to be used
                              0: no shadow, 1: ShadowVolume, 2: ShadowTextue, 3: ParallelSplitShadowMap
                              4: SoftShadowMap, 5: ShadowMap (default)
              -shadowsize size        * sets the size of the shadow texture (default 2048)
              -drawboundings  enables the drawing of the bounding shapes of the meshes
              -simtime min    limited simulation time in minutes
              -savecfg        safe the configuration file with the values given by the cmd line
              -threads N      number of threads to use (default is the number of processors)
              -odethread      * if given the ODE runs in its own thread. -> Sensors are delayed by 1
              -osgthread      * if given the OSG runs in its own thread (recommended)
              * this parameter can be set in the configuration file ~/.lpzrobots/ode_robots.cfg

- On some machine the program crashed right away because of graphic card incompatibilities, try: `./start -noshadow`
- Have a look at the console after starting the program, there you will find some further information for the usage of the program.
- E. g. with Ctrl+C (on the terminal) you get a interactive console interface which can be used to modify parameters on the fly.
- For starting your own simulation see paragraph "How to Start Your Own Simulation" in ode_robots.
- For a well documented examples of a main.cpp of a simulation and a robot .cpp file click the tab "Examples" at the top of this page.

## Documentation

- This manual can be found at http://robot.informatik.uni-leipzig.de/software
- More information on the used self-organization algorithm is available at http://robot.informatik.uni-leipzig.de/research
- The original ODE documentation can be found at http://opende.sourceforge.net/wiki/index.php/Main_Page
- The OSG documentation can be found at http://www.openscenegraph.org/projects/osg/wiki/Support