File	Date	Author	Commit
build	2012-03-02	Alexander Kettler	[dfbd97] Changes to copyright notices
cmake	2012-03-02	Alexander Kettler	[dfbd97] Changes to copyright notices
data	2012-05-01	Alexander Kettler	[e42e4e] Added basic outline for a PowerSupply class.
src	2012-05-01	Alexander Kettler	[e42e4e] Added basic outline for a PowerSupply class.
CMakeLists.txt	2012-05-01	Alexander Kettler	[e42e4e] Added basic outline for a PowerSupply class.
COPYING	2012-03-02	Alexander Kettler	[dfbd97] Changes to copyright notices
README	2012-03-09	Alexander Kettler	[14d243] *Changes to Python Interface and Python Control...
README.ogre	2012-03-02	Alexander Kettler	[e3bda8] Include Ogre Copyright Notice

Read Me

DisCoBots aims to be a Distributed Collective Robotics Simulator.

It was originally developed by Alexander Kettler (akettler@users.sf.net)
at the Karlsruhe Institute of Technology (KIT). The work was supported 
by the German Research Foundation (DFG) within the Research Training 
Group GRK 1194: “Self-organizing Sensor-Actuator-Networks”.

=========================================================================
Copyright (C) 2012  Alexander Kettler (akettler@users.sf.net)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>
=========================================================================

This software contains some content from the the Ogre3D Library. 
The corresponding copyright notice can be found in the file "README.ogre"
distributed along with this software.

Please find below a very quick, dirty and incomplete introduction.

=========================================================================
REQUIREMENTS:
=========================================================================

	This is a list of the required libraries / tools 
	you need to build / use the simulator:

	Simulator:
		* CMake
		* Bullet (tested with >= 2.77)
		* Ogre3D (>=1.7 (Cthugha))
		* Boost (thread, regex)
		* libxml2
	Python Interface (optional):
		* libreadline
		* Boost (python)
	OpenMPI based Network Interface (optional):
		* OpenMPI
	Telnet Network Interface (optional):
		* Boost (asio)		
	Documentation (optional)
		* Doxygen

	The simulator heavily relies on the graphics hardware for 
	simulating sensor values, so you should have a 	fairly good (what 
	ever this means) graphics card with	GLSL Shader support installed.
	
=========================================================================
INSTALLATION HOWTO FOR UBUNTU:
=========================================================================

1. Dependencies:
	Most of the required libraries/tools can be installed from the 
	ubuntu repositories. A complete list would be (hopefully):
	
	build-essential\
	cmake-curses-gui\
	libboost-thread-dev\
	libboost-regex-dev\
	libboost-python-dev\
	libxml2-dev\
	libois-dev\
	libreadline-dev\
	python-dev\
	libopenmpi-dev\
	openmpi-bin\
	doxygen

	If you want to compile OGRE and Bullet yourself, you need some
	additional packages:

	libxaw7-dev\
	libfreetype6-dev
	libgl1-mesa-dev\
	libzzip-dev\
	libfreeimage-dev\
	libxrandr-dev\
	libglu1-mesa-dev\

2. Compiling and installing Bullet:
	a) Get the latest bullet source package and extract it somewhere
		(www.bulletphysics.org)
	b) Create a new folder "build" inside the newly extracted directory
	c) Inside the folder "build" run "cmake ..", 
	   then "make" and finally "sudo make install"

3. Compiling and installing OGRE: 
	You can install Ogre from launchpad: 
		(https://launchpad.net/~ogre-team/+archive/ogre)
		It currently also ships with its own version of libboost, so watch
		out for conflicting package versions.
	OR:
	a) Get the latest ogre3d source package and extract it somewhere
		(http://www.ogre3d.org/download/source)
	b) same as 2.b)
	c) same as 3.c)


4. Compiling the simulator:
	a) Get the source and extract it (You probably did this already)
	b) Change to folder "build"
	c) Inside the folder "build" run "cmake ..", then "make"

5. Creating Documentation
	You can issue "make doc" inside the "build" folder. 
		This creates a directory "doc" containing 
		very very little documentation ;-)


=========================================================================
RUNNING THE SIMULATOR:
=========================================================================
	If you had success with the above steps, try to start an example:
		"./discobots -c ../data/configurations/scenes/collecting.xml"
		or: 
		"./discobots -c ../data/configurations/scenes/example.xml
		or:
		"./discobots -h" (list command-line parameters)
	* The simulation can be paused by hitting "space"
	* Use "w" "a" "s" "d" or arrow keys to move the camera
	* Hold the left mouse button while moving the mouse cursor to 
	  look around
	* Hold the right mouse button to drag objects 
		(works only while simulation is running)
	* In the console-window, type "DCBS." and then hit <tab> twice 
		this will give you access to some parameters of the simulator
		"DCBS.world." will give you access to all simulated	objects

=========================================================================
CREATING OWN CONTROLLERS:
=========================================================================
	* You can write a controller using python 
	  (see ../data/configurations/scripts/example.py) for an example
	* You can of course write a controller using C++
		navigate to "src/Objects/Controllers/Wanda/"
		here you will find some example controllers, just follow them
		for creating your own.
		There's no plugin infrastructure yet (feel free to add one ;), 
		so you have to perform a few steps to integrate your controller:
			* You have to add your new source files to the 
			  "CMakeLists.txt" file in the DisCoBotS root-directory 
			* You have to add your new controller to the object-factory 
			  (look into "src/main.c", it should be straight forward)
		Thats it (at least i hope so) 
		
=========================================================================
ISSUES:
=========================================================================
	Run "ccmake .." to adjust compile settings 
		(you can try multi-threading with bullet, see below)

	For Bullet or Ogre installs in strage places, use: 
	cmake ..	-DBULLET_ROOT=<bullet install location (e.g. /usr/local/)> \
				-DOGRE_ROOT=<ogre install location (e.g. /usr/local/)>
				
	If you want to used Multithreading with Bullet, which is still 
	kind of experimental, it may be necessary to copy the contents of
	the folder "src/vectormath/" from the bullet folder into the 
	folder where you installed the bullet includes
	
	I found that using multi-threading only for constraint solving gives
	a speedup for numbers > 30 robots. Using multi-threading for 
	collision dispatching results in a slow down, however !?!