Documentation of Simulator

------------------------------------------------------------------
Content:
------------------------------------------------------------------
1) Introduction:
What is done? What is the need?
2) Platform and software packages details:

3) Architecture.

4) Different Modules.

5) Programming style (call back functions), its efficiency.

6) Importance of timer.h.

7) Files required to run the simulator.

8) Specify file format, which stores obstacles.

9) Command line options.

10) Runtime controls

------------------------------------------------------------------

1) Introduction:

What is done?
Developed a sophisticated simulated world that can exactly simulate real
world robot with real world dynamics, steering controls of robot, and all the
sensor system onboard.

What is the need?

When developing software for robots, it's hard to run programs every time
on real robot and run about robot collect data, observe its behavior. Simulator
provides one place testing of complete software, it's easy to run, and simulator
can pause/freeze and provide statistical data.

2) Platform and software packages details:

Platform :Simulation can work on windows and Unix based operating

systems.
Programming Language :C++ is used to program simulator.
Packages: OpenGL :OpenGl for 3-D graphic. It makes efficient use of
graphic hardware and provides best performance. This
package is compatible in almost all operating systems.
ODE :Open Dynamics Engine is a free software library for the
simulation of Rigid Body Dynamics.

3) Architecture:
The program start it control from simulator.C, which starts openGL display
window and set required display options. It creates objects of all required
modules (like robot_t, laser_t, etc). It registers some of these modules that
are required to execute at regular intervals, with timer_t. Timer_t calls these
modules through registered function at their registered time intervals. (Fig.1)
 Timer_t accepts all the objects(of class which are subclass of
timer_t.observer_t). It starts a thread which repeats the following loop.
(fig.2)
1) Increase simualtor time.
2) For each registered module, decrease its time left value.
3) If this time left value equals zero, call its time_out() function, and
reset value of time left to the time interval it registered for.
4) Different Modules:

Simulator:
Is the start point of the simulator, which instantiates openGL graphics,
creates instance of simulated time, and other required components like robot,
laser, sonar and other sensor system. This is the program running continuously
to provide graphics, and handles user interface commands, like change of camera,
pause /un-pause, etc.

Control information:
1) Read command-line arguments and load route file, obstacle file.
2) Instantiate OpenGL, and ODE.
3) Create instances of different modules like robot, obstacles,
sensor units, etc.
4) Register different functions for different user interface
commands.
5) Register all modules that need to be executed at regular
intervals, with timer module.
6) Start the openGL function that continuously displays graphics.
Timer:
This is the simulated time, which provides time to all modules. It
regularly updates time. It helps to perform actions like slow down simulation,
speed up, or pause the simulation.
Different modules that need to be executed at regular time interval are
registered here and this module call them at those time interval.
This module make sure that all required modules gets executed at time
interval that they are required to execute.

Control information:
1) Update simulator time.
2) Decrease time for each registered module, and if the time for a
module equals zero, call that module.

Robot:
This is the class that represents the bot in simulator, with all the
features of bot like, mass, dimensions, positions, etc. It has its speed,
throttle, brake lever etc.

Note: Robot do not maintain a list of sensor systems that it has (its better to
have it: to do in future). Its the individual sensors that has reference to
which robot that they are mounted on.

It has rectangular box representing its central body, and has 6 wheels
that are attached to this central body using hinge2Joint. The beautiful
structure of the robot seen in display is just the work of textures, its not
designed to have complex structure, to reduce computation.
It provides with list of functions to return bot’s speed, location, etc.

Obstacles:
This class represents set of obstacles, which are made from some basic
structures like cube, cylinder, and sphere. This class defines its own function
to display obstacles in openGL,

Laser:
This class represents the laser sensor system. Laser beams in sensor
system is implemented using 'Ray' concept provided by ODE, it has a origin and
the direction in which it can be projected. It provides its point of collision
with objects in the simulated world.
 Just like the real sensor system, it is simulated to emit 180 beams each
spaced at one degree apart. It has the pointer to the robot on which it is
mounted and its relative position and orientation on the robot. It defines its
own function to display laser beam in openGL.

Build_terrain:
This class builds the terrain with obstacles, it provides interface to
create obstacles and save them to a file. It is this class that loads obstacles
from obstacle file during simulation. It reads each obstacle type, its size,
position and orientation details, and creates ODE object with those precise
values. Basic building objects include cube, cylinder and sphere.
During interactive creation of obstacles, you can start with already
existing obstacle file, load the obstacle file, add new obstacles and save new
obstacles to file.

