
=========================================
MobileSim Source Code Information:
 * Building MobileSim 
 * How MobileSim works
=========================================

Reed Hedges <reed@mobilerobots.com>

This document provides an overview of MobileSim for people interested in
compiling MobileSim from source, modifying MobileSim, or just understanding 
how it works.

MobileSim is software for simulating MobileRobots mobile robots
and their environments, for debugging and experimentation.

MobileSim is based on the Stage library, created by the 
Player/Stage project <http://playerstage.sourceforge.net>,
but modify to add some needed features.  

All of the actual simulation is done by the Stage library,
as well as the graphical display of the robot, sensors and map.
MobileSim merely packages up the library into an easy to use
application, and interprets Pioneer robot-compatible commands
and data for Stage.

Player, Stage and all MobileSim components are free software,
distributed under the terms of the GNU General Public License:
see the file COPYING for details.



----------------------------
Modifying MobileSim or Stage
----------------------------

Both Stage and MobileSim are distributed to you under the terms of the 
GNU General Public Lincese (GPL).  See the file named COPYING for the
text of this copyright license, which in particular, requires you to
release source code of any modified versions make under the
GPL as well, if you also distribute the modified program.  See 
COPYING for the details.

If you do make any modifications and would like to share them, please
do so via the appropriate channel:
 * For modifications to Stage (libstage), you can share the change with all
   Stage developers and users (not just MobileSim developers and users) via 
   the patch tracker and mailing list at <http://playerstage.sf.net>. 
 * For modifications to just MobileSim (emulatePioneer; MobileSim main.cc or tools)
   post them to the public aria-users mailing list or email them to MobileRobots
   technical support. See <http://robots.mobilerobots.com>

If you have any questions about how MobileSim works or about modifying it,
please discuss on the aria-users mailing list.



----------------------------------
How to Compile Stage and MobileSim
----------------------------------

To build MobileSim, you will need GTK 2.0 or later, including 
development packages, and the full GNU development tools: 
G++ (3.2 or later), make, libtool, automake, and autoconf.  
If you have multiple versions of automake or autoconf, or have
them installed somewhere unusual, you can choose which commands
to use by setting the AUTOMAKE, AUTOCONF, AUTORECONF and ACLOCAL
environment variables before running make (e.g set them to 
run the newer version).  A modified version of Stage required by 
MobileSim is included in the 'stage' subdirectory; you may enter 
that directory and manually configure and build libstage if 
required, or you may just run 'make' here in the main MobileSim 
directory to build both libstage.a and MobileSim.  Then run 
'make install' to install MobileSim into /usr/local.  

On Debian Linux, you can use apt-get to install the required
packages as follows:
  apt-get install libgtk2.0-dev automake autoconf libtool make g++

On RedHat Linux 7.3, you can download and install the following
packages with 'rpm' if you don't already have them (Or, install them using
your RedHat CD-ROM instead of downloading, if you wish):
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/glib2-devel-2.0.1-2.i386.rpm
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/atk-devel-1.0.1-1.i386.rpm
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/pkgconfig-0.12.0-1.i386.rpm
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/pango-devel-1.0.1-1.i386.rpm
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/gtk2-devel-2.0.2-4.i386.rpm 
 ftp://archive.download.redhat.com/pub/redhat/7.3/en/os/i386/RedHat/RPMS/XFree86-devel-4.2.0-8.i386.rpm 

If you need any additional dependencies, or have a different version of RedHat,
SuSE or Fedora, you can search for RPMs at rpmfind.net.

