Documentation of lpzrobots

0.4

Organization:

University Leipzig
Institute for Computer Science
Dept. Intelligent Systems
Prof. Dr. Ralf Der
Research Group: Neuroinformatics und Robotic
    and
Max-Planck Institute for Dynamics and Self-organzation
Bernsteincenter for Computational Neuroscience Goettingen
Bunsenstr.10, 37073 Goettingen, Germany
Georg Martius
Research Group: Self-organization in Adaptive Systems

People:

Ralf Der, Georg Martius, Frank Hesse, Frank Güttler
Former Contributors: Marcel Kretschmann, Dominic Schneider, Claus Stadler,

General

This is a collection of algorithms, simulations, and tools developed by the robot group of the University Leipzig
(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 behaviour 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, utils, 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 program
• neuronviz : application that displays neural networks
• webots : directory with a webots simulation using the selforg lib
• opende : directory with a snapshot of the open dynamics engine (release 0.9) (please follow the link for installation hints)

Requirements

You need the following software and libraries installed (Tested on Linux x86 machines).

• ODE see http://www.ode.org which is now in the opende directory (please follow the instrutions printed by the Makefile in lpzrobots)
• OpenSceneGraph http://www.openscenegraph.org (version >= 2.2.0)
• (optional) Qt library from http://www.trolltech.com for guilogger (version > 4.0)
  • make sure you install the devel packages
  • make sure the correct qmake version is in your path. If you have both qt3 and qt4 installed you have to take care of that. Use qmake --version to find out. On Debian and Ubuntu use the alternatives system http://www.debian-administration.org/articles/91
• (optional) Java JDK for neuronviz (version >= J2SE 1.5.0)

For convinience we provide a binary package with ODE and OSG compatible with most linux distributions, see next section

Installation & Startup

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

• A) download a precompiled version of the simulator libaries and the utilities. This is the quick and easy way which you can try first, see Way A: Binary installation
• B) download the source tar ball and compile the simulator youself. You have still the chance to take the precompiled extra libs. If way A failes or you want to modify the simulator then this is the way to go, see Way B: Installation from source

Way A: Binary installation

• Download the binary and the extra-lib tar balls from http://robot.informatik.uni-leipzig.de/software .
• Unpack the files (with tar -xvzf file.tgz)
• Install extra libs:

  cd lpzrobots-0.*-extra-lib-devel*
  ./install.sh
  # or, if you want a system wide installation
  sudo ./install.sh
  

• Install the simulator:

  cd lpzrobots-0.*-binary-lib-devel*
  make install
  # or, if you want a system wide installation
  sudo make install
  

• You will be asked for the installation prefix and the installation type. The latter you have to anwser with u like user.
• Now you are done with the installation and you can try a sample simulation from ode_robots/simulations/. Please continue reading in section Run example Simulations.

Way B: Installation from source

• Download source tar ball from http://robot.informatik.uni-leipzig.de/software .
• Unpack file.
• Change into lpzrobots directory
• Call make to get a help display and continue with make prepare, which will do the following:
  • it creates a configuration makefile (Makefile.conf) with your interaction
  • it compiles neuronviz (not strictly necessary, only for displaying neuronal network online)
  • it compiles guilogger (not strictly necessary, only for displaying parameters online)
  • Please note, that the make call will not fail if either of them failed to make, because they are optional. You can type make guilogger and make neuronviz to compile them seperately.
  • it creates dependency files and creates links to header files, that they can be found.
  • it prints some information how to install the ODE residing in the opende directory.
• Now you have to install the extra libs namely ODE and OSG.
  • To install the ODE please follow the instructions printed by the makefile. If nothing is printed then the libode was found. In case it is not the correct version do the following:

    cd opende 
    sh autogen.sh
    ./configure --enable-release --enable-double-precision
    make
    sudo make install
    

  • To install the OSG, please refere to their homepage: http://www.openscenegraph.org/
• After finishing the installation of ODE and OSG you can procede with the installtion of th simulator.
• Call in the directory lpzrobots/

  make libs
  make install
  # or, if you want a system wide installation
  sudo make install
  

  This will compile the libaries and install the tools.
• Now you are done with the installation and you can try a sample simulationsee next section.

Run example Simulations

• Simulations are located in ode_robots/simulations/? and selforg/simulations/?
• To start a simulation go into a simulation directory.
• If you installed from source you have to call make.
• You can start the simulation by ./start.
• For example when you want to start the template_onerobot simulation type:

  cd ode_robots/simulations/template_onerobot
  make # if installed from source
  ./start 
  

• for optimisation you can also use make opt which produces and start_opt(might need a make clean before)
• 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)
          -n interval     use neuronviz (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
  

• 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 informations on the used self-organization algorithm is available at http://robot.informatik.uni-leipzig.de/research
• The ODE tutorial of Marcel Kretschmann can be found at http://robot.informatik.uni-leipzig.de/students
  (Tar ball with pdf and example code also there available.)
• The original ODE documentation can be found at http://www.ode.org/ode-docs.html
• The OSG documentation can be found at http://www.openscenegraph.org/osgwiki/pmwiki.php/Documentation/Documentation

---