
Software : libIrcom 1.0.7
Authors : Alexandre Campo, Alvaro Gutierrez, Valentin Longchamp


What is it ?
================================================================================
libIrcom is a library that can be used straight forward on the e-puck robots 
(www.e-puck.org) to achieve local range infrared communication, alsa known as
range and bearing. libIrcom relies on the infrared sensors of the robots to 
transmit and receive information. However, the communication system is 
multiplexed with the proximity sensing system commonly used on the robots. It is 
therefore possible to both communicate and avoid obstacles.

libIrcom allows communications at a rate of 30 bytes per seconds max from 
sender to receiver, including a 2bits CRC check in each byte to detect erroneous
messages. Messages are encoded using a frequency modulation that permits usage 
in a wide range of light conditions. Messages can be detected up to 25 cm of 
distance between emitter and receiver. If continuous listening is activated,
libIrcom will try to catch as many messages as possible, independently of the 
cycle duration of your controller. Messages are stored in a queue and can be 
retrieved at any time, unless they are overwritten when the queue is full.



How to test the examples ?
================================================================================
With the libIrcom library 2 examples are provided : test and synchronize.

Windows :
---------
Open project files located in synchronize or test folders.
All necessary files are loaded, you can simply compile with mplab IDE then 
upload with the robots. We tested compilation with mplab 8.02.

Linux : 
-------
Before compiling the examples you have to compile all the libraries. Go to 
the root directory of the library and launch the compilation script by typing:

	./make.sh

test example
------------
This example shows the comunication between two robots. One will be the emitter
and the other the receiver. You will choose each one with the selector switch.
1-> Emiter 2-> Receiver.

The emitter will start transmiting a sequence of numbers from 0 to 255 (1 byte)
continuously.

The receiver will take the frame and demodulate it. If the frame is well decoded
the receiver will send it through bluetooth along with information about the
location of the emitter of the message (orientation and distance). 
The orientation is expressed in the local mark of the receiver starting from 
the camera and going CCW. The distance is between the center of the 2 robots.

Boths robots have to be connected to a computer through bluetooth and 
press enter to start the comunication between them.

The code for the robots is located in libIrcomXXX/e-puck/src/test/. Go to the 
directory and type:

	make
	
The binary will be generated on libIrcomXXX/e-puck/bin/. Download the file to 
the robots

	epuckupload -f test.hex <number_of_robots_to_download>

The code for the computer transmition is on libIrcomXXX/pc/ircomTest/. Go to 
the directory. 

	make

and after 

	./ircomTest <number_of_robot>

Once you are connected to both robots, press enter and check the transmision.

Good luck !

synchronize example
-------------------

This example shows how a group of robots can communicate about directions where they
are pointing to surrounding neighbours and end up aligned towards the same direction.

The example is based on the libIrcom library. In a complete loop, the robots try to:

i)  Send information: Because of the number of robots, each robot will first send 
	his own ID, and after his own direction related to the robots which it has 
	receive any message.
i)  listen for some transmissions and decode the messages. 
	If a message is an ID, it will store the direction where it cames from.
	If the message is an orientation addressed to it, it will change the orientation, 
	according to this new information.

The code for the robots is on libIrcomXXX/e-puck/src/synchronize/. Go to the 
directory and type:

	make
	
The binary will be generated on libIrcomXXX/e-puck/bin/. Download the file to 
the robots

	epuckupload -f sync.hex <number_of_robots_to_download>


Troubleshooting
================================================================================
* Wrong messages received, or messages not received
Robots emit the same infrareds. So when several robots try to send in the same 
time, you are likely to receive only wrong messages.
In addition, IR communications are slightly sensitive to light conditions. If 
you want to get close to 0 messages lost, try to work with controlled light, 
emitting few infrareds, and without oscillations.

* Timers 
libIrcom is cpu consuming because it is monitoring very regularly the sensors.
The interrupt used is set to a high priority which may superseed others. If you
use agendas or any other interrupt, it is likely that some steps are lost.
To cope with this problems of timing, we have implemented a time counter inside
libIrcom (see ircomTools.c). libIrcom is the only tool that can give you accurate 
timings.

* Messages going through a robot or blocked by a wall
Infrared is light. Therefore a message can not be sent accross an opaque material.
Given that e-pucks are transparent, it is possible that a message goes accross
a robot. Do not expect that a robot is necessarily preventing messages to go 
through, make some tests.


More informations
================================================================================
Find more informations on http://www.e-puck.org, or on the GNA community 
https://gna.org/projects/e-puck/


Contact the authors
================================================================================
For specific requests you may also contact the authors of this software 
Alexandre Campo : alexandre.campo@ulb.ac.be
Alvaro Gutierrez : aguti@etsit.upm.es
Valentin Longchamp : valentin.longchamp@epfl.ch