On Windows, you must use MinGW, MSYS and the MSYS DTK (http://www.mingw.org) 
to build Stage and MobileSim. You must also install various additional libraries.
See the file "README-Windows.txt" in the 'stage' subdirectory for 
instructions on building Stage with MinGW on Windows.  After following those
instructions and building Stage, you can then build MobileSim.

Stage uses the autotools, (autoconf, automake, libtool, etc.) so
if you plan on customizing anything about Stage's build process, or
otherwise need to regenerate its configure script, config.h header, or its 
Makefiles, you will need those.   MobileSim's Makefile will run the autotools
to regenerate the aclocal.m4 and configure scripts if neccesary, and run
configure to generate the Makefiles etc., or you can do it by entering the 
stage directory, running "autoreconf -i" or "autoreconf -i --force". Then go 
back up to the MobileSim directory, and run "make stage/config.status" to 
run the stage configure script, and "make" to build everything.

MobileSim requires certain resources (such as the robot models definitions 
file) to work correctly, so you must either install MobileSim with 
'make install', or set a MOBILESIM environment variable to the MobileSim
source directory (or another directory containing MobileSim's resources).

When building MobileSim, you can set environment variables that affect
compilation options:
 
  CXX                     Set the C++ compiler; if unset, "c++" is used.

  CC                      Set the C compiler; if unset, "cc" is used.

  CFLAGS                  Additional compilation flags for C.
  
  CXXFLAGS                Additional compilation flags for C++.

  LFLAGS                  Additional linker flags.

  MOBILESIM_RELEASE       Build MobileSim with optimizations enabled and
                          debugging disabled and skip some libstage test programs.

  MOBILESIM_PROFILE       Build with profiling enabled with -pg; analyze later
                          with gprof.

  prefix                  Installation directory base (default is /usr/local)
   
  DESTDIR                 Alternate root for installation (default is none,
                          therefore the root filesystem is used).

  STAGEDIR                Alternate Stage directory (default is stage/)

  STAGELIBDIR             Alternate Stage library directory (default is
                          stage/src/.libs)

  AUTORECONF		  autoreconf command

  AUTOCONF                autoconf command

  ACLOCAL                 aclocal command

  AUTOMAKE                automake command

You can also edit Makefile if neccesary.


-------------------
How MobileSim Works
-------------------

MobileSim glues together three main components: Stage; Pioneer emulation; 
various utilities borrowed from ARIA to load a map file and to send and
receive packets to and from clients.  The source file "main.cc" contains 
the main() function and brings these three components together, and provides 
a command-line interface and also an initial dialog box for loading a map 
file and selecting a robot model to create. The files RobotFactory.cc,
RobotFactory.hh, StageRobotFactory.cc and StageRobotFactory.hh implement
the "robot factory" feature (on-demand model creation).

Stage
-----

Stage is the core of the simulator. It provides the main GUI, and simulation of 
all the robots, devices, their environment, and collisions between them. 
Stage is not a MobileRobots project, but was created by a variety of individuals
and is related to the Player project.   Stage consists of a library, libstage.a,
which MobileSim uses to set up the simulated world, the GUI, and requested
robots and their devices. 

We have modified Stage to add some missing features and to allow it 
to be built in MSYS/MinGW.  This modified version of stage is included
in the source code package in the 'stage' subdirectory, and must be built
before building MobileSim.  (Patches that specify the differences between
my modified version of Stage and the original release are in the 'patches' 
subdirectory.) 

The source code to Stage is in the 'stage/src' subdirectory.  Simulation
of robots and devices ("models") are in files beginning with the "model_"
prefix. E.g. a movable robot base is a "position" model and is implemented
in "model_position.c".  Sonar is a kind of "ranger" model.  The laser LRF
is a "laser" model.  Stage begins by creating a "world" (MobileSim creates
a temporary world file for Stage to start with).  MobileSim then creates
models for the robots and devices, represented using stg_model_t structs
which store properties and other state.  These are initialized with an init
function for the appropriate type (e.g. position_init for position models,
ranger_init for ranger models, etc.)  which creates the model's property
objects, registers callbacks for future events, etc.  It then calls the
load function (e.g. position_load for position models, etc.) which reads
configuration information from the world.  Then, after the simulation has
been started, MobileSim's main loop calls Stage's main update function, which
calls the update functions for all model in the simulation (e.g. position_update
for position models) every 100ms (by default).  This update function can examine 
"command" properties and make appropriate changes, and otherwise maintain the 
model's state in the simulation.  Each model-specific function ends by calling 
a common update function that updates the model's position in the simulated world 
(based on its current velocity properties) and updates the GUI.

In setting up the world configuration for Stage, MobileSim relies on definitions of various 
Pioneer robot models, which are kept in a file called PioneerRobotModels.world.inc.  
When installed, this file is alongside the MobileSim program (e.g. 
/usr/local/MobileSim director on Linux).  

More about Stage (including library API documentation) is on the web at 
<http://playerstage.sf.net>.


Pioneer emulation
-----------------

The Pioneer emulator component encapsulates the Pioneer robot specific aspects
of the MobileSim code. The central class in this part is called EmulatePioneer.
EmulatePioneer accepts command packets and sends information packets through a 
TCP port, the same way that a real Pioneer robot communicates over a serial port.  
These commands are de-marshalled and EmulatePioneer makes appropriate calls into 
a RobotInterface object.  Likewise, information is retrieved from the 
RobotInterface to be sent in information packets. RobotInterface is the 
interface through which the Pioneer emulation component communicates with the 
simulation component.   In MobileSim, a subclass of RobotInterface called 
StageInterface is used to connect the Pioneer server emulation with the Stage 
simulation.   The StageInterface class also contains a function to load the map 
file and set up the Stage world accordingly.

For each robot requested, MobileSim's main() function creates a 
StageInterface and an  EmulatePioneer object. The EmulatePioneer object creates 
a background thread to manage client connections.   The StageInterface object 
locates appropriate "model" pointers in the Stage simulation for the robot 
(a "position" model), sonar (a "ranger" model) and possibly a laser model.  
StageInterface communicates with Stage through it's public functional API or by 
getting and setting "properties" (a generic data container) of these models.


-----------------------------------------------
$Id: README.src.txt,v 1.22.2.1 2009-01-28 20:35:30 reed Exp $

