Eyesim 5 alpha
--------------

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 (unstable).  Eyesim has been successfully compiled on
machines running Debian 3.0 and RedHat 7.2/7.3.

Requirements
------------

Eyesim is dependent on a number of third party libraries.  All of
these are prepackaged for Debian, and most of them packaged for
RedHat.  A separate archive (eyesim5-libs.tar.bz2) is available on
our server that contains the less commonly packaged libraries
so they may be built from source.  We are also working on providing
RPM's of these (marked with an *); check on our server to see if
they have been completed.

- GCC
    You must ensure the dynamic C++ libraries on your system have
    been compiled with the same version that compiles Eyesim; this is
    usually not an issue on a single workstation, but can affect
    environments with different Linux distributions installed.

* Coin (1.0.1) (www.coin3d.org)

* SoQt (www.coin3d.org)

* GNU CommonC++ 2.0 (www.gnu.org)

- Qt (www.trolltech.com)
	  Eyesim has been succesfully built against both Qt2.3.1 and Qt3.x. 
	  Some packaged versions of Qt 2.x do not include the Qt GL widget
		which is required by Eyesim.

- OpenGL compliant library (eg Mesa, www.mesa3d.org)
	  Eyesim has been tested to work with the Mesa software renderer, and
		Nvidia's proprietary hardware accelerated version.

- GNU zlib (www.gnu.org)
-	libxml2 (packaged with most distributions)
- pthread (packaged with most distributions)

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:

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

1) edit the makefile if necessary; provided libraries have been installed
   in standard locations (/usr, /usr/local) it should work without
	 modification.  Note that the QTDIR environment variable must be set.

2) make eyesim

3) edit the simulation files in the test directory
	- 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.

4) compile your robi program with the gccsim script (or use the provided
  	 Makefile)
   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 inside your simulated program directory, optionally 
	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.


	-  Axel Waggershauser
	-  Updated by Daniel Venkitachalam 13/9/2002