This file describes how to set up the (new) simulation environment for
the EyeBot. The current version is a _very_ preliminary, possible buggy
one.

The Linux system on which this program has been developed, is running
GNU/Debian 3.0 (testing). Unfortunately we were not yet able to
properly compile the program under the current Red Hat distribution
(7.2). So, best (if any :-)) results will probably be made with a
Debian system.


What you need to compile user programs:
- GCC ( should work with >= 2.95.x, but not with >= 3.0 )

To compile the simulator I use the following libraries and versions,
other version may work as well:
- Coin (1.0.1) (www.coin3d.org)
- SoQt (I got it from the cvs
	(:pserver:cvs@cvs.coin3d.org:/export/cvsroot, module SoQt,
	password is "cvs" (I guess)))
- GNU CommonC++ (1.9.4) (www.gnu.org, is available as Debian package)
	needs libxml2 and Linux-Threads (pthreads), this should be
	part of most distributions
- Qt (2.3.1) (www.trolltech.com, is available as Debian package)
	has to be compiled with OpenGL-support like QGLWidget, the
	Debian package is libqt2-gl and libqt-gl-dev
- Mesa (4.1) (standard OpenGL library, Debian package xlibmesa(-dev))
- GNU zlib (standard library)
- GCC (2.95.4) (www.gnu.org, bet there is a package...)

To make your own VRML-model for the robots, you have to make a VRML
1.0 or OpenInventor file. For example the program ac3d (www.ac3d.org)
could be used for that. The file must be placed in the "current"
directory and have the name "robi.iv". The unit to use for the model
is 1 meter.


INSTALLATION:
(if you have an executable of the simulator (eyesim), you can skip steps 1-3)

0) make sure the OpenGL setup of your machine is fine

1) untar the sources (eyesim-5.0.tgz)

2) Since there is no configure script available, you probably have to
   modify the Makefile by hand to set up some paths like the COIN and
   SOQT path.

3) make eyesim

4) edit the simulation files:
	- test.sim : the description of the simulation
	- test.robi : the description of the robi configuration
	- test.wld/test.maz : the description of the environment/world
	- robi.iv : the 3D-model of the robi in the OpenInventor file fomat
	- eyesim.ini : global parameters for the error model, the ball
	  simulation etc.

5) compile your robi program with the gccsim script
   e.g.: > gccsim test.c -o test.so

6) add the current directory (".") to the environment variable
   LD_LIBRARY_PATH (to enable the simulator to find the program, here
   "test.so")

7) start the simulator, optional with the path to the simulation description
   file as the parameter (e.g.: > ./eyesim test.sim)


TODO:
- implement new Camera Interface, including the specification of several cams
- implement appropriate error handling for functions that are not tested yet,
	like LCD, Radio, CAM, RS232 - ask Yves (hwang-y)
- perform still missing timing measurements for the features.cc file,
	like multi-threading - ask Tee (ng-ty)
- test/debug especially the functions in the sections RS232, LCD (graphic),
	RADIO, IP
- implement the specification of different robis in the test.sim file
	(which is actually, why I used this dll model)
- use the user id, specified in the robi description file for the
	OSMachineID and RADIO funtions
- implement workaround for the bug, deadlocking the display
- display some additional information like psd values and the psd sensor
	lines for better debugging purposes.

TODO (but won't be done):
- improve the dynamic model by introducing speed ramps
- infrared and bumper sensors
- implementation of process instead of thread based simulation
	-> distributed simulation
- image error model (%) [0..1] [salt/pepper] 
- implement cpu speed factor measurement and find better cpu time clock
- fix the bugs

BUGS:
- a lot (especially everywhere where you find the string "//BUG:" in the
	source code)
- there seems to be a bug in Qt/SoQt that leads to weird error messages
	on the console, telling something about QTimer or the display simply
	does not react anymore but the simulation core is actually still
	running
- the ball simulation is very dodgy. I had no time to develop a considered
	model and the whole thing is more like a quick hack, hence with several
	"open ends"; like balls can be pushed through a wall, balls don't interact
	with each other, etc.
- unclear behaviour in multi-tasking mode for example what happens if the
	only ready thread calls OSSleep or gets blocked by calling OSSemV?
	So there might be differneces in the behaviour of the simulator and the
	robot.
- manual movements of robis in presence of balls will likely crash or
	misbehave.


THINGS TO KEEP IN MIND WHEN WRITING PROGRAMS THAT SHALL BE SIMULATED:

1) The well known and general motto "global variables are bad" is write
	especially in this case. If your program contains global variables
	you will _NOT_ be able to simulate several robis running this program,
	because all instances will share the same variables.
2) Since there is no simulation for the Servos, the way to modify the pan
	and tilt angle for the cameras is different for the real robi and the
	simulator. see function SIM_CAMSetPanTiltAnlge in robios/eyebot.h.
	The same goes for the kicker mechanism.