Note: Right now there is no provision to interactively delete obstacles or even

make changes to obstacle that are just created before creating present handling
obstacle. We need to add this feature in near future. You can always open the
obstacle file and make changes to obstacle, even delete obstacles.

Cbsim_ui:
This class provides interface to user by receiving all keyboard and mouse
interrupts and calling the corresponding procedures, which registered for this
type of interrupts.

Ray_sensor:
This class provides a single ray sensor, which simulates sonar and radar
sensor. It has pointer to the robot on which it is mounted and its relative
position and orientation on the robot.
It defines its own function to display ray beam in openGL.

Sensor_observer:
This has list of classes that are inherited from timer_t::observer_t. Each
observer is meant to register different type of object with timer module, so
that timer can call back these objects at regular interval. Few of these classes
include motion_observer, nav_observer, sog_observer, etc.
These classes implement virtual function 'time_out()', which is called by
timer module. This function implements the required task that is to be executed
at regular interval or it can in turn call other functions.

Sim_util:
This file provides with library of functions that are required by multiple
classes. Some of the functions include providing distance between set of points,
to converting degrees to radians, etc.

Simview:
This class provides with function and variables that are related to openGL
display. It has information like position, orientation of camera in the
simulator. It provides functions to draw bot, road.

subWindow:
This class represent second window which displays throttle level, lever
position and other things like generator on, engine on, time, speed of robot,
etc.

/*************************************************************
5) Programming style (call back functions), its efficiency.
6) Importance of timer.h.
*************************************************************/

7) Files required for simulator.

a) C++ compiler
b) OpenGL library files
c) ODE library files
d) All .C and .H files in simulator director
e) ../cajunbot/shared_mem.o ../cajunbot/util.o ../cajunbot/route.o
f) ms3d and bmp files in ./data director

8) Format of obstacle file:

First entry in the file contains number of obstacles that are stored in
the file. Followed by list of records describing obstacles in separate lines.
Format of this record is as follows:
[Obstacle_type] [Obstacle_length] [Obstacle_height] [Obstacle_width]
[Position_x] [Positon_y] [Position_z] [Azimuth] [Elevation] [Tilt]

Where [Obstacle_type] can take values:

1 - for Box
2 - for Cylinder
3 - for Sphere

For obstacle of type cylinder it has only height and length, in this case
width of the obstacle is ignored. Similarly for sphere length is taken as
diameter of sphere and other values length and height are ignored.

9) Command line options:

-R Route file
-r Route type (relative,RDDF)
-O Obstacle definition file

The files are specified relative to present directory. Third option '-O'
is capital alphabet 'o', and not numeric zero.

10) Runtime controls:

Right Click option:

Exit : Exit simulation.
Trace with boxes: Enable/Disable robot trace using boxes. When disabled, trace
is displayed using lines.
Auto-pilot : Toggle between auto-pilot/manual driving.
Display_laser : Toggle display of laser.
Display_sonar : Toggle display of sonar.

Keyboard options:
Key 'p': Toggle between pause/un-pause simulation.
Key 'r': Toggle between pause/un-pause only robot.
Key 's': Toggle between stepwise/continuous execution mode. In step-execution
mode press 'p'/'P' to move simulation by one step. You can change step length by
changing value of 'STEP_SIZE' macro in timer.H.

Default options (may vary from version to version)

Pause : Un-pause
Step/continuous : Continuous execution
 Auto-pilot : Manual control.
Camera : Static Camera.

Camera Controls:
Key F1 : Static Camera
Key F2 : Camera on the vehicle.
Key F3 : Camera following the vehicle.

Key Up-Arrow : Move camera forward.

Key Down-Arrow : Move camera backward.
Key Left-Arrow : Move camera leftwards.
Key Right-Arrow : Move camera rightwards.

Key Pg-Up: Zoom In

Key Pg-Dwn: Zoom Out

Manual Control of bot:

key 'F11': Reset speed of left wheel to 0.
key 'F12': Reset speed of right wheel to 0.

Key interpretation when simulator is in speed mode and manual control:

Key 'a': Increase speed on left wheel.
Key 'z': Decrease speed on left wheel.
Key 'k': Increase speed on right wheel.
Key 'm': Decrease speed on right wheel.

Key interpretation when simulator is in throttle mode and manual control:

Key 'a': Move left lever towards brake position.
Key 'z': Move left lever away from brake position.
Key 'k': Move right lever towards brake position.
Key 'm': Move right lever away from brake position.
Key 'j': Increase throttle.
Key 'n': Decrease throttle.