GCtronic wiki - User contributions [en]

Elisa-3

2026-06-22T13:23:23Z

WikiSysop: /* Internal EEPROM */

[[Category:elisa3]]
[[Category:all]]
=Overview=
[[File:Elisa3_and_charger.JPG|350px]] 
Elisa-3 is an evolution of the [https://www.gctronic.com/doc/index.php/Elisa Elisa] robot based on a different microcontroller and including a comprehensive set of sensors:
* [https://projects.gctronic.com/elisa3/atmega640-1280-1281-2560-2561_datasheet.pdf Atmel 2560] microcontroller (Arduino compatible)
* central RGB led
* 8 green leds around the robot
* IRs emitters
* 8 IR proximity sensors ([https://projects.gctronic.com/elisa3/tcrt1000.pdf Vishay Semiconductors Reflective Optical Sensor])
* 4 ground sensors ([https://projects.gctronic.com/elisa3/QRE1113-D.PDF Fairchild Semiconductor Minature Reflective Object Sensor])
* 3-axis accelerometer ([https://projects.gctronic.com/elisa3/MMA7455L.pdf Freescale MMA7455L])
* RF radio for communication ([https://www.nordicsemi.com/kor/Products/2.4GHz-RF/nRF24L01P Nordic Semiconductor nRF24L01+])
* micro USB connector for programming, debugging and charging
* IR receiver
* 2 DC motors
* top light diffuser
* selector
The robot is able to self charge using the charger station, as shown in the previous figure. The following figure illustrates the position of the various sensors: 
[[File:Elisa3-mainComp-digital-white.png|400px]] 

==Useful information==
* the top light diffuser and robot are designed to lock together, but the diffuser isn't fixed and can thus be removed as desired; the top light diffuser, as the name suggests, helps the light coming from the RGB led to be smoothly spread out, moreover the strip attached around the diffuser let the robot be better detected from others robots. Once the top light diffuser is removed, pay attention not to look at the RGB led directly. In order to remove the top light diffuser simply pull up it, then to place it back on top of the robot remember to align the 3 holes in the diffuser with the 3 IRs emitters and push down carefully untill the diffuser is stable; pay attention to not apply too much force on the IRs emitters otherwise they can bend and stop working.
[[File:Diffuser-pull-up.jpg|200px]] [[File:Diffuser-push-down.jpg|200px]] 
* when the top light diffuser is fit on top of the robot, then in order to change the selector position you can use the tweezers; the selector is located near the front-left IR emitter, as shown in the following figure:
[[File:selector-tweezers.jpg|200px]] 
* if you encounter problems with the radio communication (e.g. lot of packet loss) then you can try moving the antenna that is a wire near the robot label. Place the antenna as high as possible, near the plastic top light diffuser; try placing it in the borders in order to avoid seeing a black line on the top light diffuser when the RGB led is turned on.
[[File:Antenna-position.jpg|200px]] [[File:Antenna-diffuser.jpg|200px]] 

==Robot charging==
The Elisa-3 can be piloted in the charger station in order to be automatically self charged; there is no need to unplug the battery for charing. The following figures shows the robot approaching the charger station; a led indicates that the robot is in charge:
 
[[File:Elisa3-charger-out.jpg|300px]] [[File:Elisa3-charger-in.jpg|350px]] 

The microcontroller is informed when the robot is in charge and this information is also transferred to the PC in the ''flags'' byte; this let the user be able to pilote the robot to the charger station and be informed when it is actually in charge. More information about the radio protocol can be found in the section [https://www.gctronic.com/doc/index.php/Elisa-3#Communication Communication].

Moreover the robot is also charged when the micro USB cable is connected to a computer; pay attention that if the USB cable is connected to a hub, this one need to be power supplied.

The following video shows the Elisa-3 piloted through the radio to the charging station using the monitor application: {{#ev:youtube|kjliXlQcgzw}}

==Top light diffuser==
From February 2013 onwards the Elisa-3 is equipped with a new top light diffuser designed to fit perfectly in the 3 IRs emitters of the robot. The diffuser is made of plastic (3d printed), it is more robust and it simplifies the removal and insertion. Here is an image: 
[[File:elisa3-new-case.jpg|350px]] 

=Hardware=
The following figures show the main components offered by the Elisa-3 robot and where they are physically placed: 
[[File:Elisa3.1-hw-schema-top.jpg|550px]] 
[[File:Elisa3-hw-schema-bottom3.jpg|400px]] 

==Power autonomy==
The robot is equipped with two batteries for a duration of about 3 hours at normal usage (motors run continuously, IRs and RGB leds turned on).
[[File:Power-autonomy.jpg|800px]] 

==Detailed specifications==
{| border="1"
|'''Feature'''
|'''Technical information'''
|-
|Size, weight
|50 mm diameter, 30 mm height, 39 g
|-
|Battery, autonomy
|LiIPo rechargeable battery (2 x 130 mAh, 3.7 V). About 3 hours autonomy. Recharging time about 1h e 30.
|-
|Processor
|Atmel ATmega2560 @ 8MHz (~ 8 MIPS); 8 bit microcontroller
|-
|Memory
|RAM: 8 KB; Flash: 256 KB; EEPROM: 4 KB
|-
|Motors
|2 DC motors with a 25:1 reduction gear; speed controlled with backEMF
|-
|Magnetic wheels
|Adesion force of about 1 N (100 g) depending on surface material and painting Wheels diamater = 9 mm Distance between wheels = 40.8 mm
|-
|Speed
|Max: 60 cm/s
|-
|Mechanical structure
|PCB, motors holder, top white plastic to diffuse light
|-
|IR sensors
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm; each sensor is 45° away from each other 4 ground sensors detecting the end of the viable surface (placed on the front-side of the robot)
|-
| IR emitters
| 3 IR emitters (2 on front-side, 1 on back-side of the robot)
|-
|Accelerometer
|3D accelerometer along the X, Y and Z axis
|-
|LEDs
|1 RGB LED in the center of the robot; 8 green LEDs around the robot
|-
|Switch / selector
|16 position rotating switch
|-
|Communication
| Standard Serial Port (up to 38kbps) Wireless: RF 2.4 GHz; the throughput depends on number of robot: eg. 250Hz for 4 robots, 10Hz for 100 robots; up to 10 m
|-
|Remote Control
|Infra-red receiver for standard remote control commands
|-
|Expansion bus
|Optional connectors: 2 x UART, I2C, 2 x PWM, battery, ground, analog and digital voltage
|-
|Programming
|C/C++ programming with the AVR-GCC compiler ([https://winavr.sourceforge.net/ WinAVR] for Windows). Free compiler and IDE (AVR Studio / Arduino)
|}

=Communication=
==Wireless==
The radio base-station is connected to the PC through USB and transfers data to and from the robot wirelessly. In the same way the radio chip ([https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P nRF24L01+]) mounted on the robot communicates through SPI with the microcontroller and transfers data to and from the PC wirelessly. 
The robot is identified by an address that is stored in the last two bytes of the microcontroller internal EEPROM; the robot firmware setup the radio module reading the address from the EEPROM. This address corresponds to the robot id written on the label placed under the robot and should not be changed. 
[[File:Elisa-communication.jpg|400px]] 

===Packet format - PC to radio to robot===
The 13 bytes payload packet format is shown below (the number in the parenthesis expresses the bytes):
{| border="1"
| Command (1)
| Red led (1)
| Blue led (1)
| Green led (1)
| IR + Flags (1)
| Right motor (1)
| Left motor (1)
| Small green leds (1)
| Flags2 (1)
| Reserved (1)
| Remaining 4 bytes are unused
|}

* Command: 0x27 = change robot state; 0x28 = goto base-station bootloader (this byte is not sent to the robot)
* Red, Blue, Green leds: values from 0 (OFF) to 100 (ON max power)
* IR + flags:
** first two bits are dedicated to the IRs:
*** 0x00 => all IRs off
*** 0x01 => back IR on
*** 0x02 => front IRs on
*** 0x03 => all IRs on
** third bit is reserved for enabling/disabling IR remote control (0=>disabled, 1=>enabled)
** fourth bit is used for sleep (1 => go to sleep for 1 minute)
** fifth bit is used to calibrate all sensors (proximity, ground, accelerometer) and reset odometry
** sixth bit is reserved (used by radio station)
** seventh bit is used for enabling/disabling onboard obstacle avoidance
** eight bit is used for enabling/disabling onboard cliff avoidance
* Right, Left motors: speed expressed in 1/5 of mm/s (i.e. a value of 10 means 50 mm/s); MSBit indicate direction: 1=forward, 0=backward; values from 0 to 127
* Small green leds: each bit define whether the corresponding led is turned on (1) or off (0); e.g. if bit0=1 then led0=on
* Flags2:
** bit0 is used for odometry calibration
** remaining bits unused
* Remaining bytes free to be used

====Optimized protocol====
The communication between the pc and the base-station is controlled by the master (computer) that continuously polls the slave (base-station); the polling is done once every millisecond and this is a restriction on the maximum communication throughput. To overcome this limitation we implemented an optimized protocol in which the packet sent to the base-station contains commands for four robots simultaneously; the base-station then separate the data and send them to the correct robot address. The same is applied in reception, that is the base-station is responsible of receiving the ack payloads of 4 robots (64 bytes in total) and send them to the computer. This procedure let us have a throughput 4 times faster.


===Packet format - robot to radio to PC===
The robot send back to the base-station information about all its sensors every time it receive a command; this is accomplished by using the "ack payload" feature of the radio module. Each "ack payload" is 16 bytes length and is marked with an ID that is used to know which information the robot is currently transferring. The sequence is the following (the number in the parenthesis expresses the bytes):
{| border="1"
|ID=3 (1)
|Prox0 (2)
|Prox1 (2)
|Prox2 (2)
|Prox3 (2)
|Prox5 (2)
|Prox6 (2)
|Prox7 (2)
|Flags (1)
|-
|||||||||||||||||
|-
|ID=4 (1)
|Prox4 (2)
|Ground0 (2)
|Ground1 (2)
|Ground2 (2)
|Ground3 (2)
|AccX (2)
|AccY (2)
|TV remote (1)
|-
|||||||||||||||||
|-
|ID=5 (1)
|ProxAmbient0 (2)
|ProxAmbient1 (2)
|ProxAmbient2 (2)
|ProxAmbient3 (2)
|ProxAmbient5 (2)
|ProxAmbient6 (2)
|ProxAmbient7 (2)
|Selector (1)
|-
|||||||||||||||||
|-
|ID=6 (1)
|ProxAmbient4 (2)
|GroundAmbient0 (2)
|GroundAmbient1 (2)
|GroundAmbient2 (2)
|GroundAmbient3 (2)
|AccZ (2)
|Battery (2)
|Free (1)
|-
|||||||||||||||||
|-
|ID=7 (1)
|LeftSteps (4)
|RightSteps (4)
|theta (2)
|xpos (2)
|ypos (2)
|Free (1)
|
|
|}

Pay attention that the base-station could return "error" codes in the first byte if the communication has problems:
* 0 => transmission succeed (no ack received though)
* 1 => ack received (should not be returned because if the ack is received, then the payload is read)
* 2 => transfer failed

Packet ID 3:
* Prox* contain values from 0 to 1023, the greater the values the nearer the objects to the sensor
* The ''Flags'' byte contains these information:
** bit0: 0 = robot not in charge; 1 = robot in charge
** bit1: 0 = button pressed; 1 = button not pressed
** bit2: 0 = robot not charged completely; 1 = robot charged completely
** the remainig bits are not used at the moment

Packet ID 4:
* Prox4 contains values from 0 to 1023, the greater the values the nearer the objects to the sensor
* Ground* contain values from 512 to 1023, the smaller the value the darker the surface
* AccX and AccY contain raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* TV remote contains the last interpreted command received through IR

Packet ID 5:
* ProxAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* Selector contains the value of the current selector position

Packet ID 6:
* ProxAmbient4 contains values from 0 to 1023, the smaller the values the brighter the ambient light
* GroundAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* AccZ contains raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* Battery contains the sampled value of the battery, the values range is between 780 (battery discharged) and 930 (battery charged)

Packet ID 7:
* LeftSteps and RightSteps contain the sum of the sampled speed for left and right motors respectively (only available when the speed controller isn't used; refer to xpos, ypos and theta when the speed controller is used)
* theta contains the orientation of the robot expressed in 1/10 of degree (3600 degrees for a full turn); available only when the speed controller is enabled
* xpos and ypos contain the position of the robot expressed in millimeters; available only when the speed controller is enabled

==USB cable==
You can directly connect the robot to the computer to make a basic functional test. You can find the source code in the following link [https://projects.gctronic.com/elisa3/Elisa3-global-test.zip Elisa3-global-test.zip] (Windows). 
To start the test follow these steps:
# put the selector in position 6
# connect the robot to the computer with the USB cable and turn it on
# run the program, insert the correct COM port and choose option 1
With the same program you can also change the ID of the robot by choosing option 2 in the last step (not recommended).

Via USB cable you can also program the robot with [https://www.gctronic.com/doc/index.php?title=Elisa-3#Aseba Aseba].

=Software=

==Robot==
===Requirements===
In order to communicate with the robot through the micro USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise you need to download the drivers for your system and architecture:
* [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.10.00%20WHQL%20Certified.exe Windows Vista/XP], [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.12.10%20WHQL%20Certified.exe Windows 7/8/10 (run as administrator)]
* Ubuntu: when the robot is connected the port will be created in <code>/dev/ttyUSB0</code> (no need to install a driver)
* [https://www.ftdichip.com/drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (32 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (64 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_3.dmg Mac OS X 10.9 and above]; after installing the driver the port will be created in <code>/dev/tty.usbserial-...</code>; you can find a guide on how to install the driver in the following link [https://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf]
All the drivers can be found in the official page from the following link [https://www.ftdichip.com/Drivers/VCP.htm FTDI drivers]. 
Starting from robot ID 3823 the USB to serial chip can be one of the following: FTDI, [https://projects.gctronic.com/elisa3/CypressDriverInstaller_1.exe Cypress CY7C65213] or Silicon Labs CP2102 ([https://projects.gctronic.com/elisa3/CP210x_Universal_Windows_Driver.zip Windows 10 or later], [https://projects.gctronic.com/elisa3/CP210x_Windows_Drivers.zip Windows 7]); this is due to chips availability.

===AVR Studio 4 project===
The projects are built with [https://projects.gctronic.com/elisa3/AvrStudio4Setup.exe AVR Studio 4] released by Atmel. 
The projects should be compatible also with newer versions of Atmel Studio (last version known as Microchip Studio), the last version is available from [https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive]. 

====Basic demo====
This project is thought to be a starting point for Elisa-3 newbie users and basically contains a small and clean main with some basic demos selected through the hardware selector that show how to interact with robot sensors and actuators.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_basic https://github.com/gctronic/elisa3_firmware_basic]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-basic_ffb3947_21.03.18.hex Elisa-3 basic firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors

====Advanced demo====
This is an extension of the ''basic demo project'', basically it contains some additional advanced demos.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_advanced.git https://github.com/gctronic/elisa3_firmware_advanced.git]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-advanced_96c355a_13.03.18.hex Elisa-3 advanced firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors
* 6: robot testing and address writing through serial connection (used in production)
* 7: automatic charging demo (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Videos Videos]), that is composed of 4 states:
** random walk with obstacle avoidance
** search black line
** follow black line that lead to the charging station
** charge for a while
* 8: autonomous odometry calibration (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Autonomous_calibration Autonomous calibration])
* 9: write default odometry calibration values in EEPROM (hard-coded values); wait 2 seconds before start writing the calibration values
* 10: robot moving forward (with pause) and obstacle avoidance enabled; random RGB colors and green led effect
* 11: local communication: robot alignment
* 12: local communication: 2 or more robots exchange data sequentially
* 13: local communication: listen and transmit continuously; when data received change RGB color
* 14: local communication: RGB color propagation
* 15: clock calibration (communicate with the PC through the USB cable to change the OSCCAL register); this position could also be used to remote contol the robot through the radio (only speed control is enabled)

====Atmel Studio 7 / Microchip Studio====
If you are working with Atmel Studio 7 / Microchip Studio, you can simply use the provided AVR Studio 4 projects by importing them directly in Atmel Studio 7 / Microchip Studio: <code>File => Import => AVR Studio 4 Project</code>, then select <code>Elisa3-avr-studio.aps</code> and click on <code>Convert</code>.

If you are asked to update some components (see following figure), then agree: 
[[File:atmel-studio-convert.png|400px]] 

Then click on <code>Build => Clean solution</code> and then <code>Build => Build solution</code>.

If you experience problems during the building, make sure you have the correct toolchain installed: you can download WinAVR toolchain from [https://projects.gctronic.com/elisa3/WinAVR-20100110-install.exe WinAVR-20100110-install.exe]. 
Close and open again Atmel/Microchip Studio and verify that the new toolchain is recognized and that the path is correct: <code>Tools => Options</code> and on the left panel select <code>Toolchain => Package Configuration</code>. Select on top <code>Atmel AVR 8-bit (C language)</code>, then <code>WinAVR</code> flavour and verify the path corresponds to the WinAVR installation path. The following figure shows the toolchain configuration: 
[[File:elisa3-atmelstudio1.png|400px]] 

Finally verify the project is using the WinAVR toolchain: <code>right click on the project name => Properties</code>, on the left panel select <code>Advanced</code> and verify that <code>Toolchain Flavour</code> is set to WinAVR. Press <code>CTRL+S</code> to save your project configuration changes. The following figures show the project configuration: 
[[File:elisa3-atmelstudio2.png|200px]] [[File:elisa3-atmelstudio3.png|400px]] 

===Arduino IDE project===
The project is built with the Arduino IDE 1.x freely available from the [https://arduino.cc/ official Arduino website]. In order to build the Elisa-3 firmware with the Arduino IDE 1.x the following steps has to be performed: 
*1. download the [https://arduino.cc/hu/Main/Software Arduino IDE 1.x] (the last known working version is 1.8.9, refer to [https://www.arduino.cc/en/Main/OldSoftwareReleases#previous Arduino Software]) and extract it, let say in a folder named <code>arduino-1.x</code> 
*2. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_library_03.02.25_65964ed.zip Elisa-3 Arduino library] and extract it within the libraries folder of the Arduino IDE, in this case <code>arduino-1.x\libraries</code> (see [https://support.arduino.cc/hc/en-us/articles/4415103213714-Find-sketches-libraries-board-cores-and-other-files-on-your-computer Find-sketches-libraries-board-cores-and-other-files-on-your-computer] for more information on Arduino useful paths); you should end up with a <code>Elisa3</code> folder within the libraries. If you start the Arduino IDE now you can see that the <code>Elisa-3</code> library is available in the menu <code>Sketch=>Import Library...</code> (or <code>Sketch=>Include Lirary</code> in later IDE versions). In later versions of Arduino IDE you can also install the library via menu: <code>Sketch=>Include Library=>Add .ZIP library</code>, for more info have a look at [https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#importing-a-zip-library importing-a-zip-library].
*3. the file <code>boards.txt</code> in the Arduino IDE folder <code>arduino-1.x\hardware\arduino</code> (or <code>arduino-1.x\hardware\arduino\avr</code> or <code>Users\{username}\AppData\Local\Arduino15\packages\arduino\hardware\avr\1.8.6</code> in later IDE versions) need to be changed to contain the definitions for the Elisa-3 robot, add the following definitions at the end of the file:
<pre>
##############################################################

elisa3.name=Elisa 3 robot

elisa3.upload.tool=avrdude
elisa3.upload.tool.serial=avrdude
elisa3.upload.protocol=stk500v2
elisa3.upload.maximum_size=258048
elisa3.upload.speed=57600

elisa3.bootloader.low_fuses=0xE2
elisa3.bootloader.high_fuses=0xD0
elisa3.bootloader.extended_fuses=0xFF
elisa3.bootloader.path=stk500v2-elisa3
elisa3.bootloader.file=stk500v2-elisa3.hex
elisa3.bootloader.unlock_bits=0x3F
elisa3.bootloader.lock_bits=0x0F

elisa3.build.mcu=atmega2560
elisa3.build.f_cpu=8000000L
elisa3.build.board=AVR_ELISA3
elisa3.build.core=arduino
elisa3.build.variant=mega

##############################################################
</pre>
*4. this step need to be performed only with later IDE versions, when you receive a warning like this <code>Bootloader file specified but missing...</code> during compilation. In this case place the bootloader hex file (<code>stk500v2.hex</code>) you can find in the [https://www.gctronic.com/doc/index.php/Elisa-3#Bootloader Bootloader section] in the directory <code>arduino-1.x\Arduino\hardware\arduino\avr\bootloaders\</code> and name it <code>stk500v2-elisa3.hex</code>
*5. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_project_02.03.21_d2c017e.zip Elisa-3 project file] and open it with the Arduino IDE (you should open the file "''elisa3.ino''")
*6. select <code>Elisa-3 robot</code> from the <code>Tools=>Board</code> menu; click on the <code>Verify</code> button to build the project
*7. turn on the robot, attach the micro USB and wait the blinks terminate. 

*8. to upload the resulting hex file, from the Arduino IDE set the port from the <code>Tools=>Serial Port</code> menu consequently; click on the <code>Upload</code> button
: Only for Windows users: before clicking on <code>Upload</code>, open the serial monitor from the Arduino IDE (<code>Tools => Serial Monitor</code> or <code>Ctrl+Shift+M</code>), the robot should then blink again; keep the serial monitor opened.


You can download the Arduino IDE 1.0.5 for Linux (32 bits) containing an updated avr toolchain (4.5.3) and the Elisa3 library from the following link [https://projects.gctronic.com/elisa3/arduino-1.0.5-linux32.zip arduino-1.0.5-linux32.zip]. 
If the <code>Tools->Serial Port</code> menu is grayed out then you need to start the Arduino IDE in a terminal typing <code>sudo path/to/arduino</code>. 

If you want to have access to the compiler options you can download the following project [https://projects.gctronic.com/elisa3/Elisa3-arduino-makefile.zip Elisa3-arduino-makefile.zip] that contains an Arduino IDE project with a Makefile, follow the instructions in the "readme.txt" file in order to build and upload to the robot.

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

===Aseba===
Refer to the page [{{fullurl:Elisa-3 Aseba}} Elisa-3 Aseba].

===Matlab===
[[File:elisa3-matlab.jpg|200px]] 
The [https://www.e-puck.org/index.php?option=com_content&view=article&id=29&Itemid=27 ePic2] Matlab interface was adapted to work with the Elisa-3 robot. The communication is handled with the radio module. Both Matlab 32 bits and 64 bits are supported (tested on Matlab R2010a). Follow these steps to start playing with the interface:
# program the robot with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced demo]
# place the selector in position 15 (to pilot the robot through the interface with no obstacle and no cliff avoidance)
# connect the radio base-station to the computer
# download the ePic2 for Elisa-3 from the repository [https://github.com/gctronic/elisa3_epic.git https://github.com/gctronic/elisa3_epic.git]: either from github site clicking on <code>Code</code>=><code>Download ZIP</code> or by issueing the command <code>git clone https://github.com/gctronic/elisa3_epic.git</code>
# open (double click) the file ''main.m''; once Matlab is ready type ''main+ENTER'' and the GUI should start
# click on the ''+'' sign (top left) and insert the robot address (e.g 3307), then click on ''Connect''

===Webots simulator===
[[File:Elisa-3-webots.png|200px]] 
The following features have been included in the Elisa-3 model for the [https://www.cyberbotics.com/ Webots simulator]:
* proximity sensors
* ground sensors
* accelerometer
* motors
* green leds around the robot
* RGB led
* radio communication

You can donwload the Webots project containig the Elisa-3 model (proto) and a demonstration world in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots.zip Elisa-3-webots.zip].

You can download a Webots project containing a demonstration world illustrating the usage of the radio communication between 10 Elisa-3 robots and a supervisor in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots-radio.zip Elisa-3-webots-radio.zip]. Here is a video of this demo: 
{{#ev:youtube|IEgCo3XSESU}}

===Onboard behaviors===
The released firmware contains two basic onboard behaviors: obstacle and cliff avoidance. Both can be enabled and disabled from the computer through the radio (seventh bit of flags byte for obstacle avoidance, eight bit of flags byte for cliff avoidance).
The following videos show three robots that have their obstacle avoidance enabled:{{#ev:youtube|EbroxwWG-x4}} {{#ev:youtube|q6IRWRlTQeQ}}

===Programming===
The robot is pre-programmed with a serial bootloader. In order to upload a new program to the robot a micro USB cable is required. The connection with the robot is shown below: 
[[File:Elisa3.1-programming.jpg|400px]] 

If you are working with the Arduino IDE you don't need to follow this procedure, refer instead to section [https://www.gctronic.com/doc/index.php/Elisa-3#Arduino_IDE_project Arduino IDE project].

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

====Windows 7====
# Download the [https://projects.gctronic.com/elisa3/programming/AVR-Burn-O-Mat-Windows7.zip Windows 7 package] and extract it. The package contains also the FTDI driver. Beware that starting from robot id 4000 the USB driver might be different, refer to section [https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements Requirements], so you need to install it manually in case it isn't an FTDI chip.
# Execute the script <code>config.bat</code> and follow the installation; beware that this need to be done only once. The script will ask you to modify the registry, this is fine (used to save application preferences).
# Connect the robot to the computer; the COM port will be created.
# Run the application <code>AVR Burn-O-Mat.exe</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer (e.g. COM10); then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, connect the USB cable to the computer and wait the blinks terminate. Then open a terminal and issue the command <code>c:\windows\system32\mode.com com10: dtr=on</code> (change the port number accordingly to your robot). The robot should blink again, if this is not the case then try again the command.
# From the <code>AVR Burn-O-Mat</code> interface, click on <code>Write</code> in the <code>Flash</code> section. If you get an <code>Access is denied</code> error, then run <code>AVR Burn-O-Mat.exe</code> as administrator.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Mac OS X====
The following procedure is tested in Max OS X 10.10, but should work from Mac OS X 10.9 onwards; in these versions there is built-in support for the FTDI devices.
# Download the [https://projects.gctronic.com/elisa3/programming/AVR8-Burn-O-Mat-MacOsX.zip Mac OS X package] and extract it.
# Execute the script <code>config.sh</code> in the terminal, it will ask you to install the Java Runtime Environment; in case there is a problem executing the script try with <code>chmod +x config.sh</code> and try again. Beware that this need to be done only once.
# Connect the robot to the computer; the serial device will be created (something like <code>/dev/tty.usbserial-AJ03296J</code>).
# Run the application <code>AVR Burn-O-Mat</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer; then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Linux====
The following procedure was tested in Ubunut 12.04, but a similar procedure can be followed in newer systems and other Linux versions. 
You can find a nice GUI for <code>avrdude</code> in the following link [https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php]; you can download directly the application for Ubuntu from the following link [https://projects.gctronic.com/elisa3/programming/avr8-burn-o-mat-2.1.2-all.deb avr8-burn-o-mat-2.1.2-all.deb]. 
Double click the package and install it; the executable will be <code>avr8-burn-o-mat</code>. 
Beware that the application requires the Java SE Runtime Environment (JRE) that you can download from the official page [https://www.oracle.com/technetwork/java/javase/downloads/index.html https://www.oracle.com/technetwork/java/javase/downloads/index.html], alternatively you can issue the command <code>sudo apt-get install openjdk-8-jre</code> in the terminal.

The application need a bit of configuration, follow these steps:
:1. connect the robot to the computer, the serial device will be created (something like /dev/USB0)
:2. to use the USB port the permissions need to be set to read and write issueing the command <code>sudo chmod a+rw /dev/ttyUSB0</code>
:3. start the application and click on <code>Settings => AVRDUDE</code>
:4. set the location of <code>avrdude</code> and the related configuration file (refer to the previous section when <code>avrdude</code> was installed to know the exact location); the configuration file is in <code>/etc/avrdude.conf</code>
:3. click <code>OK</code>, close the application and open it again (this is needed to load the configuration file information); click on <code>Settings => AVRDUDE</code>
:4. select <code>stk500v2</code> as the <code>Programmer</code>
:5. set the serial port connected to the robot (<code>/dev/ttyUSB0</code>)
:6. in <code>additional options</code> insert <code>-b 57600</code>, you will end up with a window like the following one:
[[File:avrdude-gui.png|400px]] 
:7. click <code>OK</code>; select <code>ATmega2560</code> in the <code>AVR type</code>
:8. in the <code>Flash</code> section search the hex file you want to upload on the robot; select <code>Intel Hex</code> on the right
:9. connect the robot to the computer, turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section
:10. during the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Command line====
The [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility is used to do the upload, you can download it directly from the following links depending on your system:
* [https://projects.gctronic.com/elisa3/programming/WinAVR-20100110-install.exe Windows (tested on Windows 7 and 10)]; <code>avrdude</code> will be installed in the path <code>C:\WinAVR-20100110\bin\avrdude</code>; avrdude version 5.10
* [https://projects.gctronic.com/elisa3/programming/CrossPack-AVR-20131216.dmg Mac OS X]; <code>avrdude</code> will be installed in the path <code>/usr/local/CrossPack-AVR/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 6.0.1
* Ubuntu (12.04 32-bit): issue the command <code>sudo apt-get install avrdude</code> in the terminal; <code>avrdude</code> will be installed in the path <code>/usr/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 5.11.1

Open a terminal and issue the following commands:
# only for windows users: <code>c:\windows\system32\mode.com com10: dtr=on</code>. You should see the robot blink (blue), if this is not the case try again the command.
# <code>avrdude -p m2560 -P COM10 -b 57600 -c stk500v2 -D -Uflash:w:Elisa3-avr-studio.hex:i -v</code> 
where <code>COM10</code> must be replaced with your com port and <code>Elisa3-avr-studio.hex</code> must be replaced with your application name; in Mac OS X the port will be something like <code>/dev/tty.usbserial-...</code>, in Ubuntu will be <code>/dev/ttyUSB0</code>. 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Basic_demo Basic demo] and [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo Advanced demo] have this command contained in the file <code>program.bat</code> in the <code>default</code> directory within the project, this can be useful for Windows users. 

===Internal EEPROM===
The internal 4 KB EEPROM that resides in the microcontroller is pre-programmed with the robot ID in the last two bytes (e.g. if ID=3200 (0x0C80), then address 4094=0x80 and address 4095=0x0C). The ID represents also the RF address that the robot uses to communicate with the computer and is automatically read at startup (have a look a the firmware for more details). 
Moreover the address 4093 is used to save the clock calibration value that is found during production/testing of the robots; this value hasn't to be modified otherwise some functionalities such as tv remote control could not work anymore. For more information on clock calibration refers to the applicaiton note [https://projects.gctronic.com/elisa3/AVR053-Calibration-RC-oscillator.pdf AVR053: Calibration of the internal RC oscillator]. 
The Elisa-3 robot supports an autonomous calibration process and the result of this calibration is saved in EEPROM starting at address 3946 to 4092. 
'''The size of usable EEPROM is thus 3946 bytes (0-3945) and the remaining memory must not be modified/erased.'''

In order to program the eeprom an AVR programmer is required, we utilize the Pocket AVR Programmer from Sparkfun (recognized as USBtiny device); then with the [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility the following command has to be issued:
<pre>
avrdude -p m2560 -c usbtiny -v -U eeprom:w:Elisa3-eeprom.hex:i -v -B 1
</pre>
where ''Elisa3-eeprom.hex'' is the EEPROM memory saved as Intel Hex format ([https://projects.gctronic.com/elisa3/Elisa3-eeprom.hex eeprom example]); a possible tool to read and write Intel Hex format is [https://projects.gctronic.com/elisa3/G32setup_12004-intel-hex-editor.exe Galep32 from Conitec Datensysteme]. 
Alternatively a program designed to writing to these EEPROM locations can be uploaded to the robot, in case an AVR programmer isn't available. The project source is available in the repository [https://github.com/gctronic/elisa3_eeprom.git https://github.com/gctronic/elisa3_eeprom.git]; it is simply needed to modify the address, rebuild and upload to the robot. 
Another option is to use the following Python script [https://projects.gctronic.com/elisa3/write_radio_address.py write_radio_address.py] (tested in Ubuntu 22.04), the procedure would be:
# program the robot with the factory firmware
# put selector in position 6
# connect the robot to the computer via USB cable
# set the correct serial port and address in the script
# run the script
After a power-cycle the new address can be used.

===Bootloader===
In case the bootloader of the Elisa-3 is erased by mistake, then you can restore it by using an AVR programmer. You can download the bootloader from here [https://projects.gctronic.com/elisa3/stk500v2_20.03.18_13b46ce.hex stk500v2.hex]; the source code is available from the repository [https://github.com/gctronic/elisa3_bootloader.git https://github.com/gctronic/elisa3_bootloader.git]. 
<code>Avrdude</code> can be used to actually write the bootloader to the robot with a command similar to the following one: 
<code>avrdude -p m2560 -c stk500v2 -P COM348 -v -U lfuse:w:0xE2:m -U hfuse:w:0xD8:m -U efuse:w:0xFF:m -V -U flash:w:stk500v2.hex:i -v -B 2</code> 
Here we used a programmer recognized as a serial device (port COM348) that utilizes the <code>stk500v2</code> protocol.

==Base-station==
This chapter explains informations that aren't needed for most of the users since the radio module is ready to be used and don't need to be reprogrammed. Only if you are interested in the firmware running in the radio module and on how to reprogram it then refer to section [https://www.gctronic.com/doc/index.php/Elisa#Base-station https://www.gctronic.com/doc/index.php/Elisa#Base-station] (chapter 4.2) of the Elisa robot wiki.

==PC side==
This section gives informations related to the radio module connected to the computer; if you don't have a radio module you can skip this section.
===Requirements===
Refer to the section [https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver].

===Elisa-3 library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. Some basic examples will be provided in the following sections to show how to use this library. 
The source code of the library is available in the repository [https://github.com/gctronic/elisa3_remote_library https://github.com/gctronic/elisa3_remote_library]; follow the instructions in the repository to build the library.

===Multiplatform monitor===
The demo is a command line monitor that shows all the sensors information (e.g. proximity, ground, acceleromter, battery, ...) and let the user move the robot and change its colors and behavior with the keyboard. The data are sent using the protocol described in the previous section. 
The following figures show the monitor on the left and the available commands on the right. 
[[File:Cmd-line-monitor.jpg|400px]] [[File:Pc-side-commands2.jpg|400px]] 

The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_monitor https://github.com/gctronic/elisa3_remote_monitor]. 

====Windows====
Execution:
* install the driver contained in the [https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio nRFgo Studio tool] if not already done; this let the base-station be recognized as a WinUSB device (bootloader), independently of whether the libusb library is installed or not
* once the driver is installed, the pre-compiled "exe" (under <code>\bin\Release</code> dir) should run without problems; the program will prompt you the address of the robot you want to control

Compilation: 
the Code::Blocks project should already be setup to reference the Elisa-3 library headers and lib files, anyway you need to put this project within the same directory of the Elisa-3 library, e.g. you should have a tree similar to the following one:
* Elisa-3 demo (parent dir)
** <code>elisa3_remote_library</code> (Elisa-3 library project)
** <code>elisa3_remote_monitor</code> (current project)

====Linux / Mac OS X====
The project was tested to work also in Ubuntu and Mac OS X (no driver required). 
Compilation:
* you need to put this project within the same directory of the Elisa-3 library
* build command: go under "linux" dir and type <code>make clean && make</code>
Execution:
* <code>sudo ./main</code>

===Communicate with 4 robots simultaneously===
This example shows how to interact with 4 robots simlutaneously, basically it shows the sensors information (proximity and ground) coming from 4 robots and let control one robot at a time through the keyboard (you can change the robot you want to control). The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_multiple https://github.com/gctronic/elisa3_remote_multiple]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

===Obstacle avoidance===
This demo implements the ''obstacle avoidance'' behavior controlling the robot from the pc through the radio; this means that the robot reacts only to the commands received using the basic communication protocol and has no "intelligence" onboard. The demo uses the information gathered from the 3 front proximity sensors and set the motors speed accordingly; moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|F_b1TQxZKos}}

It is available also the same example but with 4 robots controlled simultaneously; the source can be downloaded from the branch <code>4robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa] 
It is easy to extend the previous example in order to control many robots, the code that controls 8 robots simultaneously can be downloaded from the branch <code>8robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa].

===Cliff avoidance===
This demo implements the ''cliff avoidance'' behavior controlling the robot from the pc through the radio; as with the ''obstacle avoidance'' demo, the robot reacts only to the commands received from the radio. The demo uses the information gathered from the 4 ground sensors to stop the robot when a cliff is detected (threshold tuned to run in a white surface); moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_cliff https://github.com/gctronic/elisa3_remote_cliff]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|uHy-9XXAHcs}}
===Communication between robots via PC===
This examples shows how to emulate direct communication between robots: basically a common state is shared between the robots and this state is changed based on the current state of each robot; it emulates the facts that each robot propagates its state to all other robots. Actually all the robots communicate only with the computer (only one computer with only one radio module) and the computer forward the information to all the others robots; the radio is fast enough so that the computer in the middle will not slow down the communication. A big advantage passing from the computer is that you can log the communication messages on the computer and see what is happening. 
In particular in this demo a total of 4 robots are handled and when a robot crosses a black line, then it inform all others robots to change their color. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_communication_between_robots_via_pc https://github.com/gctronic/elisa3_communication_between_robots_via_pc]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|4tpxoAyWfEA}}

===Set robots state from file===
This project show how to send data to robots for which we will know the address only at runtime, in particular the content of the packets to be transmitted is parsed from a csv file and the interpreted commands are sent to the robots one time. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_file https://github.com/gctronic/elisa3_remote_file]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 

===Elisa-3 Python library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. 
The source code of the library and some usage examples are available in the repository [https://github.com/gctronic/elisa3_remote_library_python https://github.com/gctronic/elisa3_remote_library_python]. 

=Odometry=
The odometry of Elisa-3 is quite good even if the speed is only measured by back-emf. On vertical surfaces the absolute angle is given by the accelerometer measuring g... quite a fix reference without drifting ;-) 
A fine calibration of the right and left wheel speed parameters might give better results.
However the current odometry is a good estimate of the absolute position from a starting point.
The experiments are performed on a square labyrinth and the robot advances doing obstacle avoidance. The on-board calculated (x,y,theta) position is sent to a PC via radio and logged for further display. 
[[File:odometry-vertical.jpg|400px]] 
Details about the code can be found in the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced-demo] project, in particular the ''motors.c'' source file. The PC application used for logging data is the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor].
==Autonomous calibration==
Since the motors can be slightly different a calibration can improve the behavior of the robot in terms of maneuverability and odometry accuracy.
An autonomous calibration process is implemented onboard: basically a calibration is performed for both the right and left wheels in two modes that are forward and backward with speed control enabled. In order to let the robot calibrate istelf a white sheet in which a black line is drawed is needed; the robot will measure the time between detection of the line at various speeds. The calibration sheet can be downloaded from the following link [https://projects.gctronic.com/elisa3/calibration-sheet.pdf calibration-sheet.pdf]. 
In order to accomplish the calibration the robot need to be programmed with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmare] and a specific command has to be sent to the robot through the radio module or the TV remote; if you are using the radio module you can use the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor application] in which the letter ''l (el)'' is reserved to launch the calibration, otherwise if you have a TV remote control you can press the button ''5''.
The sequence is the following: 
1. put the selector in position 8 
2. place the robot near the black line as shown below; the left motor is the first to be calibrated. Pay attention to place the right wheel as precise as possible with the black line 
[[File:elisa3-calibration-1.jpg|300px]] [[File:elisa3-calibration-2.jpg|300px]] 
3. once the robot is placed you can type the ''l (el)'' command (or press the button ''5''); wait a couple of minutes during which the robot will do various turns at various speed in the forward direction and then in the backward direction 
4. when the robot terminated (robot is stopped after going backward at high speed) you need to place it in the opposite direction in order to calibrate the right motor, as shown below. 
[[File:elisa3-calibration-3.jpg|300px]] 
5. once the robot is placed you can type again the ''l (el)'' command (or press the button ''5'') 
6. when the robot finish, the calibration process is also terminated. 

The previous figures show a robot without the top diffuser, anyway you don't need to remove it!

=Tracking=
==Assembly documentation==
You can download the documentation from here [https://projects.gctronic.com/elisa3/tracking-doc.pdf tracking-doc.pdf]. 
Have a look also at the video: 
{{#ev:youtube|92pz28hnteY}} 

==SwisTrack==
Some experiments are done with the [https://en.wikibooks.org/wiki/SwisTrack SwisTrack software] in order to be able to track the Elisa-3 robots through the back IR emitter, here is a resulting image with 2 robots: 
[[File:elisa-3-tracking-2robots.jpg|300px]] 
The pre-compiled SwisTrack software (Windows) can be downloaded from the following link [https://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip SwisTrack-compiled]. 


The following video shows the tracking of 5 robots: 
{{#ev:youtube|33lrIUux_0Q}} 
The SwisTrack software lets you easily log also the resulting data that you can then elaborate, here is an example taken from the experiment using 5 robots: 
[[File:swistrack-output.jpg|300px]] 

The following video shows the test done with 20, 30 and 38 Elisa-3 robots, the tracking is still good; it's important to notice that we stopped to 38 Elisa-3 robots because are the ones we have in our lab. 
{{#ev:youtube|5LAccIJ9Prs}} 

==Position control==
We developed a simple position control example that interacts with Swistrack through a TCP connection and control 4 robots simultaneously; the orientation of the robots is estimated only with the Swistrack information (delta position), future improvements will integrate odometry information. The following video shows the control of 4 robots that are driven in a ''8-shape''. 
{{#ev:youtube|ACaGNEQHayc}} 
[[File:tracking-8shape.jpg|300px]] 
All the following projects require the [https://www.gctronic.com/doc/index.php/Elisa-3#Elisa-3_library Elisa-3 library], for building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

* Horizontal position control (4 robots): the source code can be downloaded from [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-4-robots-rev245-15.01.21.zip position-control-pattern-horizontal-4-robots.zip] (Code::Blocks project). 
One of the characteristics of the Elisa-3 robot is that it can move in vertical thanks to its magnetic wheels, thus we developed also a vertical position control that use accelerometer data coming from the robot to get the orientation of the robot (more precise) instead of estimating it with the Swistrack information, you can download the source code from the following link:
* Vertical position control (4 robots): [https://projects.gctronic.com/elisa3/position-control-pattern-vertical-4-robots-rev245-15.01.21.zip position-control-pattern-vertical-4-robots.zip] (Code::Blocks project). 
We developed also an example of position control that control a single robot (code adapted from previous example) that can be useful during the initial environment installation/testing; you can download the source code from the following link:
* Horizontal position control (1 robot): [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-1-robot-rev245-15.01.21.zip position-control-pattern-horizontal-1-robot.zip] (Code::Blocks project). 
Another good example to start playing with the tracking is an application that lets you specify interactively the target point that the robot should reach; you can download the source code of this application from the following link:
* Go to target point: [https://projects.gctronic.com/elisa3/position-control-goto-pos-horizontal-1-robot-rev245-15.01.21.zip position-control-goto-pos-horizontal-1-robot.zip] (Code::Blocks project). 

==Utilities==
In order to adjust the IR camera position it is useful to have an application that turn on the back IR of the robots. The following application [https://projects.gctronic.com/elisa3/back-IR-on-4-robots-rev245-15.01.21.zip back-IR-on-4-robots-rev245-15.01.21.zip] is an example that turn on the back IR of 4 robots, their addresses are asked to the user at the execution.

=Local communication=
{{#ev:youtube|7bxIR0Z3q3M}} 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] is needed in order to use the local communication. You can find some examples on how to use this module in the main, refers to demos in selector position from 11 to 14. 
Here are some details about the current implementation of the communication module:
* use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; in the worst case (continuous receive and transmit) the sensor update frequency is about 3 Hz
* bidirectional communication
* id and angle of the proximity sensor that received the data are available
* the throughput is about 1 bytes/sec
* maximum communication distance is about 5 cm
* no reception/transmission queue (only one byte at a time)
* the data are sent using all the sensors, cannot select a single sensor from which to send the data. The data isn't sent contemporaneously from all the sensors, but the sensors used are divided in two groups of 4 alternating sensors (to reduce consumption)
== Clustering example==
In this demo there are 37 elisa-3 robots programmed with a special firmware that you can download here [https://projects.gctronic.com/elisa3/elisa3_cluster_firmware.hex elisa3_cluster_firmware.hex]; the source code is available in the repo [https://github.com/gctronic/elisa3_cluster_firmware https://github.com/gctronic/elisa3_cluster_firmware]. 
The robots will try to form some clusters by exchanging data through the local communication and at the same time exchange data with a central computer: they send their status (in cluster or not) and receive a new color when in cluster.
The application running on the computer side is available in the repo [https://github.com/gctronic/elisa3_cluster_pc https://github.com/gctronic/elisa3_cluster_pc]. 
Here is a video of the demo: 
{{#ev:youtube|MOuSfr1_3lg}}

=ROS=
This chapter explains how to use ROS with the elisa-3 robots; the radio module is needed here. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. The ROS node is implemented in cpp. Here is a general schema: 
[[File:elisa-ros-schema.png|450px]]
''Click to enlarge'' 

First of all you need to install and configure ROS, refer to [https://wiki.ros.org/Distributions https://wiki.ros.org/Distributions] for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Virtual_machine virtual machine]; this is the preferred way.
:* This tutorial is based on ROS Hydro. The same instructions are working with ROS Noetic, beware to use <code>noetic</code> instead of <code>hydro</code> when installing the packages.
:* If you downloaded the pre-installed VM you can go directly to section [https://www.gctronic.com/doc/index.php/Elisa-3#Running_the_ROS_node Running the ROS node].

The ROS elisa-3 node based on roscpp can be found in the following repository [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp]. 

==Initial configuration==
The following steps need to be done only once after installing ROS:
:1. If not already done, create a catkin workspace, refer to [https://wiki.ros.org/catkin/Tutorials/create_a_workspace https://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands:
<pre> mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws/
catkin_make
source devel/setup.bash </pre>
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
:3. Clone the elisa-3 ROS node repo from [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] inside the catkin workspace source folder (<tt>~/catkin_ws/src</tt>): <code>git clone https://github.com/gctronic/elisa3_node_cpp.git</code>
:4. Install the dependencies:
:ROS:
::* <code>sudo apt-get install ros-hydro-slam-gmapping</code>
::* <code>sudo apt-get install ros-hydro-imu-tools</code>
::If you are using a newer version of ROS, replace <code>hydro</code> with your distribution name.
:cpp:
::* install OpenCV: <code>sudo apt-get install libopencv-dev</code>
::If you are working with OpenCV 4, then you need to change the header include from <code>#include <opencv/cv.h></code> to <code>#include <opencv2/opencv.hpp></code>
:5. Rebuild the <code>elisa-3 library</code>: go to <code>~/catkin_ws/src/elisa3_node_cpp/src/pc-side-elisa3-library/linux</code>, then issue <code>make clean</code> and <code>make</code>
:6. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
:7. The USB radio module by default requires root priviliges to be accessed; to let the current user have access to the radio we use <tt>udev rules</tt>:

:* in the udev rules file you can find in <tt>/etc/udev/rules.d/name.rules</tt> add the following string changing the <tt>GROUP</tt> field with your current user group:
::<tt>SUBSYSTEMS=="usb", ATTRS{product}=="nRF24LU1P-F32 BOOT LDR", GROUP="viki"</tt>
:: To know which groups your user belongs to issue the command <tt>id</tt>
:* disconnect and reconnect the radio module
:8. Program the elisa-3 robot with the last [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] (>= rev.221) and put the selector in position 15

==Running the ROS node==
First of all get the last version of the elisa-3 ROS node from github:
* clone the repo [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] and copy the <tt>elisa3_node_cpp</tt> directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src)
* build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws). 

Now you can start the ROS node, for this purposes there is a launch script (based on [https://wiki.ros.org/roslaunch roslaunch]), as explained in the following section. Before starting the ROS node you need to start <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.

===Single robot===
Open a terminal and issue the following command: <code>roslaunch elisa3_node_cpp elisa3_single.launch elisa3_address:='1234'</code> where <tt>1234</tt> is the robot id (number on the bottom).

If all is going well [https://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the elisa ROS node as shown in the following figure: 
[[File:elisa-ros-single-robot.png|300px]]
''Click to enlarge'' 

The launch script is configured also to run the [https://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: 
{{#ev:youtube|v=k_9nmEO2zqE}}

==Move the robot==
You have two options to move the robot. 

The first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right. 
[[File:elisa-teleop.png|300px]]
''Click to enlarge'' 

The second method is by directly publishing on the <code>/mobile_base/cmd_vel</code> topic, for instance by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'</code> the robot will rotate on the spot, instead by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code> the robot will move straight forward. 
Beware that there shouldn't be any other node publishing on the <code>/mobile_base/cmd_vel</code> topic (e.g. Rviz), otherwise your commands will be overwritten.

==Troubleshooting==
===Robot state publisher===
If you get an error similar to the following when you start a node with roslaunch:
<pre>
ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)
</pre>
Then you need to change the launch file from:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="state_publisher" />
</pre>
To:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
</pre>
This is due to the fact that <code>state_publisher</code> was a deprecated alias for the node named <code>robot_state_publisher</code> (see [https://github.com/ros/robot_state_publisher/pull/87 https://github.com/ros/robot_state_publisher/pull/87]).

==Virtual machine==
To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and elisa. You can download the image as ''open virtualization format'' from the following link [https://projects.gctronic.com/VM/ROS-Hydro-12.04.ova ROS-Hydro-12.04.ova] (based on the VM from https://nootrix.com/2014/04/virtualized-ros-hydro/); you can then use [https://www.virtualbox.org/ VirtualBox] to import the file and automatically create the virtual machine. Some details about the system:
* user: gctronic, pw: gctronic
* Ubuntu 12.04.4 LTS (32 bits)
* ROS Hydro installed
* [https://www.cyberbotics.com/ Webots] 8.0.5 is installed (last version available for 32 bits linux)
* [https://git-cola.github.io/ git-cola] (git interface) is installed
* the <tt>catkin workspace</tt> is placed in the desktop

=Videos=
==Autonomous charge==
The following videos show 3 Elisa-3 robots moving around in the environment avoiding obstacles thanks to their proximity sensors and then going to the charging station autonomously; some black tape is placed in the charging positions to help the robots place themselves thanks to their ground sensors. The movement and charging is indipendent of the gravity. It works also vertically and up-side-down.
{{#ev:youtube|o--FM8zIrRk}}{{#ev:youtube|Ib9WdbwMlyQ}}{{#ev:youtube|xsOdxwOjmuI}}{{#ev:youtube|tprO126R9iA}}{{#ev:youtube|HVYp1Eujof8}}{{#ev:youtube|mtJd8jTWT94}}
==Remote control==
The following video shows 38 Elisa-3 robots moving around with onboard obstacle avoidance enabled; 15 of them are running autonmously, the remaining 23 are controlled from one computer with the radio module. 
{{#ev:youtube|WDxfIFhpm1g}}

Elisa-3

2026-06-22T13:22:23Z

WikiSysop: /* Internal EEPROM */

[[Category:elisa3]]
[[Category:all]]
=Overview=
[[File:Elisa3_and_charger.JPG|350px]] 
Elisa-3 is an evolution of the [https://www.gctronic.com/doc/index.php/Elisa Elisa] robot based on a different microcontroller and including a comprehensive set of sensors:
* [https://projects.gctronic.com/elisa3/atmega640-1280-1281-2560-2561_datasheet.pdf Atmel 2560] microcontroller (Arduino compatible)
* central RGB led
* 8 green leds around the robot
* IRs emitters
* 8 IR proximity sensors ([https://projects.gctronic.com/elisa3/tcrt1000.pdf Vishay Semiconductors Reflective Optical Sensor])
* 4 ground sensors ([https://projects.gctronic.com/elisa3/QRE1113-D.PDF Fairchild Semiconductor Minature Reflective Object Sensor])
* 3-axis accelerometer ([https://projects.gctronic.com/elisa3/MMA7455L.pdf Freescale MMA7455L])
* RF radio for communication ([https://www.nordicsemi.com/kor/Products/2.4GHz-RF/nRF24L01P Nordic Semiconductor nRF24L01+])
* micro USB connector for programming, debugging and charging
* IR receiver
* 2 DC motors
* top light diffuser
* selector
The robot is able to self charge using the charger station, as shown in the previous figure. The following figure illustrates the position of the various sensors: 
[[File:Elisa3-mainComp-digital-white.png|400px]] 

==Useful information==
* the top light diffuser and robot are designed to lock together, but the diffuser isn't fixed and can thus be removed as desired; the top light diffuser, as the name suggests, helps the light coming from the RGB led to be smoothly spread out, moreover the strip attached around the diffuser let the robot be better detected from others robots. Once the top light diffuser is removed, pay attention not to look at the RGB led directly. In order to remove the top light diffuser simply pull up it, then to place it back on top of the robot remember to align the 3 holes in the diffuser with the 3 IRs emitters and push down carefully untill the diffuser is stable; pay attention to not apply too much force on the IRs emitters otherwise they can bend and stop working.
[[File:Diffuser-pull-up.jpg|200px]] [[File:Diffuser-push-down.jpg|200px]] 
* when the top light diffuser is fit on top of the robot, then in order to change the selector position you can use the tweezers; the selector is located near the front-left IR emitter, as shown in the following figure:
[[File:selector-tweezers.jpg|200px]] 
* if you encounter problems with the radio communication (e.g. lot of packet loss) then you can try moving the antenna that is a wire near the robot label. Place the antenna as high as possible, near the plastic top light diffuser; try placing it in the borders in order to avoid seeing a black line on the top light diffuser when the RGB led is turned on.
[[File:Antenna-position.jpg|200px]] [[File:Antenna-diffuser.jpg|200px]] 

==Robot charging==
The Elisa-3 can be piloted in the charger station in order to be automatically self charged; there is no need to unplug the battery for charing. The following figures shows the robot approaching the charger station; a led indicates that the robot is in charge:
 
[[File:Elisa3-charger-out.jpg|300px]] [[File:Elisa3-charger-in.jpg|350px]] 

The microcontroller is informed when the robot is in charge and this information is also transferred to the PC in the ''flags'' byte; this let the user be able to pilote the robot to the charger station and be informed when it is actually in charge. More information about the radio protocol can be found in the section [https://www.gctronic.com/doc/index.php/Elisa-3#Communication Communication].

Moreover the robot is also charged when the micro USB cable is connected to a computer; pay attention that if the USB cable is connected to a hub, this one need to be power supplied.

The following video shows the Elisa-3 piloted through the radio to the charging station using the monitor application: {{#ev:youtube|kjliXlQcgzw}}

==Top light diffuser==
From February 2013 onwards the Elisa-3 is equipped with a new top light diffuser designed to fit perfectly in the 3 IRs emitters of the robot. The diffuser is made of plastic (3d printed), it is more robust and it simplifies the removal and insertion. Here is an image: 
[[File:elisa3-new-case.jpg|350px]] 

=Hardware=
The following figures show the main components offered by the Elisa-3 robot and where they are physically placed: 
[[File:Elisa3.1-hw-schema-top.jpg|550px]] 
[[File:Elisa3-hw-schema-bottom3.jpg|400px]] 

==Power autonomy==
The robot is equipped with two batteries for a duration of about 3 hours at normal usage (motors run continuously, IRs and RGB leds turned on).
[[File:Power-autonomy.jpg|800px]] 

==Detailed specifications==
{| border="1"
|'''Feature'''
|'''Technical information'''
|-
|Size, weight
|50 mm diameter, 30 mm height, 39 g
|-
|Battery, autonomy
|LiIPo rechargeable battery (2 x 130 mAh, 3.7 V). About 3 hours autonomy. Recharging time about 1h e 30.
|-
|Processor
|Atmel ATmega2560 @ 8MHz (~ 8 MIPS); 8 bit microcontroller
|-
|Memory
|RAM: 8 KB; Flash: 256 KB; EEPROM: 4 KB
|-
|Motors
|2 DC motors with a 25:1 reduction gear; speed controlled with backEMF
|-
|Magnetic wheels
|Adesion force of about 1 N (100 g) depending on surface material and painting Wheels diamater = 9 mm Distance between wheels = 40.8 mm
|-
|Speed
|Max: 60 cm/s
|-
|Mechanical structure
|PCB, motors holder, top white plastic to diffuse light
|-
|IR sensors
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm; each sensor is 45° away from each other 4 ground sensors detecting the end of the viable surface (placed on the front-side of the robot)
|-
| IR emitters
| 3 IR emitters (2 on front-side, 1 on back-side of the robot)
|-
|Accelerometer
|3D accelerometer along the X, Y and Z axis
|-
|LEDs
|1 RGB LED in the center of the robot; 8 green LEDs around the robot
|-
|Switch / selector
|16 position rotating switch
|-
|Communication
| Standard Serial Port (up to 38kbps) Wireless: RF 2.4 GHz; the throughput depends on number of robot: eg. 250Hz for 4 robots, 10Hz for 100 robots; up to 10 m
|-
|Remote Control
|Infra-red receiver for standard remote control commands
|-
|Expansion bus
|Optional connectors: 2 x UART, I2C, 2 x PWM, battery, ground, analog and digital voltage
|-
|Programming
|C/C++ programming with the AVR-GCC compiler ([https://winavr.sourceforge.net/ WinAVR] for Windows). Free compiler and IDE (AVR Studio / Arduino)
|}

=Communication=
==Wireless==
The radio base-station is connected to the PC through USB and transfers data to and from the robot wirelessly. In the same way the radio chip ([https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P nRF24L01+]) mounted on the robot communicates through SPI with the microcontroller and transfers data to and from the PC wirelessly. 
The robot is identified by an address that is stored in the last two bytes of the microcontroller internal EEPROM; the robot firmware setup the radio module reading the address from the EEPROM. This address corresponds to the robot id written on the label placed under the robot and should not be changed. 
[[File:Elisa-communication.jpg|400px]] 

===Packet format - PC to radio to robot===
The 13 bytes payload packet format is shown below (the number in the parenthesis expresses the bytes):
{| border="1"
| Command (1)
| Red led (1)
| Blue led (1)
| Green led (1)
| IR + Flags (1)
| Right motor (1)
| Left motor (1)
| Small green leds (1)
| Flags2 (1)
| Reserved (1)
| Remaining 4 bytes are unused
|}

* Command: 0x27 = change robot state; 0x28 = goto base-station bootloader (this byte is not sent to the robot)
* Red, Blue, Green leds: values from 0 (OFF) to 100 (ON max power)
* IR + flags:
** first two bits are dedicated to the IRs:
*** 0x00 => all IRs off
*** 0x01 => back IR on
*** 0x02 => front IRs on
*** 0x03 => all IRs on
** third bit is reserved for enabling/disabling IR remote control (0=>disabled, 1=>enabled)
** fourth bit is used for sleep (1 => go to sleep for 1 minute)
** fifth bit is used to calibrate all sensors (proximity, ground, accelerometer) and reset odometry
** sixth bit is reserved (used by radio station)
** seventh bit is used for enabling/disabling onboard obstacle avoidance
** eight bit is used for enabling/disabling onboard cliff avoidance
* Right, Left motors: speed expressed in 1/5 of mm/s (i.e. a value of 10 means 50 mm/s); MSBit indicate direction: 1=forward, 0=backward; values from 0 to 127
* Small green leds: each bit define whether the corresponding led is turned on (1) or off (0); e.g. if bit0=1 then led0=on
* Flags2:
** bit0 is used for odometry calibration
** remaining bits unused
* Remaining bytes free to be used

====Optimized protocol====
The communication between the pc and the base-station is controlled by the master (computer) that continuously polls the slave (base-station); the polling is done once every millisecond and this is a restriction on the maximum communication throughput. To overcome this limitation we implemented an optimized protocol in which the packet sent to the base-station contains commands for four robots simultaneously; the base-station then separate the data and send them to the correct robot address. The same is applied in reception, that is the base-station is responsible of receiving the ack payloads of 4 robots (64 bytes in total) and send them to the computer. This procedure let us have a throughput 4 times faster.


===Packet format - robot to radio to PC===
The robot send back to the base-station information about all its sensors every time it receive a command; this is accomplished by using the "ack payload" feature of the radio module. Each "ack payload" is 16 bytes length and is marked with an ID that is used to know which information the robot is currently transferring. The sequence is the following (the number in the parenthesis expresses the bytes):
{| border="1"
|ID=3 (1)
|Prox0 (2)
|Prox1 (2)
|Prox2 (2)
|Prox3 (2)
|Prox5 (2)
|Prox6 (2)
|Prox7 (2)
|Flags (1)
|-
|||||||||||||||||
|-
|ID=4 (1)
|Prox4 (2)
|Ground0 (2)
|Ground1 (2)
|Ground2 (2)
|Ground3 (2)
|AccX (2)
|AccY (2)
|TV remote (1)
|-
|||||||||||||||||
|-
|ID=5 (1)
|ProxAmbient0 (2)
|ProxAmbient1 (2)
|ProxAmbient2 (2)
|ProxAmbient3 (2)
|ProxAmbient5 (2)
|ProxAmbient6 (2)
|ProxAmbient7 (2)
|Selector (1)
|-
|||||||||||||||||
|-
|ID=6 (1)
|ProxAmbient4 (2)
|GroundAmbient0 (2)
|GroundAmbient1 (2)
|GroundAmbient2 (2)
|GroundAmbient3 (2)
|AccZ (2)
|Battery (2)
|Free (1)
|-
|||||||||||||||||
|-
|ID=7 (1)
|LeftSteps (4)
|RightSteps (4)
|theta (2)
|xpos (2)
|ypos (2)
|Free (1)
|
|
|}

Pay attention that the base-station could return "error" codes in the first byte if the communication has problems:
* 0 => transmission succeed (no ack received though)
* 1 => ack received (should not be returned because if the ack is received, then the payload is read)
* 2 => transfer failed

Packet ID 3:
* Prox* contain values from 0 to 1023, the greater the values the nearer the objects to the sensor
* The ''Flags'' byte contains these information:
** bit0: 0 = robot not in charge; 1 = robot in charge
** bit1: 0 = button pressed; 1 = button not pressed
** bit2: 0 = robot not charged completely; 1 = robot charged completely
** the remainig bits are not used at the moment

Packet ID 4:
* Prox4 contains values from 0 to 1023, the greater the values the nearer the objects to the sensor
* Ground* contain values from 512 to 1023, the smaller the value the darker the surface
* AccX and AccY contain raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* TV remote contains the last interpreted command received through IR

Packet ID 5:
* ProxAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* Selector contains the value of the current selector position

Packet ID 6:
* ProxAmbient4 contains values from 0 to 1023, the smaller the values the brighter the ambient light
* GroundAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* AccZ contains raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* Battery contains the sampled value of the battery, the values range is between 780 (battery discharged) and 930 (battery charged)

Packet ID 7:
* LeftSteps and RightSteps contain the sum of the sampled speed for left and right motors respectively (only available when the speed controller isn't used; refer to xpos, ypos and theta when the speed controller is used)
* theta contains the orientation of the robot expressed in 1/10 of degree (3600 degrees for a full turn); available only when the speed controller is enabled
* xpos and ypos contain the position of the robot expressed in millimeters; available only when the speed controller is enabled

==USB cable==
You can directly connect the robot to the computer to make a basic functional test. You can find the source code in the following link [https://projects.gctronic.com/elisa3/Elisa3-global-test.zip Elisa3-global-test.zip] (Windows). 
To start the test follow these steps:
# put the selector in position 6
# connect the robot to the computer with the USB cable and turn it on
# run the program, insert the correct COM port and choose option 1
With the same program you can also change the ID of the robot by choosing option 2 in the last step (not recommended).

Via USB cable you can also program the robot with [https://www.gctronic.com/doc/index.php?title=Elisa-3#Aseba Aseba].

=Software=

==Robot==
===Requirements===
In order to communicate with the robot through the micro USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise you need to download the drivers for your system and architecture:
* [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.10.00%20WHQL%20Certified.exe Windows Vista/XP], [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.12.10%20WHQL%20Certified.exe Windows 7/8/10 (run as administrator)]
* Ubuntu: when the robot is connected the port will be created in <code>/dev/ttyUSB0</code> (no need to install a driver)
* [https://www.ftdichip.com/drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (32 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (64 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_3.dmg Mac OS X 10.9 and above]; after installing the driver the port will be created in <code>/dev/tty.usbserial-...</code>; you can find a guide on how to install the driver in the following link [https://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf]
All the drivers can be found in the official page from the following link [https://www.ftdichip.com/Drivers/VCP.htm FTDI drivers]. 
Starting from robot ID 3823 the USB to serial chip can be one of the following: FTDI, [https://projects.gctronic.com/elisa3/CypressDriverInstaller_1.exe Cypress CY7C65213] or Silicon Labs CP2102 ([https://projects.gctronic.com/elisa3/CP210x_Universal_Windows_Driver.zip Windows 10 or later], [https://projects.gctronic.com/elisa3/CP210x_Windows_Drivers.zip Windows 7]); this is due to chips availability.

===AVR Studio 4 project===
The projects are built with [https://projects.gctronic.com/elisa3/AvrStudio4Setup.exe AVR Studio 4] released by Atmel. 
The projects should be compatible also with newer versions of Atmel Studio (last version known as Microchip Studio), the last version is available from [https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive]. 

====Basic demo====
This project is thought to be a starting point for Elisa-3 newbie users and basically contains a small and clean main with some basic demos selected through the hardware selector that show how to interact with robot sensors and actuators.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_basic https://github.com/gctronic/elisa3_firmware_basic]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-basic_ffb3947_21.03.18.hex Elisa-3 basic firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors

====Advanced demo====
This is an extension of the ''basic demo project'', basically it contains some additional advanced demos.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_advanced.git https://github.com/gctronic/elisa3_firmware_advanced.git]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-advanced_96c355a_13.03.18.hex Elisa-3 advanced firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors
* 6: robot testing and address writing through serial connection (used in production)
* 7: automatic charging demo (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Videos Videos]), that is composed of 4 states:
** random walk with obstacle avoidance
** search black line
** follow black line that lead to the charging station
** charge for a while
* 8: autonomous odometry calibration (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Autonomous_calibration Autonomous calibration])
* 9: write default odometry calibration values in EEPROM (hard-coded values); wait 2 seconds before start writing the calibration values
* 10: robot moving forward (with pause) and obstacle avoidance enabled; random RGB colors and green led effect
* 11: local communication: robot alignment
* 12: local communication: 2 or more robots exchange data sequentially
* 13: local communication: listen and transmit continuously; when data received change RGB color
* 14: local communication: RGB color propagation
* 15: clock calibration (communicate with the PC through the USB cable to change the OSCCAL register); this position could also be used to remote contol the robot through the radio (only speed control is enabled)

====Atmel Studio 7 / Microchip Studio====
If you are working with Atmel Studio 7 / Microchip Studio, you can simply use the provided AVR Studio 4 projects by importing them directly in Atmel Studio 7 / Microchip Studio: <code>File => Import => AVR Studio 4 Project</code>, then select <code>Elisa3-avr-studio.aps</code> and click on <code>Convert</code>.

If you are asked to update some components (see following figure), then agree: 
[[File:atmel-studio-convert.png|400px]] 

Then click on <code>Build => Clean solution</code> and then <code>Build => Build solution</code>.

If you experience problems during the building, make sure you have the correct toolchain installed: you can download WinAVR toolchain from [https://projects.gctronic.com/elisa3/WinAVR-20100110-install.exe WinAVR-20100110-install.exe]. 
Close and open again Atmel/Microchip Studio and verify that the new toolchain is recognized and that the path is correct: <code>Tools => Options</code> and on the left panel select <code>Toolchain => Package Configuration</code>. Select on top <code>Atmel AVR 8-bit (C language)</code>, then <code>WinAVR</code> flavour and verify the path corresponds to the WinAVR installation path. The following figure shows the toolchain configuration: 
[[File:elisa3-atmelstudio1.png|400px]] 

Finally verify the project is using the WinAVR toolchain: <code>right click on the project name => Properties</code>, on the left panel select <code>Advanced</code> and verify that <code>Toolchain Flavour</code> is set to WinAVR. Press <code>CTRL+S</code> to save your project configuration changes. The following figures show the project configuration: 
[[File:elisa3-atmelstudio2.png|200px]] [[File:elisa3-atmelstudio3.png|400px]] 

===Arduino IDE project===
The project is built with the Arduino IDE 1.x freely available from the [https://arduino.cc/ official Arduino website]. In order to build the Elisa-3 firmware with the Arduino IDE 1.x the following steps has to be performed: 
*1. download the [https://arduino.cc/hu/Main/Software Arduino IDE 1.x] (the last known working version is 1.8.9, refer to [https://www.arduino.cc/en/Main/OldSoftwareReleases#previous Arduino Software]) and extract it, let say in a folder named <code>arduino-1.x</code> 
*2. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_library_03.02.25_65964ed.zip Elisa-3 Arduino library] and extract it within the libraries folder of the Arduino IDE, in this case <code>arduino-1.x\libraries</code> (see [https://support.arduino.cc/hc/en-us/articles/4415103213714-Find-sketches-libraries-board-cores-and-other-files-on-your-computer Find-sketches-libraries-board-cores-and-other-files-on-your-computer] for more information on Arduino useful paths); you should end up with a <code>Elisa3</code> folder within the libraries. If you start the Arduino IDE now you can see that the <code>Elisa-3</code> library is available in the menu <code>Sketch=>Import Library...</code> (or <code>Sketch=>Include Lirary</code> in later IDE versions). In later versions of Arduino IDE you can also install the library via menu: <code>Sketch=>Include Library=>Add .ZIP library</code>, for more info have a look at [https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#importing-a-zip-library importing-a-zip-library].
*3. the file <code>boards.txt</code> in the Arduino IDE folder <code>arduino-1.x\hardware\arduino</code> (or <code>arduino-1.x\hardware\arduino\avr</code> or <code>Users\{username}\AppData\Local\Arduino15\packages\arduino\hardware\avr\1.8.6</code> in later IDE versions) need to be changed to contain the definitions for the Elisa-3 robot, add the following definitions at the end of the file:
<pre>
##############################################################

elisa3.name=Elisa 3 robot

elisa3.upload.tool=avrdude
elisa3.upload.tool.serial=avrdude
elisa3.upload.protocol=stk500v2
elisa3.upload.maximum_size=258048
elisa3.upload.speed=57600

elisa3.bootloader.low_fuses=0xE2
elisa3.bootloader.high_fuses=0xD0
elisa3.bootloader.extended_fuses=0xFF
elisa3.bootloader.path=stk500v2-elisa3
elisa3.bootloader.file=stk500v2-elisa3.hex
elisa3.bootloader.unlock_bits=0x3F
elisa3.bootloader.lock_bits=0x0F

elisa3.build.mcu=atmega2560
elisa3.build.f_cpu=8000000L
elisa3.build.board=AVR_ELISA3
elisa3.build.core=arduino
elisa3.build.variant=mega

##############################################################
</pre>
*4. this step need to be performed only with later IDE versions, when you receive a warning like this <code>Bootloader file specified but missing...</code> during compilation. In this case place the bootloader hex file (<code>stk500v2.hex</code>) you can find in the [https://www.gctronic.com/doc/index.php/Elisa-3#Bootloader Bootloader section] in the directory <code>arduino-1.x\Arduino\hardware\arduino\avr\bootloaders\</code> and name it <code>stk500v2-elisa3.hex</code>
*5. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_project_02.03.21_d2c017e.zip Elisa-3 project file] and open it with the Arduino IDE (you should open the file "''elisa3.ino''")
*6. select <code>Elisa-3 robot</code> from the <code>Tools=>Board</code> menu; click on the <code>Verify</code> button to build the project
*7. turn on the robot, attach the micro USB and wait the blinks terminate. 

*8. to upload the resulting hex file, from the Arduino IDE set the port from the <code>Tools=>Serial Port</code> menu consequently; click on the <code>Upload</code> button
: Only for Windows users: before clicking on <code>Upload</code>, open the serial monitor from the Arduino IDE (<code>Tools => Serial Monitor</code> or <code>Ctrl+Shift+M</code>), the robot should then blink again; keep the serial monitor opened.


You can download the Arduino IDE 1.0.5 for Linux (32 bits) containing an updated avr toolchain (4.5.3) and the Elisa3 library from the following link [https://projects.gctronic.com/elisa3/arduino-1.0.5-linux32.zip arduino-1.0.5-linux32.zip]. 
If the <code>Tools->Serial Port</code> menu is grayed out then you need to start the Arduino IDE in a terminal typing <code>sudo path/to/arduino</code>. 

If you want to have access to the compiler options you can download the following project [https://projects.gctronic.com/elisa3/Elisa3-arduino-makefile.zip Elisa3-arduino-makefile.zip] that contains an Arduino IDE project with a Makefile, follow the instructions in the "readme.txt" file in order to build and upload to the robot.

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

===Aseba===
Refer to the page [{{fullurl:Elisa-3 Aseba}} Elisa-3 Aseba].

===Matlab===
[[File:elisa3-matlab.jpg|200px]] 
The [https://www.e-puck.org/index.php?option=com_content&view=article&id=29&Itemid=27 ePic2] Matlab interface was adapted to work with the Elisa-3 robot. The communication is handled with the radio module. Both Matlab 32 bits and 64 bits are supported (tested on Matlab R2010a). Follow these steps to start playing with the interface:
# program the robot with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced demo]
# place the selector in position 15 (to pilot the robot through the interface with no obstacle and no cliff avoidance)
# connect the radio base-station to the computer
# download the ePic2 for Elisa-3 from the repository [https://github.com/gctronic/elisa3_epic.git https://github.com/gctronic/elisa3_epic.git]: either from github site clicking on <code>Code</code>=><code>Download ZIP</code> or by issueing the command <code>git clone https://github.com/gctronic/elisa3_epic.git</code>
# open (double click) the file ''main.m''; once Matlab is ready type ''main+ENTER'' and the GUI should start
# click on the ''+'' sign (top left) and insert the robot address (e.g 3307), then click on ''Connect''

===Webots simulator===
[[File:Elisa-3-webots.png|200px]] 
The following features have been included in the Elisa-3 model for the [https://www.cyberbotics.com/ Webots simulator]:
* proximity sensors
* ground sensors
* accelerometer
* motors
* green leds around the robot
* RGB led
* radio communication

You can donwload the Webots project containig the Elisa-3 model (proto) and a demonstration world in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots.zip Elisa-3-webots.zip].

You can download a Webots project containing a demonstration world illustrating the usage of the radio communication between 10 Elisa-3 robots and a supervisor in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots-radio.zip Elisa-3-webots-radio.zip]. Here is a video of this demo: 
{{#ev:youtube|IEgCo3XSESU}}

===Onboard behaviors===
The released firmware contains two basic onboard behaviors: obstacle and cliff avoidance. Both can be enabled and disabled from the computer through the radio (seventh bit of flags byte for obstacle avoidance, eight bit of flags byte for cliff avoidance).
The following videos show three robots that have their obstacle avoidance enabled:{{#ev:youtube|EbroxwWG-x4}} {{#ev:youtube|q6IRWRlTQeQ}}

===Programming===
The robot is pre-programmed with a serial bootloader. In order to upload a new program to the robot a micro USB cable is required. The connection with the robot is shown below: 
[[File:Elisa3.1-programming.jpg|400px]] 

If you are working with the Arduino IDE you don't need to follow this procedure, refer instead to section [https://www.gctronic.com/doc/index.php/Elisa-3#Arduino_IDE_project Arduino IDE project].

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

====Windows 7====
# Download the [https://projects.gctronic.com/elisa3/programming/AVR-Burn-O-Mat-Windows7.zip Windows 7 package] and extract it. The package contains also the FTDI driver. Beware that starting from robot id 4000 the USB driver might be different, refer to section [https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements Requirements], so you need to install it manually in case it isn't an FTDI chip.
# Execute the script <code>config.bat</code> and follow the installation; beware that this need to be done only once. The script will ask you to modify the registry, this is fine (used to save application preferences).
# Connect the robot to the computer; the COM port will be created.
# Run the application <code>AVR Burn-O-Mat.exe</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer (e.g. COM10); then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, connect the USB cable to the computer and wait the blinks terminate. Then open a terminal and issue the command <code>c:\windows\system32\mode.com com10: dtr=on</code> (change the port number accordingly to your robot). The robot should blink again, if this is not the case then try again the command.
# From the <code>AVR Burn-O-Mat</code> interface, click on <code>Write</code> in the <code>Flash</code> section. If you get an <code>Access is denied</code> error, then run <code>AVR Burn-O-Mat.exe</code> as administrator.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Mac OS X====
The following procedure is tested in Max OS X 10.10, but should work from Mac OS X 10.9 onwards; in these versions there is built-in support for the FTDI devices.
# Download the [https://projects.gctronic.com/elisa3/programming/AVR8-Burn-O-Mat-MacOsX.zip Mac OS X package] and extract it.
# Execute the script <code>config.sh</code> in the terminal, it will ask you to install the Java Runtime Environment; in case there is a problem executing the script try with <code>chmod +x config.sh</code> and try again. Beware that this need to be done only once.
# Connect the robot to the computer; the serial device will be created (something like <code>/dev/tty.usbserial-AJ03296J</code>).
# Run the application <code>AVR Burn-O-Mat</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer; then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Linux====
The following procedure was tested in Ubunut 12.04, but a similar procedure can be followed in newer systems and other Linux versions. 
You can find a nice GUI for <code>avrdude</code> in the following link [https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php]; you can download directly the application for Ubuntu from the following link [https://projects.gctronic.com/elisa3/programming/avr8-burn-o-mat-2.1.2-all.deb avr8-burn-o-mat-2.1.2-all.deb]. 
Double click the package and install it; the executable will be <code>avr8-burn-o-mat</code>. 
Beware that the application requires the Java SE Runtime Environment (JRE) that you can download from the official page [https://www.oracle.com/technetwork/java/javase/downloads/index.html https://www.oracle.com/technetwork/java/javase/downloads/index.html], alternatively you can issue the command <code>sudo apt-get install openjdk-8-jre</code> in the terminal.

The application need a bit of configuration, follow these steps:
:1. connect the robot to the computer, the serial device will be created (something like /dev/USB0)
:2. to use the USB port the permissions need to be set to read and write issueing the command <code>sudo chmod a+rw /dev/ttyUSB0</code>
:3. start the application and click on <code>Settings => AVRDUDE</code>
:4. set the location of <code>avrdude</code> and the related configuration file (refer to the previous section when <code>avrdude</code> was installed to know the exact location); the configuration file is in <code>/etc/avrdude.conf</code>
:3. click <code>OK</code>, close the application and open it again (this is needed to load the configuration file information); click on <code>Settings => AVRDUDE</code>
:4. select <code>stk500v2</code> as the <code>Programmer</code>
:5. set the serial port connected to the robot (<code>/dev/ttyUSB0</code>)
:6. in <code>additional options</code> insert <code>-b 57600</code>, you will end up with a window like the following one:
[[File:avrdude-gui.png|400px]] 
:7. click <code>OK</code>; select <code>ATmega2560</code> in the <code>AVR type</code>
:8. in the <code>Flash</code> section search the hex file you want to upload on the robot; select <code>Intel Hex</code> on the right
:9. connect the robot to the computer, turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section
:10. during the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Command line====
The [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility is used to do the upload, you can download it directly from the following links depending on your system:
* [https://projects.gctronic.com/elisa3/programming/WinAVR-20100110-install.exe Windows (tested on Windows 7 and 10)]; <code>avrdude</code> will be installed in the path <code>C:\WinAVR-20100110\bin\avrdude</code>; avrdude version 5.10
* [https://projects.gctronic.com/elisa3/programming/CrossPack-AVR-20131216.dmg Mac OS X]; <code>avrdude</code> will be installed in the path <code>/usr/local/CrossPack-AVR/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 6.0.1
* Ubuntu (12.04 32-bit): issue the command <code>sudo apt-get install avrdude</code> in the terminal; <code>avrdude</code> will be installed in the path <code>/usr/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 5.11.1

Open a terminal and issue the following commands:
# only for windows users: <code>c:\windows\system32\mode.com com10: dtr=on</code>. You should see the robot blink (blue), if this is not the case try again the command.
# <code>avrdude -p m2560 -P COM10 -b 57600 -c stk500v2 -D -Uflash:w:Elisa3-avr-studio.hex:i -v</code> 
where <code>COM10</code> must be replaced with your com port and <code>Elisa3-avr-studio.hex</code> must be replaced with your application name; in Mac OS X the port will be something like <code>/dev/tty.usbserial-...</code>, in Ubuntu will be <code>/dev/ttyUSB0</code>. 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Basic_demo Basic demo] and [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo Advanced demo] have this command contained in the file <code>program.bat</code> in the <code>default</code> directory within the project, this can be useful for Windows users. 

===Internal EEPROM===
The internal 4 KB EEPROM that resides in the microcontroller is pre-programmed with the robot ID in the last two bytes (e.g. if ID=3200 (0x0C80), then address 4094=0x80 and address 4095=0x0C). The ID represents also the RF address that the robot uses to communicate with the computer and is automatically read at startup (have a look a the firmware for more details). 
Moreover the address 4093 is used to save the clock calibration value that is found during production/testing of the robots; this value hasn't to be modified otherwise some functionalities such as tv remote control could not work anymore. For more information on clock calibration refers to the applicaiton note [https://projects.gctronic.com/elisa3/AVR053-Calibration-RC-oscillator.pdf AVR053: Calibration of the internal RC oscillator]. 
The Elisa-3 robot supports an autonomous calibration process and the result of this calibration is saved in EEPROM starting at address 3946 to 4092. 
'''The size of usable EEPROM is thus 3946 bytes (0-3945) and the remaining memory must not be modified/erased.'''

In order to program the eeprom an AVR programmer is required, we utilize the Pocket AVR Programmer from Sparkfun (recognized as USBtiny device); then with the [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility the following command has to be issued:
<pre>
avrdude -p m2560 -c usbtiny -v -U eeprom:w:Elisa3-eeprom.hex:i -v -B 1
</pre>
where ''Elisa3-eeprom.hex'' is the EEPROM memory saved as Intel Hex format ([https://projects.gctronic.com/elisa3/Elisa3-eeprom.hex eeprom example]); a possible tool to read and write Intel Hex format is [https://projects.gctronic.com/elisa3/G32setup_12004-intel-hex-editor.exe Galep32 from Conitec Datensysteme]. 
Alternatively a program designed to writing to these EEPROM locations can be uploaded to the robot, in case an AVR programmer isn't available. The project source is available in the repository [https://github.com/gctronic/elisa3_eeprom.git https://github.com/gctronic/elisa3_eeprom.git]; it is simply needed to modify the address, rebuild and upload to the robot. 
Another option is to use the following Python script [https://projects.gctronic.com/elisa3/write_radio_address.py write_radio_address.py], the procedure would be:
# program the robot with the factory firmware
# put selector in position 6
# connect the robot to the computer via USB cable
# set the correct serial port and address in the script
# run the script
After a power-cycle the new address can be used.

===Bootloader===
In case the bootloader of the Elisa-3 is erased by mistake, then you can restore it by using an AVR programmer. You can download the bootloader from here [https://projects.gctronic.com/elisa3/stk500v2_20.03.18_13b46ce.hex stk500v2.hex]; the source code is available from the repository [https://github.com/gctronic/elisa3_bootloader.git https://github.com/gctronic/elisa3_bootloader.git]. 
<code>Avrdude</code> can be used to actually write the bootloader to the robot with a command similar to the following one: 
<code>avrdude -p m2560 -c stk500v2 -P COM348 -v -U lfuse:w:0xE2:m -U hfuse:w:0xD8:m -U efuse:w:0xFF:m -V -U flash:w:stk500v2.hex:i -v -B 2</code> 
Here we used a programmer recognized as a serial device (port COM348) that utilizes the <code>stk500v2</code> protocol.

==Base-station==
This chapter explains informations that aren't needed for most of the users since the radio module is ready to be used and don't need to be reprogrammed. Only if you are interested in the firmware running in the radio module and on how to reprogram it then refer to section [https://www.gctronic.com/doc/index.php/Elisa#Base-station https://www.gctronic.com/doc/index.php/Elisa#Base-station] (chapter 4.2) of the Elisa robot wiki.

==PC side==
This section gives informations related to the radio module connected to the computer; if you don't have a radio module you can skip this section.
===Requirements===
Refer to the section [https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver].

===Elisa-3 library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. Some basic examples will be provided in the following sections to show how to use this library. 
The source code of the library is available in the repository [https://github.com/gctronic/elisa3_remote_library https://github.com/gctronic/elisa3_remote_library]; follow the instructions in the repository to build the library.

===Multiplatform monitor===
The demo is a command line monitor that shows all the sensors information (e.g. proximity, ground, acceleromter, battery, ...) and let the user move the robot and change its colors and behavior with the keyboard. The data are sent using the protocol described in the previous section. 
The following figures show the monitor on the left and the available commands on the right. 
[[File:Cmd-line-monitor.jpg|400px]] [[File:Pc-side-commands2.jpg|400px]] 

The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_monitor https://github.com/gctronic/elisa3_remote_monitor]. 

====Windows====
Execution:
* install the driver contained in the [https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio nRFgo Studio tool] if not already done; this let the base-station be recognized as a WinUSB device (bootloader), independently of whether the libusb library is installed or not
* once the driver is installed, the pre-compiled "exe" (under <code>\bin\Release</code> dir) should run without problems; the program will prompt you the address of the robot you want to control

Compilation: 
the Code::Blocks project should already be setup to reference the Elisa-3 library headers and lib files, anyway you need to put this project within the same directory of the Elisa-3 library, e.g. you should have a tree similar to the following one:
* Elisa-3 demo (parent dir)
** <code>elisa3_remote_library</code> (Elisa-3 library project)
** <code>elisa3_remote_monitor</code> (current project)

====Linux / Mac OS X====
The project was tested to work also in Ubuntu and Mac OS X (no driver required). 
Compilation:
* you need to put this project within the same directory of the Elisa-3 library
* build command: go under "linux" dir and type <code>make clean && make</code>
Execution:
* <code>sudo ./main</code>

===Communicate with 4 robots simultaneously===
This example shows how to interact with 4 robots simlutaneously, basically it shows the sensors information (proximity and ground) coming from 4 robots and let control one robot at a time through the keyboard (you can change the robot you want to control). The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_multiple https://github.com/gctronic/elisa3_remote_multiple]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

===Obstacle avoidance===
This demo implements the ''obstacle avoidance'' behavior controlling the robot from the pc through the radio; this means that the robot reacts only to the commands received using the basic communication protocol and has no "intelligence" onboard. The demo uses the information gathered from the 3 front proximity sensors and set the motors speed accordingly; moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|F_b1TQxZKos}}

It is available also the same example but with 4 robots controlled simultaneously; the source can be downloaded from the branch <code>4robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa] 
It is easy to extend the previous example in order to control many robots, the code that controls 8 robots simultaneously can be downloaded from the branch <code>8robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa].

===Cliff avoidance===
This demo implements the ''cliff avoidance'' behavior controlling the robot from the pc through the radio; as with the ''obstacle avoidance'' demo, the robot reacts only to the commands received from the radio. The demo uses the information gathered from the 4 ground sensors to stop the robot when a cliff is detected (threshold tuned to run in a white surface); moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_cliff https://github.com/gctronic/elisa3_remote_cliff]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|uHy-9XXAHcs}}
===Communication between robots via PC===
This examples shows how to emulate direct communication between robots: basically a common state is shared between the robots and this state is changed based on the current state of each robot; it emulates the facts that each robot propagates its state to all other robots. Actually all the robots communicate only with the computer (only one computer with only one radio module) and the computer forward the information to all the others robots; the radio is fast enough so that the computer in the middle will not slow down the communication. A big advantage passing from the computer is that you can log the communication messages on the computer and see what is happening. 
In particular in this demo a total of 4 robots are handled and when a robot crosses a black line, then it inform all others robots to change their color. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_communication_between_robots_via_pc https://github.com/gctronic/elisa3_communication_between_robots_via_pc]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|4tpxoAyWfEA}}

===Set robots state from file===
This project show how to send data to robots for which we will know the address only at runtime, in particular the content of the packets to be transmitted is parsed from a csv file and the interpreted commands are sent to the robots one time. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_file https://github.com/gctronic/elisa3_remote_file]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 

===Elisa-3 Python library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. 
The source code of the library and some usage examples are available in the repository [https://github.com/gctronic/elisa3_remote_library_python https://github.com/gctronic/elisa3_remote_library_python]. 

=Odometry=
The odometry of Elisa-3 is quite good even if the speed is only measured by back-emf. On vertical surfaces the absolute angle is given by the accelerometer measuring g... quite a fix reference without drifting ;-) 
A fine calibration of the right and left wheel speed parameters might give better results.
However the current odometry is a good estimate of the absolute position from a starting point.
The experiments are performed on a square labyrinth and the robot advances doing obstacle avoidance. The on-board calculated (x,y,theta) position is sent to a PC via radio and logged for further display. 
[[File:odometry-vertical.jpg|400px]] 
Details about the code can be found in the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced-demo] project, in particular the ''motors.c'' source file. The PC application used for logging data is the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor].
==Autonomous calibration==
Since the motors can be slightly different a calibration can improve the behavior of the robot in terms of maneuverability and odometry accuracy.
An autonomous calibration process is implemented onboard: basically a calibration is performed for both the right and left wheels in two modes that are forward and backward with speed control enabled. In order to let the robot calibrate istelf a white sheet in which a black line is drawed is needed; the robot will measure the time between detection of the line at various speeds. The calibration sheet can be downloaded from the following link [https://projects.gctronic.com/elisa3/calibration-sheet.pdf calibration-sheet.pdf]. 
In order to accomplish the calibration the robot need to be programmed with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmare] and a specific command has to be sent to the robot through the radio module or the TV remote; if you are using the radio module you can use the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor application] in which the letter ''l (el)'' is reserved to launch the calibration, otherwise if you have a TV remote control you can press the button ''5''.
The sequence is the following: 
1. put the selector in position 8 
2. place the robot near the black line as shown below; the left motor is the first to be calibrated. Pay attention to place the right wheel as precise as possible with the black line 
[[File:elisa3-calibration-1.jpg|300px]] [[File:elisa3-calibration-2.jpg|300px]] 
3. once the robot is placed you can type the ''l (el)'' command (or press the button ''5''); wait a couple of minutes during which the robot will do various turns at various speed in the forward direction and then in the backward direction 
4. when the robot terminated (robot is stopped after going backward at high speed) you need to place it in the opposite direction in order to calibrate the right motor, as shown below. 
[[File:elisa3-calibration-3.jpg|300px]] 
5. once the robot is placed you can type again the ''l (el)'' command (or press the button ''5'') 
6. when the robot finish, the calibration process is also terminated. 

The previous figures show a robot without the top diffuser, anyway you don't need to remove it!

=Tracking=
==Assembly documentation==
You can download the documentation from here [https://projects.gctronic.com/elisa3/tracking-doc.pdf tracking-doc.pdf]. 
Have a look also at the video: 
{{#ev:youtube|92pz28hnteY}} 

==SwisTrack==
Some experiments are done with the [https://en.wikibooks.org/wiki/SwisTrack SwisTrack software] in order to be able to track the Elisa-3 robots through the back IR emitter, here is a resulting image with 2 robots: 
[[File:elisa-3-tracking-2robots.jpg|300px]] 
The pre-compiled SwisTrack software (Windows) can be downloaded from the following link [https://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip SwisTrack-compiled]. 


The following video shows the tracking of 5 robots: 
{{#ev:youtube|33lrIUux_0Q}} 
The SwisTrack software lets you easily log also the resulting data that you can then elaborate, here is an example taken from the experiment using 5 robots: 
[[File:swistrack-output.jpg|300px]] 

The following video shows the test done with 20, 30 and 38 Elisa-3 robots, the tracking is still good; it's important to notice that we stopped to 38 Elisa-3 robots because are the ones we have in our lab. 
{{#ev:youtube|5LAccIJ9Prs}} 

==Position control==
We developed a simple position control example that interacts with Swistrack through a TCP connection and control 4 robots simultaneously; the orientation of the robots is estimated only with the Swistrack information (delta position), future improvements will integrate odometry information. The following video shows the control of 4 robots that are driven in a ''8-shape''. 
{{#ev:youtube|ACaGNEQHayc}} 
[[File:tracking-8shape.jpg|300px]] 
All the following projects require the [https://www.gctronic.com/doc/index.php/Elisa-3#Elisa-3_library Elisa-3 library], for building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

* Horizontal position control (4 robots): the source code can be downloaded from [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-4-robots-rev245-15.01.21.zip position-control-pattern-horizontal-4-robots.zip] (Code::Blocks project). 
One of the characteristics of the Elisa-3 robot is that it can move in vertical thanks to its magnetic wheels, thus we developed also a vertical position control that use accelerometer data coming from the robot to get the orientation of the robot (more precise) instead of estimating it with the Swistrack information, you can download the source code from the following link:
* Vertical position control (4 robots): [https://projects.gctronic.com/elisa3/position-control-pattern-vertical-4-robots-rev245-15.01.21.zip position-control-pattern-vertical-4-robots.zip] (Code::Blocks project). 
We developed also an example of position control that control a single robot (code adapted from previous example) that can be useful during the initial environment installation/testing; you can download the source code from the following link:
* Horizontal position control (1 robot): [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-1-robot-rev245-15.01.21.zip position-control-pattern-horizontal-1-robot.zip] (Code::Blocks project). 
Another good example to start playing with the tracking is an application that lets you specify interactively the target point that the robot should reach; you can download the source code of this application from the following link:
* Go to target point: [https://projects.gctronic.com/elisa3/position-control-goto-pos-horizontal-1-robot-rev245-15.01.21.zip position-control-goto-pos-horizontal-1-robot.zip] (Code::Blocks project). 

==Utilities==
In order to adjust the IR camera position it is useful to have an application that turn on the back IR of the robots. The following application [https://projects.gctronic.com/elisa3/back-IR-on-4-robots-rev245-15.01.21.zip back-IR-on-4-robots-rev245-15.01.21.zip] is an example that turn on the back IR of 4 robots, their addresses are asked to the user at the execution.

=Local communication=
{{#ev:youtube|7bxIR0Z3q3M}} 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] is needed in order to use the local communication. You can find some examples on how to use this module in the main, refers to demos in selector position from 11 to 14. 
Here are some details about the current implementation of the communication module:
* use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; in the worst case (continuous receive and transmit) the sensor update frequency is about 3 Hz
* bidirectional communication
* id and angle of the proximity sensor that received the data are available
* the throughput is about 1 bytes/sec
* maximum communication distance is about 5 cm
* no reception/transmission queue (only one byte at a time)
* the data are sent using all the sensors, cannot select a single sensor from which to send the data. The data isn't sent contemporaneously from all the sensors, but the sensors used are divided in two groups of 4 alternating sensors (to reduce consumption)
== Clustering example==
In this demo there are 37 elisa-3 robots programmed with a special firmware that you can download here [https://projects.gctronic.com/elisa3/elisa3_cluster_firmware.hex elisa3_cluster_firmware.hex]; the source code is available in the repo [https://github.com/gctronic/elisa3_cluster_firmware https://github.com/gctronic/elisa3_cluster_firmware]. 
The robots will try to form some clusters by exchanging data through the local communication and at the same time exchange data with a central computer: they send their status (in cluster or not) and receive a new color when in cluster.
The application running on the computer side is available in the repo [https://github.com/gctronic/elisa3_cluster_pc https://github.com/gctronic/elisa3_cluster_pc]. 
Here is a video of the demo: 
{{#ev:youtube|MOuSfr1_3lg}}

=ROS=
This chapter explains how to use ROS with the elisa-3 robots; the radio module is needed here. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. The ROS node is implemented in cpp. Here is a general schema: 
[[File:elisa-ros-schema.png|450px]]
''Click to enlarge'' 

First of all you need to install and configure ROS, refer to [https://wiki.ros.org/Distributions https://wiki.ros.org/Distributions] for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Virtual_machine virtual machine]; this is the preferred way.
:* This tutorial is based on ROS Hydro. The same instructions are working with ROS Noetic, beware to use <code>noetic</code> instead of <code>hydro</code> when installing the packages.
:* If you downloaded the pre-installed VM you can go directly to section [https://www.gctronic.com/doc/index.php/Elisa-3#Running_the_ROS_node Running the ROS node].

The ROS elisa-3 node based on roscpp can be found in the following repository [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp]. 

==Initial configuration==
The following steps need to be done only once after installing ROS:
:1. If not already done, create a catkin workspace, refer to [https://wiki.ros.org/catkin/Tutorials/create_a_workspace https://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands:
<pre> mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws/
catkin_make
source devel/setup.bash </pre>
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
:3. Clone the elisa-3 ROS node repo from [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] inside the catkin workspace source folder (<tt>~/catkin_ws/src</tt>): <code>git clone https://github.com/gctronic/elisa3_node_cpp.git</code>
:4. Install the dependencies:
:ROS:
::* <code>sudo apt-get install ros-hydro-slam-gmapping</code>
::* <code>sudo apt-get install ros-hydro-imu-tools</code>
::If you are using a newer version of ROS, replace <code>hydro</code> with your distribution name.
:cpp:
::* install OpenCV: <code>sudo apt-get install libopencv-dev</code>
::If you are working with OpenCV 4, then you need to change the header include from <code>#include <opencv/cv.h></code> to <code>#include <opencv2/opencv.hpp></code>
:5. Rebuild the <code>elisa-3 library</code>: go to <code>~/catkin_ws/src/elisa3_node_cpp/src/pc-side-elisa3-library/linux</code>, then issue <code>make clean</code> and <code>make</code>
:6. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
:7. The USB radio module by default requires root priviliges to be accessed; to let the current user have access to the radio we use <tt>udev rules</tt>:

:* in the udev rules file you can find in <tt>/etc/udev/rules.d/name.rules</tt> add the following string changing the <tt>GROUP</tt> field with your current user group:
::<tt>SUBSYSTEMS=="usb", ATTRS{product}=="nRF24LU1P-F32 BOOT LDR", GROUP="viki"</tt>
:: To know which groups your user belongs to issue the command <tt>id</tt>
:* disconnect and reconnect the radio module
:8. Program the elisa-3 robot with the last [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] (>= rev.221) and put the selector in position 15

==Running the ROS node==
First of all get the last version of the elisa-3 ROS node from github:
* clone the repo [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] and copy the <tt>elisa3_node_cpp</tt> directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src)
* build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws). 

Now you can start the ROS node, for this purposes there is a launch script (based on [https://wiki.ros.org/roslaunch roslaunch]), as explained in the following section. Before starting the ROS node you need to start <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.

===Single robot===
Open a terminal and issue the following command: <code>roslaunch elisa3_node_cpp elisa3_single.launch elisa3_address:='1234'</code> where <tt>1234</tt> is the robot id (number on the bottom).

If all is going well [https://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the elisa ROS node as shown in the following figure: 
[[File:elisa-ros-single-robot.png|300px]]
''Click to enlarge'' 

The launch script is configured also to run the [https://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: 
{{#ev:youtube|v=k_9nmEO2zqE}}

==Move the robot==
You have two options to move the robot. 

The first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right. 
[[File:elisa-teleop.png|300px]]
''Click to enlarge'' 

The second method is by directly publishing on the <code>/mobile_base/cmd_vel</code> topic, for instance by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'</code> the robot will rotate on the spot, instead by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code> the robot will move straight forward. 
Beware that there shouldn't be any other node publishing on the <code>/mobile_base/cmd_vel</code> topic (e.g. Rviz), otherwise your commands will be overwritten.

==Troubleshooting==
===Robot state publisher===
If you get an error similar to the following when you start a node with roslaunch:
<pre>
ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)
</pre>
Then you need to change the launch file from:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="state_publisher" />
</pre>
To:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
</pre>
This is due to the fact that <code>state_publisher</code> was a deprecated alias for the node named <code>robot_state_publisher</code> (see [https://github.com/ros/robot_state_publisher/pull/87 https://github.com/ros/robot_state_publisher/pull/87]).

==Virtual machine==
To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and elisa. You can download the image as ''open virtualization format'' from the following link [https://projects.gctronic.com/VM/ROS-Hydro-12.04.ova ROS-Hydro-12.04.ova] (based on the VM from https://nootrix.com/2014/04/virtualized-ros-hydro/); you can then use [https://www.virtualbox.org/ VirtualBox] to import the file and automatically create the virtual machine. Some details about the system:
* user: gctronic, pw: gctronic
* Ubuntu 12.04.4 LTS (32 bits)
* ROS Hydro installed
* [https://www.cyberbotics.com/ Webots] 8.0.5 is installed (last version available for 32 bits linux)
* [https://git-cola.github.io/ git-cola] (git interface) is installed
* the <tt>catkin workspace</tt> is placed in the desktop

=Videos=
==Autonomous charge==
The following videos show 3 Elisa-3 robots moving around in the environment avoiding obstacles thanks to their proximity sensors and then going to the charging station autonomously; some black tape is placed in the charging positions to help the robots place themselves thanks to their ground sensors. The movement and charging is indipendent of the gravity. It works also vertically and up-side-down.
{{#ev:youtube|o--FM8zIrRk}}{{#ev:youtube|Ib9WdbwMlyQ}}{{#ev:youtube|xsOdxwOjmuI}}{{#ev:youtube|tprO126R9iA}}{{#ev:youtube|HVYp1Eujof8}}{{#ev:youtube|mtJd8jTWT94}}
==Remote control==
The following video shows 38 Elisa-3 robots moving around with onboard obstacle avoidance enabled; 15 of them are running autonmously, the remaining 23 are controlled from one computer with the radio module. 
{{#ev:youtube|WDxfIFhpm1g}}

Elisa-3

2026-04-22T13:47:47Z

WikiSysop:

[[Category:elisa3]]
[[Category:all]]
=Overview=
[[File:Elisa3_and_charger.JPG|350px]] 
Elisa-3 is an evolution of the [https://www.gctronic.com/doc/index.php/Elisa Elisa] robot based on a different microcontroller and including a comprehensive set of sensors:
* [https://projects.gctronic.com/elisa3/atmega640-1280-1281-2560-2561_datasheet.pdf Atmel 2560] microcontroller (Arduino compatible)
* central RGB led
* 8 green leds around the robot
* IRs emitters
* 8 IR proximity sensors ([https://projects.gctronic.com/elisa3/tcrt1000.pdf Vishay Semiconductors Reflective Optical Sensor])
* 4 ground sensors ([https://projects.gctronic.com/elisa3/QRE1113-D.PDF Fairchild Semiconductor Minature Reflective Object Sensor])
* 3-axis accelerometer ([https://projects.gctronic.com/elisa3/MMA7455L.pdf Freescale MMA7455L])
* RF radio for communication ([https://www.nordicsemi.com/kor/Products/2.4GHz-RF/nRF24L01P Nordic Semiconductor nRF24L01+])
* micro USB connector for programming, debugging and charging
* IR receiver
* 2 DC motors
* top light diffuser
* selector
The robot is able to self charge using the charger station, as shown in the previous figure. The following figure illustrates the position of the various sensors: 
[[File:Elisa3-mainComp-digital-white.png|400px]] 

==Useful information==
* the top light diffuser and robot are designed to lock together, but the diffuser isn't fixed and can thus be removed as desired; the top light diffuser, as the name suggests, helps the light coming from the RGB led to be smoothly spread out, moreover the strip attached around the diffuser let the robot be better detected from others robots. Once the top light diffuser is removed, pay attention not to look at the RGB led directly. In order to remove the top light diffuser simply pull up it, then to place it back on top of the robot remember to align the 3 holes in the diffuser with the 3 IRs emitters and push down carefully untill the diffuser is stable; pay attention to not apply too much force on the IRs emitters otherwise they can bend and stop working.
[[File:Diffuser-pull-up.jpg|200px]] [[File:Diffuser-push-down.jpg|200px]] 
* when the top light diffuser is fit on top of the robot, then in order to change the selector position you can use the tweezers; the selector is located near the front-left IR emitter, as shown in the following figure:
[[File:selector-tweezers.jpg|200px]] 
* if you encounter problems with the radio communication (e.g. lot of packet loss) then you can try moving the antenna that is a wire near the robot label. Place the antenna as high as possible, near the plastic top light diffuser; try placing it in the borders in order to avoid seeing a black line on the top light diffuser when the RGB led is turned on.
[[File:Antenna-position.jpg|200px]] [[File:Antenna-diffuser.jpg|200px]] 

==Robot charging==
The Elisa-3 can be piloted in the charger station in order to be automatically self charged; there is no need to unplug the battery for charing. The following figures shows the robot approaching the charger station; a led indicates that the robot is in charge:
 
[[File:Elisa3-charger-out.jpg|300px]] [[File:Elisa3-charger-in.jpg|350px]] 

The microcontroller is informed when the robot is in charge and this information is also transferred to the PC in the ''flags'' byte; this let the user be able to pilote the robot to the charger station and be informed when it is actually in charge. More information about the radio protocol can be found in the section [https://www.gctronic.com/doc/index.php/Elisa-3#Communication Communication].

Moreover the robot is also charged when the micro USB cable is connected to a computer; pay attention that if the USB cable is connected to a hub, this one need to be power supplied.

The following video shows the Elisa-3 piloted through the radio to the charging station using the monitor application: {{#ev:youtube|kjliXlQcgzw}}

==Top light diffuser==
From February 2013 onwards the Elisa-3 is equipped with a new top light diffuser designed to fit perfectly in the 3 IRs emitters of the robot. The diffuser is made of plastic (3d printed), it is more robust and it simplifies the removal and insertion. Here is an image: 
[[File:elisa3-new-case.jpg|350px]] 

=Hardware=
The following figures show the main components offered by the Elisa-3 robot and where they are physically placed: 
[[File:Elisa3.1-hw-schema-top.jpg|550px]] 
[[File:Elisa3-hw-schema-bottom3.jpg|400px]] 

==Power autonomy==
The robot is equipped with two batteries for a duration of about 3 hours at normal usage (motors run continuously, IRs and RGB leds turned on).
[[File:Power-autonomy.jpg|800px]] 

==Detailed specifications==
{| border="1"
|'''Feature'''
|'''Technical information'''
|-
|Size, weight
|50 mm diameter, 30 mm height, 39 g
|-
|Battery, autonomy
|LiIPo rechargeable battery (2 x 130 mAh, 3.7 V). About 3 hours autonomy. Recharging time about 1h e 30.
|-
|Processor
|Atmel ATmega2560 @ 8MHz (~ 8 MIPS); 8 bit microcontroller
|-
|Memory
|RAM: 8 KB; Flash: 256 KB; EEPROM: 4 KB
|-
|Motors
|2 DC motors with a 25:1 reduction gear; speed controlled with backEMF
|-
|Magnetic wheels
|Adesion force of about 1 N (100 g) depending on surface material and painting Wheels diamater = 9 mm Distance between wheels = 40.8 mm
|-
|Speed
|Max: 60 cm/s
|-
|Mechanical structure
|PCB, motors holder, top white plastic to diffuse light
|-
|IR sensors
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm; each sensor is 45° away from each other 4 ground sensors detecting the end of the viable surface (placed on the front-side of the robot)
|-
| IR emitters
| 3 IR emitters (2 on front-side, 1 on back-side of the robot)
|-
|Accelerometer
|3D accelerometer along the X, Y and Z axis
|-
|LEDs
|1 RGB LED in the center of the robot; 8 green LEDs around the robot
|-
|Switch / selector
|16 position rotating switch
|-
|Communication
| Standard Serial Port (up to 38kbps) Wireless: RF 2.4 GHz; the throughput depends on number of robot: eg. 250Hz for 4 robots, 10Hz for 100 robots; up to 10 m
|-
|Remote Control
|Infra-red receiver for standard remote control commands
|-
|Expansion bus
|Optional connectors: 2 x UART, I2C, 2 x PWM, battery, ground, analog and digital voltage
|-
|Programming
|C/C++ programming with the AVR-GCC compiler ([https://winavr.sourceforge.net/ WinAVR] for Windows). Free compiler and IDE (AVR Studio / Arduino)
|}

=Communication=
==Wireless==
The radio base-station is connected to the PC through USB and transfers data to and from the robot wirelessly. In the same way the radio chip ([https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P nRF24L01+]) mounted on the robot communicates through SPI with the microcontroller and transfers data to and from the PC wirelessly. 
The robot is identified by an address that is stored in the last two bytes of the microcontroller internal EEPROM; the robot firmware setup the radio module reading the address from the EEPROM. This address corresponds to the robot id written on the label placed under the robot and should not be changed. 
[[File:Elisa-communication.jpg|400px]] 

===Packet format - PC to radio to robot===
The 13 bytes payload packet format is shown below (the number in the parenthesis expresses the bytes):
{| border="1"
| Command (1)
| Red led (1)
| Blue led (1)
| Green led (1)
| IR + Flags (1)
| Right motor (1)
| Left motor (1)
| Small green leds (1)
| Flags2 (1)
| Reserved (1)
| Remaining 4 bytes are unused
|}

* Command: 0x27 = change robot state; 0x28 = goto base-station bootloader (this byte is not sent to the robot)
* Red, Blue, Green leds: values from 0 (OFF) to 100 (ON max power)
* IR + flags:
** first two bits are dedicated to the IRs:
*** 0x00 => all IRs off
*** 0x01 => back IR on
*** 0x02 => front IRs on
*** 0x03 => all IRs on
** third bit is reserved for enabling/disabling IR remote control (0=>disabled, 1=>enabled)
** fourth bit is used for sleep (1 => go to sleep for 1 minute)
** fifth bit is used to calibrate all sensors (proximity, ground, accelerometer) and reset odometry
** sixth bit is reserved (used by radio station)
** seventh bit is used for enabling/disabling onboard obstacle avoidance
** eight bit is used for enabling/disabling onboard cliff avoidance
* Right, Left motors: speed expressed in 1/5 of mm/s (i.e. a value of 10 means 50 mm/s); MSBit indicate direction: 1=forward, 0=backward; values from 0 to 127
* Small green leds: each bit define whether the corresponding led is turned on (1) or off (0); e.g. if bit0=1 then led0=on
* Flags2:
** bit0 is used for odometry calibration
** remaining bits unused
* Remaining bytes free to be used

====Optimized protocol====
The communication between the pc and the base-station is controlled by the master (computer) that continuously polls the slave (base-station); the polling is done once every millisecond and this is a restriction on the maximum communication throughput. To overcome this limitation we implemented an optimized protocol in which the packet sent to the base-station contains commands for four robots simultaneously; the base-station then separate the data and send them to the correct robot address. The same is applied in reception, that is the base-station is responsible of receiving the ack payloads of 4 robots (64 bytes in total) and send them to the computer. This procedure let us have a throughput 4 times faster.


===Packet format - robot to radio to PC===
The robot send back to the base-station information about all its sensors every time it receive a command; this is accomplished by using the "ack payload" feature of the radio module. Each "ack payload" is 16 bytes length and is marked with an ID that is used to know which information the robot is currently transferring. The sequence is the following (the number in the parenthesis expresses the bytes):
{| border="1"
|ID=3 (1)
|Prox0 (2)
|Prox1 (2)
|Prox2 (2)
|Prox3 (2)
|Prox5 (2)
|Prox6 (2)
|Prox7 (2)
|Flags (1)
|-
|||||||||||||||||
|-
|ID=4 (1)
|Prox4 (2)
|Ground0 (2)
|Ground1 (2)
|Ground2 (2)
|Ground3 (2)
|AccX (2)
|AccY (2)
|TV remote (1)
|-
|||||||||||||||||
|-
|ID=5 (1)
|ProxAmbient0 (2)
|ProxAmbient1 (2)
|ProxAmbient2 (2)
|ProxAmbient3 (2)
|ProxAmbient5 (2)
|ProxAmbient6 (2)
|ProxAmbient7 (2)
|Selector (1)
|-
|||||||||||||||||
|-
|ID=6 (1)
|ProxAmbient4 (2)
|GroundAmbient0 (2)
|GroundAmbient1 (2)
|GroundAmbient2 (2)
|GroundAmbient3 (2)
|AccZ (2)
|Battery (2)
|Free (1)
|-
|||||||||||||||||
|-
|ID=7 (1)
|LeftSteps (4)
|RightSteps (4)
|theta (2)
|xpos (2)
|ypos (2)
|Free (1)
|
|
|}

Pay attention that the base-station could return "error" codes in the first byte if the communication has problems:
* 0 => transmission succeed (no ack received though)
* 1 => ack received (should not be returned because if the ack is received, then the payload is read)
* 2 => transfer failed

Packet ID 3:
* Prox* contain values from 0 to 1023, the greater the values the nearer the objects to the sensor
* The ''Flags'' byte contains these information:
** bit0: 0 = robot not in charge; 1 = robot in charge
** bit1: 0 = button pressed; 1 = button not pressed
** bit2: 0 = robot not charged completely; 1 = robot charged completely
** the remainig bits are not used at the moment

Packet ID 4:
* Prox4 contains values from 0 to 1023, the greater the values the nearer the objects to the sensor
* Ground* contain values from 512 to 1023, the smaller the value the darker the surface
* AccX and AccY contain raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* TV remote contains the last interpreted command received through IR

Packet ID 5:
* ProxAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* Selector contains the value of the current selector position

Packet ID 6:
* ProxAmbient4 contains values from 0 to 1023, the smaller the values the brighter the ambient light
* GroundAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light
* AccZ contains raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g
* Battery contains the sampled value of the battery, the values range is between 780 (battery discharged) and 930 (battery charged)

Packet ID 7:
* LeftSteps and RightSteps contain the sum of the sampled speed for left and right motors respectively (only available when the speed controller isn't used; refer to xpos, ypos and theta when the speed controller is used)
* theta contains the orientation of the robot expressed in 1/10 of degree (3600 degrees for a full turn); available only when the speed controller is enabled
* xpos and ypos contain the position of the robot expressed in millimeters; available only when the speed controller is enabled

==USB cable==
You can directly connect the robot to the computer to make a basic functional test. You can find the source code in the following link [https://projects.gctronic.com/elisa3/Elisa3-global-test.zip Elisa3-global-test.zip] (Windows). 
To start the test follow these steps:
# put the selector in position 6
# connect the robot to the computer with the USB cable and turn it on
# run the program, insert the correct COM port and choose option 1
With the same program you can also change the ID of the robot by choosing option 2 in the last step (not recommended).

Via USB cable you can also program the robot with [https://www.gctronic.com/doc/index.php?title=Elisa-3#Aseba Aseba].

=Software=

==Robot==
===Requirements===
In order to communicate with the robot through the micro USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise you need to download the drivers for your system and architecture:
* [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.10.00%20WHQL%20Certified.exe Windows Vista/XP], [https://www.ftdichip.com/Drivers/CDM/CDM%20v2.12.10%20WHQL%20Certified.exe Windows 7/8/10 (run as administrator)]
* Ubuntu: when the robot is connected the port will be created in <code>/dev/ttyUSB0</code> (no need to install a driver)
* [https://www.ftdichip.com/drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (32 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg Mac OS X 10.3 to 10.8 (64 bit)], [https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_3.dmg Mac OS X 10.9 and above]; after installing the driver the port will be created in <code>/dev/tty.usbserial-...</code>; you can find a guide on how to install the driver in the following link [https://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf]
All the drivers can be found in the official page from the following link [https://www.ftdichip.com/Drivers/VCP.htm FTDI drivers]. 
Starting from robot ID 3823 the USB to serial chip can be one of the following: FTDI, [https://projects.gctronic.com/elisa3/CypressDriverInstaller_1.exe Cypress CY7C65213] or Silicon Labs CP2102 ([https://projects.gctronic.com/elisa3/CP210x_Universal_Windows_Driver.zip Windows 10 or later], [https://projects.gctronic.com/elisa3/CP210x_Windows_Drivers.zip Windows 7]); this is due to chips availability.

===AVR Studio 4 project===
The projects are built with [https://projects.gctronic.com/elisa3/AvrStudio4Setup.exe AVR Studio 4] released by Atmel. 
The projects should be compatible also with newer versions of Atmel Studio (last version known as Microchip Studio), the last version is available from [https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive https://www.microchip.com/mplab/avr-support/avr-and-sam-downloads-archive]. 

====Basic demo====
This project is thought to be a starting point for Elisa-3 newbie users and basically contains a small and clean main with some basic demos selected through the hardware selector that show how to interact with robot sensors and actuators.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_basic https://github.com/gctronic/elisa3_firmware_basic]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-basic_ffb3947_21.03.18.hex Elisa-3 basic firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors

====Advanced demo====
This is an extension of the ''basic demo project'', basically it contains some additional advanced demos.
The project source can be downloaded from the repository [https://github.com/gctronic/elisa3_firmware_advanced.git https://github.com/gctronic/elisa3_firmware_advanced.git]; the hex file can be directly downloaded from [https://projects.gctronic.com/elisa3/elisa3-firmware-advanced_96c355a_13.03.18.hex Elisa-3 advanced firmware hex]. To program the robot refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Programming Programming]. 
Selector position and related demo:
* 0: no speed controller activated => free running (all others positions have the speed controller activated)
* 1: obstacle avoidance enabled
* 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands)
* 3: both obstacle and cliff avoidance enabled
* 4: random RGB colors and small green leds on
* 5: robot moving forward with obstacle avoidance enabled and random RGB colors
* 6: robot testing and address writing through serial connection (used in production)
* 7: automatic charging demo (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Videos Videos]), that is composed of 4 states:
** random walk with obstacle avoidance
** search black line
** follow black line that lead to the charging station
** charge for a while
* 8: autonomous odometry calibration (refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Autonomous_calibration Autonomous calibration])
* 9: write default odometry calibration values in EEPROM (hard-coded values); wait 2 seconds before start writing the calibration values
* 10: robot moving forward (with pause) and obstacle avoidance enabled; random RGB colors and green led effect
* 11: local communication: robot alignment
* 12: local communication: 2 or more robots exchange data sequentially
* 13: local communication: listen and transmit continuously; when data received change RGB color
* 14: local communication: RGB color propagation
* 15: clock calibration (communicate with the PC through the USB cable to change the OSCCAL register); this position could also be used to remote contol the robot through the radio (only speed control is enabled)

====Atmel Studio 7 / Microchip Studio====
If you are working with Atmel Studio 7 / Microchip Studio, you can simply use the provided AVR Studio 4 projects by importing them directly in Atmel Studio 7 / Microchip Studio: <code>File => Import => AVR Studio 4 Project</code>, then select <code>Elisa3-avr-studio.aps</code> and click on <code>Convert</code>.

If you are asked to update some components (see following figure), then agree: 
[[File:atmel-studio-convert.png|400px]] 

Then click on <code>Build => Clean solution</code> and then <code>Build => Build solution</code>.

If you experience problems during the building, make sure you have the correct toolchain installed: you can download WinAVR toolchain from [https://projects.gctronic.com/elisa3/WinAVR-20100110-install.exe WinAVR-20100110-install.exe]. 
Close and open again Atmel/Microchip Studio and verify that the new toolchain is recognized and that the path is correct: <code>Tools => Options</code> and on the left panel select <code>Toolchain => Package Configuration</code>. Select on top <code>Atmel AVR 8-bit (C language)</code>, then <code>WinAVR</code> flavour and verify the path corresponds to the WinAVR installation path. The following figure shows the toolchain configuration: 
[[File:elisa3-atmelstudio1.png|400px]] 

Finally verify the project is using the WinAVR toolchain: <code>right click on the project name => Properties</code>, on the left panel select <code>Advanced</code> and verify that <code>Toolchain Flavour</code> is set to WinAVR. Press <code>CTRL+S</code> to save your project configuration changes. The following figures show the project configuration: 
[[File:elisa3-atmelstudio2.png|200px]] [[File:elisa3-atmelstudio3.png|400px]] 

===Arduino IDE project===
The project is built with the Arduino IDE 1.x freely available from the [https://arduino.cc/ official Arduino website]. In order to build the Elisa-3 firmware with the Arduino IDE 1.x the following steps has to be performed: 
*1. download the [https://arduino.cc/hu/Main/Software Arduino IDE 1.x] (the last known working version is 1.8.9, refer to [https://www.arduino.cc/en/Main/OldSoftwareReleases#previous Arduino Software]) and extract it, let say in a folder named <code>arduino-1.x</code> 
*2. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_library_03.02.25_65964ed.zip Elisa-3 Arduino library] and extract it within the libraries folder of the Arduino IDE, in this case <code>arduino-1.x\libraries</code> (see [https://support.arduino.cc/hc/en-us/articles/4415103213714-Find-sketches-libraries-board-cores-and-other-files-on-your-computer Find-sketches-libraries-board-cores-and-other-files-on-your-computer] for more information on Arduino useful paths); you should end up with a <code>Elisa3</code> folder within the libraries. If you start the Arduino IDE now you can see that the <code>Elisa-3</code> library is available in the menu <code>Sketch=>Import Library...</code> (or <code>Sketch=>Include Lirary</code> in later IDE versions). In later versions of Arduino IDE you can also install the library via menu: <code>Sketch=>Include Library=>Add .ZIP library</code>, for more info have a look at [https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#importing-a-zip-library importing-a-zip-library].
*3. the file <code>boards.txt</code> in the Arduino IDE folder <code>arduino-1.x\hardware\arduino</code> (or <code>arduino-1.x\hardware\arduino\avr</code> or <code>Users\{username}\AppData\Local\Arduino15\packages\arduino\hardware\avr\1.8.6</code> in later IDE versions) need to be changed to contain the definitions for the Elisa-3 robot, add the following definitions at the end of the file:
<pre>
##############################################################

elisa3.name=Elisa 3 robot

elisa3.upload.tool=avrdude
elisa3.upload.tool.serial=avrdude
elisa3.upload.protocol=stk500v2
elisa3.upload.maximum_size=258048
elisa3.upload.speed=57600

elisa3.bootloader.low_fuses=0xE2
elisa3.bootloader.high_fuses=0xD0
elisa3.bootloader.extended_fuses=0xFF
elisa3.bootloader.path=stk500v2-elisa3
elisa3.bootloader.file=stk500v2-elisa3.hex
elisa3.bootloader.unlock_bits=0x3F
elisa3.bootloader.lock_bits=0x0F

elisa3.build.mcu=atmega2560
elisa3.build.f_cpu=8000000L
elisa3.build.board=AVR_ELISA3
elisa3.build.core=arduino
elisa3.build.variant=mega

##############################################################
</pre>
*4. this step need to be performed only with later IDE versions, when you receive a warning like this <code>Bootloader file specified but missing...</code> during compilation. In this case place the bootloader hex file (<code>stk500v2.hex</code>) you can find in the [https://www.gctronic.com/doc/index.php/Elisa-3#Bootloader Bootloader section] in the directory <code>arduino-1.x\Arduino\hardware\arduino\avr\bootloaders\</code> and name it <code>stk500v2-elisa3.hex</code>
*5. download the [https://projects.gctronic.com/elisa3/elisa3_arduino_project_02.03.21_d2c017e.zip Elisa-3 project file] and open it with the Arduino IDE (you should open the file "''elisa3.ino''")
*6. select <code>Elisa-3 robot</code> from the <code>Tools=>Board</code> menu; click on the <code>Verify</code> button to build the project
*7. turn on the robot, attach the micro USB and wait the blinks terminate. 

*8. to upload the resulting hex file, from the Arduino IDE set the port from the <code>Tools=>Serial Port</code> menu consequently; click on the <code>Upload</code> button
: Only for Windows users: before clicking on <code>Upload</code>, open the serial monitor from the Arduino IDE (<code>Tools => Serial Monitor</code> or <code>Ctrl+Shift+M</code>), the robot should then blink again; keep the serial monitor opened.


You can download the Arduino IDE 1.0.5 for Linux (32 bits) containing an updated avr toolchain (4.5.3) and the Elisa3 library from the following link [https://projects.gctronic.com/elisa3/arduino-1.0.5-linux32.zip arduino-1.0.5-linux32.zip]. 
If the <code>Tools->Serial Port</code> menu is grayed out then you need to start the Arduino IDE in a terminal typing <code>sudo path/to/arduino</code>. 

If you want to have access to the compiler options you can download the following project [https://projects.gctronic.com/elisa3/Elisa3-arduino-makefile.zip Elisa3-arduino-makefile.zip] that contains an Arduino IDE project with a Makefile, follow the instructions in the "readme.txt" file in order to build and upload to the robot.

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

===Aseba===
Refer to the page [{{fullurl:Elisa-3 Aseba}} Elisa-3 Aseba].

===Matlab===
[[File:elisa3-matlab.jpg|200px]] 
The [https://www.e-puck.org/index.php?option=com_content&view=article&id=29&Itemid=27 ePic2] Matlab interface was adapted to work with the Elisa-3 robot. The communication is handled with the radio module. Both Matlab 32 bits and 64 bits are supported (tested on Matlab R2010a). Follow these steps to start playing with the interface:
# program the robot with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced demo]
# place the selector in position 15 (to pilot the robot through the interface with no obstacle and no cliff avoidance)
# connect the radio base-station to the computer
# download the ePic2 for Elisa-3 from the repository [https://github.com/gctronic/elisa3_epic.git https://github.com/gctronic/elisa3_epic.git]: either from github site clicking on <code>Code</code>=><code>Download ZIP</code> or by issueing the command <code>git clone https://github.com/gctronic/elisa3_epic.git</code>
# open (double click) the file ''main.m''; once Matlab is ready type ''main+ENTER'' and the GUI should start
# click on the ''+'' sign (top left) and insert the robot address (e.g 3307), then click on ''Connect''

===Webots simulator===
[[File:Elisa-3-webots.png|200px]] 
The following features have been included in the Elisa-3 model for the [https://www.cyberbotics.com/ Webots simulator]:
* proximity sensors
* ground sensors
* accelerometer
* motors
* green leds around the robot
* RGB led
* radio communication

You can donwload the Webots project containig the Elisa-3 model (proto) and a demonstration world in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots.zip Elisa-3-webots.zip].

You can download a Webots project containing a demonstration world illustrating the usage of the radio communication between 10 Elisa-3 robots and a supervisor in the following link [https://projects.gctronic.com/elisa3/Elisa-3-webots-radio.zip Elisa-3-webots-radio.zip]. Here is a video of this demo: 
{{#ev:youtube|IEgCo3XSESU}}

===Onboard behaviors===
The released firmware contains two basic onboard behaviors: obstacle and cliff avoidance. Both can be enabled and disabled from the computer through the radio (seventh bit of flags byte for obstacle avoidance, eight bit of flags byte for cliff avoidance).
The following videos show three robots that have their obstacle avoidance enabled:{{#ev:youtube|EbroxwWG-x4}} {{#ev:youtube|q6IRWRlTQeQ}}

===Programming===
The robot is pre-programmed with a serial bootloader. In order to upload a new program to the robot a micro USB cable is required. The connection with the robot is shown below: 
[[File:Elisa3.1-programming.jpg|400px]] 

If you are working with the Arduino IDE you don't need to follow this procedure, refer instead to section [https://www.gctronic.com/doc/index.php/Elisa-3#Arduino_IDE_project Arduino IDE project].

'''If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again. '''
'''Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.'''

====Windows 7====
# Download the [https://projects.gctronic.com/elisa3/programming/AVR-Burn-O-Mat-Windows7.zip Windows 7 package] and extract it. The package contains also the FTDI driver. Beware that starting from robot id 4000 the USB driver might be different, refer to section [https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements Requirements], so you need to install it manually in case it isn't an FTDI chip.
# Execute the script <code>config.bat</code> and follow the installation; beware that this need to be done only once. The script will ask you to modify the registry, this is fine (used to save application preferences).
# Connect the robot to the computer; the COM port will be created.
# Run the application <code>AVR Burn-O-Mat.exe</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer (e.g. COM10); then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, connect the USB cable to the computer and wait the blinks terminate. Then open a terminal and issue the command <code>c:\windows\system32\mode.com com10: dtr=on</code> (change the port number accordingly to your robot). The robot should blink again, if this is not the case then try again the command.
# From the <code>AVR Burn-O-Mat</code> interface, click on <code>Write</code> in the <code>Flash</code> section. If you get an <code>Access is denied</code> error, then run <code>AVR Burn-O-Mat.exe</code> as administrator.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Mac OS X====
The following procedure is tested in Max OS X 10.10, but should work from Mac OS X 10.9 onwards; in these versions there is built-in support for the FTDI devices.
# Download the [https://projects.gctronic.com/elisa3/programming/AVR8-Burn-O-Mat-MacOsX.zip Mac OS X package] and extract it.
# Execute the script <code>config.sh</code> in the terminal, it will ask you to install the Java Runtime Environment; in case there is a problem executing the script try with <code>chmod +x config.sh</code> and try again. Beware that this need to be done only once.
# Connect the robot to the computer; the serial device will be created (something like <code>/dev/tty.usbserial-AJ03296J</code>).
# Run the application <code>AVR Burn-O-Mat</code>; you need to configure the port to communicate with the robot:
## click on <code>Settings => AVRDUDE</code>
## in the <code>AVRDUDE Options</code>, on <code>Port</code> enter the name of the port just created when the robot was connected to the computer; then click <code>Ok</code>
# In the <code>Flash</code> section search the hex file you want to upload on the robot.
# Turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section.
# During the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Linux====
The following procedure was tested in Ubunut 12.04, but a similar procedure can be followed in newer systems and other Linux versions. 
You can find a nice GUI for <code>avrdude</code> in the following link [https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php https://burn-o-mat.net/avr8_burn_o_mat_avrdude_gui_en.php]; you can download directly the application for Ubuntu from the following link [https://projects.gctronic.com/elisa3/programming/avr8-burn-o-mat-2.1.2-all.deb avr8-burn-o-mat-2.1.2-all.deb]. 
Double click the package and install it; the executable will be <code>avr8-burn-o-mat</code>. 
Beware that the application requires the Java SE Runtime Environment (JRE) that you can download from the official page [https://www.oracle.com/technetwork/java/javase/downloads/index.html https://www.oracle.com/technetwork/java/javase/downloads/index.html], alternatively you can issue the command <code>sudo apt-get install openjdk-8-jre</code> in the terminal.

The application need a bit of configuration, follow these steps:
:1. connect the robot to the computer, the serial device will be created (something like /dev/USB0)
:2. to use the USB port the permissions need to be set to read and write issueing the command <code>sudo chmod a+rw /dev/ttyUSB0</code>
:3. start the application and click on <code>Settings => AVRDUDE</code>
:4. set the location of <code>avrdude</code> and the related configuration file (refer to the previous section when <code>avrdude</code> was installed to know the exact location); the configuration file is in <code>/etc/avrdude.conf</code>
:3. click <code>OK</code>, close the application and open it again (this is needed to load the configuration file information); click on <code>Settings => AVRDUDE</code>
:4. select <code>stk500v2</code> as the <code>Programmer</code>
:5. set the serial port connected to the robot (<code>/dev/ttyUSB0</code>)
:6. in <code>additional options</code> insert <code>-b 57600</code>, you will end up with a window like the following one:
[[File:avrdude-gui.png|400px]] 
:7. click <code>OK</code>; select <code>ATmega2560</code> in the <code>AVR type</code>
:8. in the <code>Flash</code> section search the hex file you want to upload on the robot; select <code>Intel Hex</code> on the right
:9. connect the robot to the computer, turn on the robot, wait the blinks terminate and then click on <code>Write</code> in the <code>Flash</code> section
:10. during the programming the robot will blink; at the end you'll receive a message saying <code>Flash succesfully written.</code>

====Command line====
The [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility is used to do the upload, you can download it directly from the following links depending on your system:
* [https://projects.gctronic.com/elisa3/programming/WinAVR-20100110-install.exe Windows (tested on Windows 7 and 10)]; <code>avrdude</code> will be installed in the path <code>C:\WinAVR-20100110\bin\avrdude</code>; avrdude version 5.10
* [https://projects.gctronic.com/elisa3/programming/CrossPack-AVR-20131216.dmg Mac OS X]; <code>avrdude</code> will be installed in the path <code>/usr/local/CrossPack-AVR/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 6.0.1
* Ubuntu (12.04 32-bit): issue the command <code>sudo apt-get install avrdude</code> in the terminal; <code>avrdude</code> will be installed in the path <code>/usr/bin/avrdude</code>; to check the path issue the commmand <code>which avrdude</code> in the terminal; avrdude version 5.11.1

Open a terminal and issue the following commands:
# only for windows users: <code>c:\windows\system32\mode.com com10: dtr=on</code>. You should see the robot blink (blue), if this is not the case try again the command.
# <code>avrdude -p m2560 -P COM10 -b 57600 -c stk500v2 -D -Uflash:w:Elisa3-avr-studio.hex:i -v</code> 
where <code>COM10</code> must be replaced with your com port and <code>Elisa3-avr-studio.hex</code> must be replaced with your application name; in Mac OS X the port will be something like <code>/dev/tty.usbserial-...</code>, in Ubuntu will be <code>/dev/ttyUSB0</code>. 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Basic_demo Basic demo] and [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo Advanced demo] have this command contained in the file <code>program.bat</code> in the <code>default</code> directory within the project, this can be useful for Windows users. 

===Internal EEPROM===
The internal 4 KB EEPROM that resides in the microcontroller is pre-programmed with the robot ID in the last two bytes (e.g. if ID=3200 (0x0C80), then address 4094=0x80 and address 4095=0x0C). The ID represents also the RF address that the robot uses to communicate with the computer and is automatically read at startup (have a look a the firmware for more details). 
Moreover the address 4093 is used to save the clock calibration value that is found during production/testing of the robots; this value hasn't to be modified otherwise some functionalities such as tv remote control could not work anymore. For more information on clock calibration refers to the applicaiton note [https://projects.gctronic.com/elisa3/AVR053-Calibration-RC-oscillator.pdf AVR053: Calibration of the internal RC oscillator]. 
The Elisa-3 robot supports an autonomous calibration process and the result of this calibration is saved in EEPROM starting at address 3946 to 4092. 
'''The size of usable EEPROM is thus 3946 bytes (0-3945) and the remaining memory must not be modified/erased.'''

In order to program the eeprom an AVR programmer is required, we utilize the Pocket AVR Programmer from Sparkfun (recognized as USBtiny device); then with the [https://www.ladyada.net/learn/avr/setup-win.html avrdude] utility the following command has to be issued:
<pre>
avrdude -p m2560 -c usbtiny -v -U eeprom:w:Elisa3-eeprom.hex:i -v -B 1
</pre>
where ''Elisa3-eeprom.hex'' is the EEPROM memory saved as Intel Hex format ([https://projects.gctronic.com/elisa3/Elisa3-eeprom.hex eeprom example]); a possible tool to read and write Intel Hex format is [https://projects.gctronic.com/elisa3/G32setup_12004-intel-hex-editor.exe Galep32 from Conitec Datensysteme]. 
Alternatively a program designed to writing to these EEPROM locations can be uploaded to the robot, in case an AVR programmer isn't available. The project source is available in the repository [https://github.com/gctronic/elisa3_eeprom.git https://github.com/gctronic/elisa3_eeprom.git]; it is simply needed to modify the address, rebuild and upload to the robot.

===Bootloader===
In case the bootloader of the Elisa-3 is erased by mistake, then you can restore it by using an AVR programmer. You can download the bootloader from here [https://projects.gctronic.com/elisa3/stk500v2_20.03.18_13b46ce.hex stk500v2.hex]; the source code is available from the repository [https://github.com/gctronic/elisa3_bootloader.git https://github.com/gctronic/elisa3_bootloader.git]. 
<code>Avrdude</code> can be used to actually write the bootloader to the robot with a command similar to the following one: 
<code>avrdude -p m2560 -c stk500v2 -P COM348 -v -U lfuse:w:0xE2:m -U hfuse:w:0xD8:m -U efuse:w:0xFF:m -V -U flash:w:stk500v2.hex:i -v -B 2</code> 
Here we used a programmer recognized as a serial device (port COM348) that utilizes the <code>stk500v2</code> protocol.

==Base-station==
This chapter explains informations that aren't needed for most of the users since the radio module is ready to be used and don't need to be reprogrammed. Only if you are interested in the firmware running in the radio module and on how to reprogram it then refer to section [https://www.gctronic.com/doc/index.php/Elisa#Base-station https://www.gctronic.com/doc/index.php/Elisa#Base-station] (chapter 4.2) of the Elisa robot wiki.

==PC side==
This section gives informations related to the radio module connected to the computer; if you don't have a radio module you can skip this section.
===Requirements===
Refer to the section [https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver https://www.gctronic.com/doc/index.php/Elisa#1._Install_the_radio_base-station_driver].

===Elisa-3 library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. Some basic examples will be provided in the following sections to show how to use this library. 
The source code of the library is available in the repository [https://github.com/gctronic/elisa3_remote_library https://github.com/gctronic/elisa3_remote_library]; follow the instructions in the repository to build the library.

===Multiplatform monitor===
The demo is a command line monitor that shows all the sensors information (e.g. proximity, ground, acceleromter, battery, ...) and let the user move the robot and change its colors and behavior with the keyboard. The data are sent using the protocol described in the previous section. 
The following figures show the monitor on the left and the available commands on the right. 
[[File:Cmd-line-monitor.jpg|400px]] [[File:Pc-side-commands2.jpg|400px]] 

The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_monitor https://github.com/gctronic/elisa3_remote_monitor]. 

====Windows====
Execution:
* install the driver contained in the [https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio nRFgo Studio tool] if not already done; this let the base-station be recognized as a WinUSB device (bootloader), independently of whether the libusb library is installed or not
* once the driver is installed, the pre-compiled "exe" (under <code>\bin\Release</code> dir) should run without problems; the program will prompt you the address of the robot you want to control

Compilation: 
the Code::Blocks project should already be setup to reference the Elisa-3 library headers and lib files, anyway you need to put this project within the same directory of the Elisa-3 library, e.g. you should have a tree similar to the following one:
* Elisa-3 demo (parent dir)
** <code>elisa3_remote_library</code> (Elisa-3 library project)
** <code>elisa3_remote_monitor</code> (current project)

====Linux / Mac OS X====
The project was tested to work also in Ubuntu and Mac OS X (no driver required). 
Compilation:
* you need to put this project within the same directory of the Elisa-3 library
* build command: go under "linux" dir and type <code>make clean && make</code>
Execution:
* <code>sudo ./main</code>

===Communicate with 4 robots simultaneously===
This example shows how to interact with 4 robots simlutaneously, basically it shows the sensors information (proximity and ground) coming from 4 robots and let control one robot at a time through the keyboard (you can change the robot you want to control). The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_multiple https://github.com/gctronic/elisa3_remote_multiple]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

===Obstacle avoidance===
This demo implements the ''obstacle avoidance'' behavior controlling the robot from the pc through the radio; this means that the robot reacts only to the commands received using the basic communication protocol and has no "intelligence" onboard. The demo uses the information gathered from the 3 front proximity sensors and set the motors speed accordingly; moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|F_b1TQxZKos}}

It is available also the same example but with 4 robots controlled simultaneously; the source can be downloaded from the branch <code>4robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa] 
It is easy to extend the previous example in order to control many robots, the code that controls 8 robots simultaneously can be downloaded from the branch <code>8robots</code> of the repository [https://github.com/gctronic/elisa3_remote_oa https://github.com/gctronic/elisa3_remote_oa].

===Cliff avoidance===
This demo implements the ''cliff avoidance'' behavior controlling the robot from the pc through the radio; as with the ''obstacle avoidance'' demo, the robot reacts only to the commands received from the radio. The demo uses the information gathered from the 4 ground sensors to stop the robot when a cliff is detected (threshold tuned to run in a white surface); moreover the RGB LED is updated with a random color at fixed intervals. 
The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_cliff https://github.com/gctronic/elisa3_remote_cliff]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|uHy-9XXAHcs}}
===Communication between robots via PC===
This examples shows how to emulate direct communication between robots: basically a common state is shared between the robots and this state is changed based on the current state of each robot; it emulates the facts that each robot propagates its state to all other robots. Actually all the robots communicate only with the computer (only one computer with only one radio module) and the computer forward the information to all the others robots; the radio is fast enough so that the computer in the middle will not slow down the communication. A big advantage passing from the computer is that you can log the communication messages on the computer and see what is happening. 
In particular in this demo a total of 4 robots are handled and when a robot crosses a black line, then it inform all others robots to change their color. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_communication_between_robots_via_pc https://github.com/gctronic/elisa3_communication_between_robots_via_pc]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 
The following video shows the result: 
{{#ev:youtube|4tpxoAyWfEA}}

===Set robots state from file===
This project show how to send data to robots for which we will know the address only at runtime, in particular the content of the packets to be transmitted is parsed from a csv file and the interpreted commands are sent to the robots one time. The source can be downloaded from the repository [https://github.com/gctronic/elisa3_remote_file https://github.com/gctronic/elisa3_remote_file]. For building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor]. 

===Elisa-3 Python library===
This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. 
The source code of the library and some usage examples are available in the repository [https://github.com/gctronic/elisa3_remote_library_python https://github.com/gctronic/elisa3_remote_library_python]. 

=Odometry=
The odometry of Elisa-3 is quite good even if the speed is only measured by back-emf. On vertical surfaces the absolute angle is given by the accelerometer measuring g... quite a fix reference without drifting ;-) 
A fine calibration of the right and left wheel speed parameters might give better results.
However the current odometry is a good estimate of the absolute position from a starting point.
The experiments are performed on a square labyrinth and the robot advances doing obstacle avoidance. The on-board calculated (x,y,theta) position is sent to a PC via radio and logged for further display. 
[[File:odometry-vertical.jpg|400px]] 
Details about the code can be found in the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced-demo] project, in particular the ''motors.c'' source file. The PC application used for logging data is the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor].
==Autonomous calibration==
Since the motors can be slightly different a calibration can improve the behavior of the robot in terms of maneuverability and odometry accuracy.
An autonomous calibration process is implemented onboard: basically a calibration is performed for both the right and left wheels in two modes that are forward and backward with speed control enabled. In order to let the robot calibrate istelf a white sheet in which a black line is drawed is needed; the robot will measure the time between detection of the line at various speeds. The calibration sheet can be downloaded from the following link [https://projects.gctronic.com/elisa3/calibration-sheet.pdf calibration-sheet.pdf]. 
In order to accomplish the calibration the robot need to be programmed with the [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmare] and a specific command has to be sent to the robot through the radio module or the TV remote; if you are using the radio module you can use the [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29 monitor application] in which the letter ''l (el)'' is reserved to launch the calibration, otherwise if you have a TV remote control you can press the button ''5''.
The sequence is the following: 
1. put the selector in position 8 
2. place the robot near the black line as shown below; the left motor is the first to be calibrated. Pay attention to place the right wheel as precise as possible with the black line 
[[File:elisa3-calibration-1.jpg|300px]] [[File:elisa3-calibration-2.jpg|300px]] 
3. once the robot is placed you can type the ''l (el)'' command (or press the button ''5''); wait a couple of minutes during which the robot will do various turns at various speed in the forward direction and then in the backward direction 
4. when the robot terminated (robot is stopped after going backward at high speed) you need to place it in the opposite direction in order to calibrate the right motor, as shown below. 
[[File:elisa3-calibration-3.jpg|300px]] 
5. once the robot is placed you can type again the ''l (el)'' command (or press the button ''5'') 
6. when the robot finish, the calibration process is also terminated. 

The previous figures show a robot without the top diffuser, anyway you don't need to remove it!

=Tracking=
==Assembly documentation==
You can download the documentation from here [https://projects.gctronic.com/elisa3/tracking-doc.pdf tracking-doc.pdf]. 
Have a look also at the video: 
{{#ev:youtube|92pz28hnteY}} 

==SwisTrack==
Some experiments are done with the [https://en.wikibooks.org/wiki/SwisTrack SwisTrack software] in order to be able to track the Elisa-3 robots through the back IR emitter, here is a resulting image with 2 robots: 
[[File:elisa-3-tracking-2robots.jpg|300px]] 
The pre-compiled SwisTrack software (Windows) can be downloaded from the following link [https://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip SwisTrack-compiled]. 


The following video shows the tracking of 5 robots: 
{{#ev:youtube|33lrIUux_0Q}} 
The SwisTrack software lets you easily log also the resulting data that you can then elaborate, here is an example taken from the experiment using 5 robots: 
[[File:swistrack-output.jpg|300px]] 

The following video shows the test done with 20, 30 and 38 Elisa-3 robots, the tracking is still good; it's important to notice that we stopped to 38 Elisa-3 robots because are the ones we have in our lab. 
{{#ev:youtube|5LAccIJ9Prs}} 

==Position control==
We developed a simple position control example that interacts with Swistrack through a TCP connection and control 4 robots simultaneously; the orientation of the robots is estimated only with the Swistrack information (delta position), future improvements will integrate odometry information. The following video shows the control of 4 robots that are driven in a ''8-shape''. 
{{#ev:youtube|ACaGNEQHayc}} 
[[File:tracking-8shape.jpg|300px]] 
All the following projects require the [https://www.gctronic.com/doc/index.php/Elisa-3#Elisa-3_library Elisa-3 library], for building refer to the section [https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor Multiplatform monitor].

* Horizontal position control (4 robots): the source code can be downloaded from [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-4-robots-rev245-15.01.21.zip position-control-pattern-horizontal-4-robots.zip] (Code::Blocks project). 
One of the characteristics of the Elisa-3 robot is that it can move in vertical thanks to its magnetic wheels, thus we developed also a vertical position control that use accelerometer data coming from the robot to get the orientation of the robot (more precise) instead of estimating it with the Swistrack information, you can download the source code from the following link:
* Vertical position control (4 robots): [https://projects.gctronic.com/elisa3/position-control-pattern-vertical-4-robots-rev245-15.01.21.zip position-control-pattern-vertical-4-robots.zip] (Code::Blocks project). 
We developed also an example of position control that control a single robot (code adapted from previous example) that can be useful during the initial environment installation/testing; you can download the source code from the following link:
* Horizontal position control (1 robot): [https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-1-robot-rev245-15.01.21.zip position-control-pattern-horizontal-1-robot.zip] (Code::Blocks project). 
Another good example to start playing with the tracking is an application that lets you specify interactively the target point that the robot should reach; you can download the source code of this application from the following link:
* Go to target point: [https://projects.gctronic.com/elisa3/position-control-goto-pos-horizontal-1-robot-rev245-15.01.21.zip position-control-goto-pos-horizontal-1-robot.zip] (Code::Blocks project). 

==Utilities==
In order to adjust the IR camera position it is useful to have an application that turn on the back IR of the robots. The following application [https://projects.gctronic.com/elisa3/back-IR-on-4-robots-rev245-15.01.21.zip back-IR-on-4-robots-rev245-15.01.21.zip] is an example that turn on the back IR of 4 robots, their addresses are asked to the user at the execution.

=Local communication=
{{#ev:youtube|7bxIR0Z3q3M}} 
The [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] is needed in order to use the local communication. You can find some examples on how to use this module in the main, refers to demos in selector position from 11 to 14. 
Here are some details about the current implementation of the communication module:
* use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; in the worst case (continuous receive and transmit) the sensor update frequency is about 3 Hz
* bidirectional communication
* id and angle of the proximity sensor that received the data are available
* the throughput is about 1 bytes/sec
* maximum communication distance is about 5 cm
* no reception/transmission queue (only one byte at a time)
* the data are sent using all the sensors, cannot select a single sensor from which to send the data. The data isn't sent contemporaneously from all the sensors, but the sensors used are divided in two groups of 4 alternating sensors (to reduce consumption)
== Clustering example==
In this demo there are 37 elisa-3 robots programmed with a special firmware that you can download here [https://projects.gctronic.com/elisa3/elisa3_cluster_firmware.hex elisa3_cluster_firmware.hex]; the source code is available in the repo [https://github.com/gctronic/elisa3_cluster_firmware https://github.com/gctronic/elisa3_cluster_firmware]. 
The robots will try to form some clusters by exchanging data through the local communication and at the same time exchange data with a central computer: they send their status (in cluster or not) and receive a new color when in cluster.
The application running on the computer side is available in the repo [https://github.com/gctronic/elisa3_cluster_pc https://github.com/gctronic/elisa3_cluster_pc]. 
Here is a video of the demo: 
{{#ev:youtube|MOuSfr1_3lg}}

=ROS=
This chapter explains how to use ROS with the elisa-3 robots; the radio module is needed here. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. The ROS node is implemented in cpp. Here is a general schema: 
[[File:elisa-ros-schema.png|450px]]
''Click to enlarge'' 

First of all you need to install and configure ROS, refer to [https://wiki.ros.org/Distributions https://wiki.ros.org/Distributions] for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [https://www.gctronic.com/doc/index.php/Elisa-3#Virtual_machine virtual machine]; this is the preferred way.
:* This tutorial is based on ROS Hydro. The same instructions are working with ROS Noetic, beware to use <code>noetic</code> instead of <code>hydro</code> when installing the packages.
:* If you downloaded the pre-installed VM you can go directly to section [https://www.gctronic.com/doc/index.php/Elisa-3#Running_the_ROS_node Running the ROS node].

The ROS elisa-3 node based on roscpp can be found in the following repository [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp]. 

==Initial configuration==
The following steps need to be done only once after installing ROS:
:1. If not already done, create a catkin workspace, refer to [https://wiki.ros.org/catkin/Tutorials/create_a_workspace https://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands:
<pre> mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws/
catkin_make
source devel/setup.bash </pre>
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
:3. Clone the elisa-3 ROS node repo from [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] inside the catkin workspace source folder (<tt>~/catkin_ws/src</tt>): <code>git clone https://github.com/gctronic/elisa3_node_cpp.git</code>
:4. Install the dependencies:
:ROS:
::* <code>sudo apt-get install ros-hydro-slam-gmapping</code>
::* <code>sudo apt-get install ros-hydro-imu-tools</code>
::If you are using a newer version of ROS, replace <code>hydro</code> with your distribution name.
:cpp:
::* install OpenCV: <code>sudo apt-get install libopencv-dev</code>
::If you are working with OpenCV 4, then you need to change the header include from <code>#include <opencv/cv.h></code> to <code>#include <opencv2/opencv.hpp></code>
:5. Rebuild the <code>elisa-3 library</code>: go to <code>~/catkin_ws/src/elisa3_node_cpp/src/pc-side-elisa3-library/linux</code>, then issue <code>make clean</code> and <code>make</code>
:6. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
:7. The USB radio module by default requires root priviliges to be accessed; to let the current user have access to the radio we use <tt>udev rules</tt>:

:* in the udev rules file you can find in <tt>/etc/udev/rules.d/name.rules</tt> add the following string changing the <tt>GROUP</tt> field with your current user group:
::<tt>SUBSYSTEMS=="usb", ATTRS{product}=="nRF24LU1P-F32 BOOT LDR", GROUP="viki"</tt>
:: To know which groups your user belongs to issue the command <tt>id</tt>
:* disconnect and reconnect the radio module
:8. Program the elisa-3 robot with the last [https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo advanced firmware] (>= rev.221) and put the selector in position 15

==Running the ROS node==
First of all get the last version of the elisa-3 ROS node from github:
* clone the repo [https://github.com/gctronic/elisa3_node_cpp https://github.com/gctronic/elisa3_node_cpp] and copy the <tt>elisa3_node_cpp</tt> directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src)
* build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws). 

Now you can start the ROS node, for this purposes there is a launch script (based on [https://wiki.ros.org/roslaunch roslaunch]), as explained in the following section. Before starting the ROS node you need to start <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.

===Single robot===
Open a terminal and issue the following command: <code>roslaunch elisa3_node_cpp elisa3_single.launch elisa3_address:='1234'</code> where <tt>1234</tt> is the robot id (number on the bottom).

If all is going well [https://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the elisa ROS node as shown in the following figure: 
[[File:elisa-ros-single-robot.png|300px]]
''Click to enlarge'' 

The launch script is configured also to run the [https://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: 
{{#ev:youtube|v=k_9nmEO2zqE}}

==Move the robot==
You have two options to move the robot. 

The first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right. 
[[File:elisa-teleop.png|300px]]
''Click to enlarge'' 

The second method is by directly publishing on the <code>/mobile_base/cmd_vel</code> topic, for instance by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'</code> the robot will rotate on the spot, instead by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code> the robot will move straight forward. 
Beware that there shouldn't be any other node publishing on the <code>/mobile_base/cmd_vel</code> topic (e.g. Rviz), otherwise your commands will be overwritten.

==Troubleshooting==
===Robot state publisher===
If you get an error similar to the following when you start a node with roslaunch:
<pre>
ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)
</pre>
Then you need to change the launch file from:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="state_publisher" />
</pre>
To:
<pre>
<node name="elisa3_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
</pre>
This is due to the fact that <code>state_publisher</code> was a deprecated alias for the node named <code>robot_state_publisher</code> (see [https://github.com/ros/robot_state_publisher/pull/87 https://github.com/ros/robot_state_publisher/pull/87]).

==Virtual machine==
To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and elisa. You can download the image as ''open virtualization format'' from the following link [https://projects.gctronic.com/VM/ROS-Hydro-12.04.ova ROS-Hydro-12.04.ova] (based on the VM from https://nootrix.com/2014/04/virtualized-ros-hydro/); you can then use [https://www.virtualbox.org/ VirtualBox] to import the file and automatically create the virtual machine. Some details about the system:
* user: gctronic, pw: gctronic
* Ubuntu 12.04.4 LTS (32 bits)
* ROS Hydro installed
* [https://www.cyberbotics.com/ Webots] 8.0.5 is installed (last version available for 32 bits linux)
* [https://git-cola.github.io/ git-cola] (git interface) is installed
* the <tt>catkin workspace</tt> is placed in the desktop

=Videos=
==Autonomous charge==
The following videos show 3 Elisa-3 robots moving around in the environment avoiding obstacles thanks to their proximity sensors and then going to the charging station autonomously; some black tape is placed in the charging positions to help the robots place themselves thanks to their ground sensors. The movement and charging is indipendent of the gravity. It works also vertically and up-side-down.
{{#ev:youtube|o--FM8zIrRk}}{{#ev:youtube|Ib9WdbwMlyQ}}{{#ev:youtube|xsOdxwOjmuI}}{{#ev:youtube|tprO126R9iA}}{{#ev:youtube|HVYp1Eujof8}}{{#ev:youtube|mtJd8jTWT94}}
==Remote control==
The following video shows 38 Elisa-3 robots moving around with onboard obstacle avoidance enabled; 15 of them are running autonmously, the remaining 23 are controlled from one computer with the radio module. 
{{#ev:youtube|WDxfIFhpm1g}}

File:tracking-8shape.jpg

2026-04-22T13:34:47Z

WikiSysop:

File:swistrack-output.jpg

2026-04-22T13:34:37Z

WikiSysop:

File:selector-tweezers.jpg

2026-04-22T13:34:24Z

WikiSysop:

File:Power-autonomy.jpg

2026-04-22T13:34:12Z

WikiSysop:

File:Pc-side-commands2.jpg

2026-04-22T13:33:59Z

WikiSysop:

File:odometry-vertical.jpg

2026-04-22T13:33:44Z

WikiSysop:

File:elisa-teleop.png

2026-04-22T13:33:31Z

WikiSysop:

File:elisa-ros-single-robot.png

2026-04-22T13:33:19Z

WikiSysop:

File:elisa-ros-schema.png

2026-04-22T13:33:02Z

WikiSysop:

File:Elisa-3-webots.png

2026-04-22T13:32:39Z

WikiSysop:

File:Elisa3-mainComp-digital-white.png

2026-04-22T13:32:27Z

WikiSysop:

File:Elisa3-hw-schema-bottom3.jpg

2026-04-22T13:32:11Z

WikiSysop:

File:Elisa3-charger-out.jpg

2026-04-22T13:32:01Z

WikiSysop:

File:Elisa3-charger-in.jpg

2026-04-22T13:31:51Z

WikiSysop:

File:Elisa3 and charger.JPG

2026-04-22T13:31:40Z

WikiSysop:

File:Elisa3.1-programming.jpg

2026-04-22T13:31:31Z

WikiSysop:

File:Elisa3.1-hw-schema-top.jpg

2026-04-22T13:31:14Z

WikiSysop:

File:elisa-3-tracking-2robots.jpg

2026-04-22T13:31:03Z

WikiSysop:

File:elisa3-new-case.jpg

2026-04-22T13:30:49Z

WikiSysop:

File:elisa3-matlab.jpg

2026-04-22T13:30:29Z

WikiSysop:

File:elisa3-calibration-3.jpg

2026-04-22T13:30:19Z

WikiSysop:

File:elisa3-calibration-2.jpg

2026-04-22T13:30:08Z

WikiSysop:

File:elisa3-calibration-1.jpg

2026-04-22T13:29:57Z

WikiSysop:

File:elisa3-atmelstudio3.png

2026-04-22T13:29:47Z

WikiSysop:

File:elisa3-atmelstudio2.png

2026-04-22T13:29:37Z

WikiSysop:

File:elisa3-atmelstudio1.png

2026-04-22T13:29:28Z

WikiSysop:

File:Diffuser-push-down.jpg

2026-04-22T13:29:16Z

WikiSysop:

File:Diffuser-pull-up.jpg

2026-04-22T13:29:06Z

WikiSysop:

File:Cmd-line-monitor.jpg

2026-04-22T13:28:57Z

WikiSysop:

File:avrdude-gui.png

2026-04-22T13:28:47Z

WikiSysop:

File:atmel-studio-convert.png

2026-04-22T13:28:37Z

WikiSysop:

File:Antenna-position.jpg

2026-04-22T13:28:27Z

WikiSysop:

File:Antenna-diffuser.jpg

2026-04-22T13:28:17Z

WikiSysop:

E-Puck

2026-04-22T13:16:42Z

WikiSysop:

=Hardware=

==Revisions==
There are three hardware revisions:
* HWRev 1.1: models from 0 to 1499
* HWRev 1.2: models from 1500 on, production of June 2008
* HWRev 1.3: models from 3320 on, production August 2014

The following table summarizes the differences between revisions:
{| border="1" cellpadding="10" cellspacing="0"
!
!Camera
!Bluetooth
!Accelerometer
!Microphone
|-
!HWRev 1.1
|PixelPlus PO3030 (VGA)
|LMX9820 Bluetooth 1.1
|MMA7260 3-axes analog acclerometer
|SiSonic SP0103NC3-3
|-
!HWRev 1.2
|PixelPlus PO6030 (VGA)
|LMX9838 Bluetooth 2.0
|MMA7260 3-axes analog acclerometer
|SiSonic SPM0208HD5
|-
!HWRev 1.3
|PixelPlus PO8030 (VGA)
|LMX9838 Bluetooth 2.0
|LSM330 3-axes digital (I2C) acclerometer + 3-axes gyroscope
|SiSonic SPU0414HR5H-SB
|}
The updated e-puck library handles automatically the various hardware revisions in order to be compatible with the existing standard software.

===Camera===
The orientation of the camera is different in each hardware revision and also in the case of HWRev 1.1 the same camera model can be oriented differently, here is an image that shows the different cameras and related orientation: 
[[File:epuck-cameras.jpg|300px]] 
The e-puck library configures the camera in order to get the right orientation for all situations except when it is rotated by 90 degrees.
In order to let the user distinguish the current camera mounted on the robot and in case it is rotated by 90 degrees apply the related processing, the EEPROM is modified based on the camera model mounted on the robot and its orientation. This modification follow these rules: the modification apply only to the last word of the EEPROM, at address 0x7FFFFE; bits 14 and 15 are used to indicate the rotation (11=no rotation, 01=90 degrees, 10=-90 degrees, 00=180 degrees), bits 12 and 13 are used to indicate the camera model (11=PO3030, 10=PO6030, 01=PO8030). The possible values for the EEPROM are thus:
* 0xFFFF (0xFFF1111): PO3030 with no rotation
* 0xFFFE (0xFFF1110): PO3030 turned by -90 degrees
* 0xFFF9 (0xFFF1000): PO6030 turned by 180 degrees
* 0xFFF7 (0xFFF0111): PO8030 with no rotation

The following example illustrates how to read this word:

<pre>
#include <DataEEPROM.h>

/*read HW version from the eeprom (last word)*/

int HWversion=0xFFFF;

int temp = 0;

temp = ReadEE(0x7F,0xFFFE,&HWversion, 1);
</pre>

This project ([https://projects.gctronic.com/E-Puck/writeEEPROMsrc.zip src]) is an example on how to write the last word of the EEPROM.

Beware that not all robots are shipped with the EEPROM programmed as specified previously. It is up to the user to check this modification by simply using the advanced sercom demo (selector in position 3) and requesting the version (command <code>v</code>); the hardware version returned by the command corresponds to the value of the last word of the EEPROM.

===Accelerometer===
The actual accelerometer mounted on the robot is automatically detected by the library at startup. The values ranges of the digital accelerometer are different from the analog accelerometer, but the library scale them to be similar in order to be compatible with the existing demos. The orientation of the accelerometer is shown below, the x axis points left, the y axis points forward and z points upward: 
[[File:epuck-acc-directions.png|150px]] 
For users playing with e-puck HWRev1.3 and gumstix extension refer to section [https://www.gctronic.com/doc/index.php/Overo_Extension#Accelerometer_and_gyroscope_.28e-puck_HWRev_1.3.29 Accelerometer and gyroscope (e-puck_HWRev_1.3)].

===Microphone===
From HWRev 1.3 the microphone sensitivity resulted a little bit different from the previous hardware revision; some empirical tests show that the difference is about ±15% so beware to adapt the thresholds in your applications if you need.

===Gyroscope===
The gyroscope is available from HWRev 1.3. The orientation of the gyro is shown below, the x axis points forward, the y axis points left and the z axis points upward: 
[[File:epuck-gyro-directions.png|150px]] 
For users playing with e-puck HWRev1.3 and gumstix extension refer to section [https://www.gctronic.com/doc/index.php/Overo_Extension#Accelerometer_and_gyroscope_.28e-puck_HWRev_1.3.29 Accelerometer and gyroscope (e-puck_HWRev_1.3)].

==Specifications==
The hardware specifications are valid for all e-puck models, except when explicitly specified with an hardware revision.
 

* '''Microcontroller''': Microchip dsPIC30F6014A
** [https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F6011A-6012A-6013A-6014A.pdf dsPIC30F6011A/6012A/6013A/6014A Data Sheet]
** [https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F-family-reference-manual.pdf dsPIC30F Family Reference Manual]
** [https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F_Programmers_reference_manual.pdf dsPIC30F/33F Programmer's Reference Manual]

* '''Camera''': [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=5&Itemid=14 details]
** '''HWRev 1.1''': PixelPlus PO3030K CMOS image sensor, [https://projects.gctronic.com/E-Puck/docs/Camera/PO3030K.pdf Data Sheet], no IR cut filter
** '''HWRev 1.2''': PixelPlus PO6030K CMOS image sensor, [https://projects.gctronic.com/E-Puck/docs/Camera/PO6030K.pdf Data Sheet], no IR cut filter
** '''HWRev 1.3''': PixelPlus PO8030D CMOS image sensor, [https://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf Data Sheet], no IR cut filter

* '''Bluetooth''':
** '''HWRev 1.1''': National Semiconductor LMX9820A Bluetooth Serial Port Module, [https://projects.gctronic.com/E-Puck/docs/BT/lmx9820.pdf Data Sheet], [https://projects.gctronic.com/E-Puck/docs/BT/lmx9820-sw-user-guide.pdf Software User Guide]
** '''HWRev 1.2 and 1.3''': Texas Instruments LMX9838 Bluetooth Serial Port Module, [https://projects.gctronic.com/E-Puck/docs/BT/lmx9838.pdf Data Sheet], [https://projects.gctronic.com/E-Puck/docs/BT/lmx9838-sw-user-guide.pdf Software User Guide]

* '''Microphone''': [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=19&Itemid=11 details]
** '''HWRev 1.1''': Silicon Labs Si3000 Voice Codec, [https://projects.gctronic.com/E-Puck/docs/Audio/SP0103NC3.pdf Knowles Acoustics SiSonic SP0103NC3-3 microphone with integrated amplifier]
** '''HWRev 1.2''': [https://projects.gctronic.com/E-Puck/docs/Audio/SPM0208HD5.pdf Knowles Acoustics SiSonic amplified mini microphone SPM0208HD5]
** '''HWRev 1.3''': [https://projects.gctronic.com/E-Puck/docs/Audio/SPU0414HR5H-SB.pdf Knowles Acoustics SiSonic amplified mini microphone SPU0414HR5H-SB]

* '''Optical sensors''': [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=22&Itemid=13 details]
** Vishay Semiconductors Reflective Optical Sensor [https://projects.gctronic.com/elisa3/tcrt1000.pdf Data Sheet]

* '''Accelerometer''': [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=21&Itemid=12 details]
** '''HWRev 1.1 and 1.2''': Freescale Semiconductor MMA7260Q three axis accelerometer, [https://projects.gctronic.com/E-Puck/docs/Accelerometer/MMA7260Q-Rev1.pdf Data Sheet]
** '''HWRev 1.3''': STMicroelectronics LSM330 3D accelerometer and 3D gyroscope, [https://projects.gctronic.com/E-Puck/docs/acc+gyro/LSM330.pdf Data Sheet]

* '''Motors''': [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=7&Itemid=9 details]

==Serial communication==
The communication between the robot and the computer can be also handled with a serial cable; the serial connector position on the robot, the related cable and the electric schema are shown on the following figures. 
[[File:E-puck-serial-connector.jpg|200px]] [[File:serial-cable-shop.jpg|400px]] [[File:RS232_connector_EJumper.gif|200px]] 
In order to communicate with the robot through a serial line, the robot firmware must be implemented using the functions of the UART2 instead the one of UART1 (BT). All the functions implemented for the UART1 are also available for the UART2, so it's only a matter of changing the function call names.
Anyway the [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] contains already a mode that communicates over serial line selecting position 11; in this mode you can configure the BT.

==I2C communication==
The camera, the ground sensors extension, the accelerometer (e-puck HWRev 1.3 only) and the gyro (e-puck HWRev 1.3 only) are connected to the I2C bus as slave devices (the microcontroller is the master). 
The <code>y</code> command of the [{{fullurl:Advanced sercom protocol}} Advanced sercom protocol.] can be used to read the registers values of these sensors. 
For instance you can read the camera id with the following commands: <code>y,220,0</code> and <code>y,220,1</code> that return respectively <code>128=0x80</code> and <code>48=0x30</code> (id=8030). In the same way you can read any register with the general command <code>y,220,REG_ADDR</code>. 
For the accelerometer you must use <code>60</code> as device address (<code>y,60,REG_ADDR</code>) and for the gyro you must use <code>212</code> (<code>y,212,REG_ADDR</code>). 
The device address value to be used with the <code>y</code> is obtained by shifting by one position left the I2C 7-bit address of the device, for example the camera 7-bit address is <code>0x6E</code>, by shifting one position left we get <code>0xDC=220</code>.

==Batteries==
===Battery from 2016 (last quarter) on===
The new batteries of 2016 are bit heavier (38g) but a bit more powerful (1800 mAh). The look is similar to the previous batteries and they are of course compatible with the robot and the charger. 
Take care when inserting the battery in the robot to not scratch the plastic sticker. You would need to apply a bit more force than before when inserting and removing the battery. 
The battery is covered with a plastic protection in order to avoid any possible short circuit during inserting/removing of the battery. 
The battery can be inserted only in one way: the side where the plastic protection do not cover completely the battery "top" must be towards the ground. 
 '''DO NOT REMOVE THE BLACK PLASTIC PROTECTION!''' 
[[File:battery-epuck-2016.jpg|250px]] [[File:battery-epuck-2016-2.jpg|200px]] [[File:battery-epuck-2016-3.jpg|200px]] 
This battery doesn't fit perfectly in older chargers, but it can be inserted anyway in the charger in order to make a good contact and charge it; when the contact is ok you will see the led turned on. 
[[File:batt2016-charger-side.jpg|250px]] [[File:batt2016-charger-top.jpg|200px]] 

===Battery from 2013 to 2016===
The new batteries of 2013 are lighter (33g) and a bit more powerful (1600 mAh). The look is different but they are of course compatible with the robot and the charger. Take care when inserting the battery in the robot to not scratch the plastic sticker. Is not a safety issue but keep them nice as in the beginning ;-). 
The battery is covered with a plastic protection in order to avoid any possible short circuit during inserting/removing of the battery. 
 '''DO NOT REMOVE THE PLASTIC PROTECTION!''' 
[[File:battery-epuck-new1.jpg|250px]] [[File:battery-epuck-new2.jpg|275px]] 

===Battery up to 2012===
The robots delivered in 2012 had a small difference regarding the battery; the type of battery is always the same but the mechanics of the positive pin is slightly different from one version to the other. The version with the black plastic cover comes out a bit more then the version with the brown cardboard cover. 
[[File:Batt-covers.jpg|300px]] 

The e-puck contact has been slightly modified to have a better contact with both versions as shown in the following figure; see the [https://projects.gctronic.com/E-Puck/docs/contact-modification.pdf Contact-modification.pdf] document to get more information on how to apply this modification. 
[[File:Battery-contact.jpg|300px]] 

The charger makes contact with both versions, as illustrated below. 
[[File:Batt-charger.jpg|300px]] 

The positive pin has the tendency to get a bit oxidated and might need to be scratched a bit for a perfect connection.


===Charger circuit diagram===
The circuit diagram of the e-puck charger is available on the following link [https://www.gctronic.com/doc/images/charger-circuit-diagram.png charger-circuit-diagram.png].

=Software=
==Getting started==
The robot is shipped with a standard firmware that let you immediately interact with the robot, follow these steps: 
1) put the robot selector in position 3 
2) turn on the robot and pair it with the computer:
* if you're running Linux use the system bluetooth manager to pair the robot with the computer and then issue the command ''sudo rfcomm bind /dev/rfcomm0 10:00:E8:C5:61:C9'', where ''10:00:E8:C5:61:C9'' is the BT mac address of the robot
* if you're running Windows there is a detailed guide from the [https://e-puck.gctronic.com/index.php?option=com_phocadownload&view=category&id=5:tutorials&Itemid=38 e-puck.org tutorials], here is a direct link to the guide [https://projects.gctronic.com/E-Puck/BTboot-epuck-gettingstarted.pdf BTboot epuck gettingstarted] (refer to chapter 2.3, page 6)
3) execute a terminal program (e.g. minicom for Linux or teraterm for Windows) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/rfcomm0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No" 
4) type ''h+ENTER'' and you'll be prompted with a menu that contains all the commands you can issue to the robot, for instance you can retrieve the sensors values or turn on the leds

==Library==
The embedded software running on the e-puck is continuously extended and managed in the following git repo [https://github.com/gctronic/e-puck-library https://github.com/gctronic/e-puck-library]. The repo comprises a complete library to work with all the sensors mounted on the e-puck and is the basis for many demos. You can download the library documentation form the following link [https://projects.gctronic.com/E-Puck/e-puck-library.pdf e-puck-library.pdf]. 
The content of the repo is the following:
* library: this is the low level library of the e-puck
* program:
** "Bluetooth mirror": interact with the Bluetooth chip through serial cable
** "BTCom": basically it is the "asercom" implementation, refer to [https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol Advanced sercom protocol]
** EPFL demo project: some nice demos bundled in one project, such as sound source location, obstacle avoidance and color blob detection (red and green). Some of these demos are included in the GCtronic standard firmware.
** GCtronic standard firmware project, refer to section [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware Standard firmware]
* tool:
** computer-side and e-puck side bootloader
** matlab interface/monitor for e-puck
** C++ interface/monitor for e-puck

In order to download a snapshot of the repo, go to the [https://github.com/gctronic/e-puck-library https://github.com/gctronic/e-puck-library] page and then click on the green botton named <code>Clone or download</code> and select <code>Download ZIP</code> as shonw in the following figure.
[[File:e-puck-snapshot.png|500px]] 

===Structure===
As previously mentioned the git repository includes a library to which many demos are linked. Only updates to this library that will be useful to others people and/or correct errors should be commited; some demos of this wiki makes changes to the library for the solely purpose of running the demo and thus they aren't commited to the repo. 
In order to separate the original e-puck library from what is modified in the library for the current demo, all the projects (created with MPLAB) share the same structure, that is they have to be placed within the ''program'' folder of the repository and must contain only the files of the library (and their dependencies) that have been modified. An example of this structure is shown afterwards:
* e-puck-library
** library
*** a_d
*** bluetooth
*** ...
** program
*** project1
**** a_d
***** e_prox.c
*** project2
*** ...
** tool
The library folder basically never change (unless bug fixes or new features for all users are developed). All the projects have a reference to this library folder in their build options. 
If some library files are modified for the current project, they are inlcuded in the project folder following the same structure of the original library, as shown for ''project1''. 
In order to build the project you then need to add all the modified library files from the project directory and all the others files from the main library folder. Not all files are always needed, it depends on the features that are used; for instance if the camera isn't used, the related library file could be omitted from the project saving memory space.

==Standard firmware==
The robot is initially programmed with a firmware that includes many demos that could be started based on the selector position:
* Selector position 0: Shock detection. Look at runaccelerometer.h for more information.
* Selector position 1: Detect the sound source. Look at rundetectsound.h for more information.
* Selector position 2: Follow the wall. Look at runwallfollow.h for more information.
* Selector position 3: [{{fullurl:Advanced sercom protocol}} Advanced sercom protocol.]
* Selector positoin 4: Let the robot move in a square path (using either odometry or gyroscope).
* Selector position 5: Sensor "feedback display".
* Selector position 6: Camera points to light.
* Selector position 7: Act like the ASL RS232 - I2C translator.
* Selector position 8: Show the ground direction. Look at rungrounddirection.h for more information.
* Selector position 9: Show the rotation rates of the gyroscope axes. Look at the rungyroscope.h for more information.
* Selector position 10: This position is used to work with the gumstix extension.
* Selector position 11: Bluetooth configuration (serial communication).
* Selector position 12: Global test (serial communication).
* Selector position 13: Uart1 to uart2 transponder.
* Selector position 14: Follow what is detected by the two front proximities detectors. Look at runbreitenberg_adv.h for more information.
* Selector position 15: Simple dust cleaner behaviour.

The pre-built fimrware is available from [https://projects.gctronic.com/E-Puck/DemoGCtronic-complete/DemoGCtronic-complete-4bba145.hex DemoGCtronic-complete.hex]. 
You can have a look at the source code from the following link [https://github.com/gctronic/e-puck-library/tree/master/program/DemoGCtronic-complete https://github.com/gctronic/e-puck-library/tree/master/program/DemoGCtronic-complete]; beware that the project is actually included in the e-puck library repository, refer to section [https://www.gctronic.com/doc/index.php?title=E-Puck#Library Library] to download it.

===Project building===
In order to build the project you need to install the MPLAB X IDE and related compiler, refer to section [https://www.gctronic.com/doc/index.php?title=E-Puck#MPLAB_X Programming: MPLAB X]. 
The standard firmware project is based on the e-puck library (refer to [https://www.gctronic.com/doc/index.php?title=E-Puck#Library Library] section). 
To build the project follow these steps: 
1) download and extract the e-puck library repository (refer to section [https://www.gctronic.com/doc/index.php?title=E-Puck#Library Library]), let say in the folder <code>e-puck-library</code>; you should have the following situation:
* e-puck-library
** library
** program
*** ...
*** DemoGCtronic-complete
** tool
2) Open MPLAB X, then click <code>File=>Open Project</code> and select the project file <code>demoGCtronic.X</code> you can find in <code>e-puck-library\program\DemoGCtronic-complete</code>. If you're asked to upgrade the project to the current IDE version, click <code>yes</code> to confirm. 
3) Right click on the project name (on the left panel) and select <code>Properties</code> as shown in the following figure: 
[[File:e-puck-project-build1.png|500px]] 
4) Select the <code>XC16</code> compiler from the <code>Compiler Toolchain</code> section and then click <code>OK</code> as shown in the following figure: 
[[File:e-puck-project-build2.png|500px]] 
5) Open the project properties once more (right click on project name and then select <code>Properites</code>), a new configuration will be available for the XC16 compiler. On the left panel select <code>xc16-gcc</code>, then on the right specify <code>Memory model</code> and verify that the <code>Code model</code> is set to <code>Large</code>. Confirm with <code>OK</code> as shown in the following figure: 
[[File:e-puck-project-build3.png|500px]] 
6) Now you can build the project by clicking on the <code>Build project</code> button (hammer icon on the top) or by pressing <code>F11</code>; if all is working you should end up with a successfully built firmware as shown in the following figure: 
[[File:e-puck-project-build4.png|500px]] 

==Programming==
===MPLAB X===
If you are interested in development of embedded applications, you should firstly choose an adequate development environment. One of the most known IDE is the <code>MPLAB Integrated Development Environment</code> that you could download for free from the Microchip site; Microchip offers also the C compiler for free. One big advantage of this IDE is that it is multiplatform (Windows, Linux, Mac) and also the compiler is available for each platform. 
To work with the e-puck software you need to:
* download and install the [https://www.microchip.com/mplab/mplab-x-ide MPLAB X IDE]; during installation select also <code>MPLAB IPE</code> to be installed, it is a nice utility to have
* download and install the [https://www.microchip.com/mplab/compilers compiler], it must be the <code>MPLAB XC16</code> (supports all 16-bit PIC MCUs and dsPICs)

Useful information related to the compiler can be found in the [https://projects.gctronic.com/E-Puck/docs/Programming/MPLAB_XC16_C_compiler_users_guide.pdf MPLAB XC16 C compiler user's guide].

===Aseba===
Aseba is a set of tools which allow novices to program robots easily and efficiently, refere to [https://aseba.wikidot.com/en:gettingstarted https://aseba.wikidot.com/en:gettingstarted] for more information. 
Here is the page with the basic information needed to start working with Aseba and the e-puck robot [https://aseba.wikidot.com/en:e-puck https://aseba.wikidot.com/en:e-puck]. 
You can download an MPLAB X project based on the git repo [https://github.com/aseba-community/aseba-target-epuck https://github.com/aseba-community/aseba-target-epuck] in the following link [https://projects.gctronic.com/E-Puck/aseba.zip aseba.zip]; place it in the "e-puck-library/program" folder (refer to section [https://www.gctronic.com/doc/index.php/E-Puck#Library https://www.gctronic.com/doc/index.php/E-Puck#Library] for more information on how to build). 
You can download the last aseba firmware for the e-puck from the following link [https://projects.gctronic.com/E-Puck/aseba-target-epuck.hex aseba-target-epuck.hex]. 
Beware that at the moment the only bootloader capable of uploading the ''aseba-target-epuck.hex'' to the robot is the Linux version.

===Python===
Python is a widely used programming language supported by a large and comprehensive standard library. A Python library is available enabling the remote control of the e-puck robot, read the sensors values, control the motors while running the heavy processes on a computer.
You can start playing with the e-puck and Python by downloading the [https://projects.gctronic.com/E-Puck/epuck-python.zip e-puck python package], it contains:
* [https://www.python.org/download/releases/2.6.6/ Python 2.6.6]
* [https://pypi.python.org/pypi/setuptools Python setup tools]
* e-puck Python library: [https://github.com/mmartinortiz/pyePuck source]
* e-puck Python library dependencies: [https://github.com/karulis/pybluez pybluez], [https://pillow.readthedocs.io/en/stable/ Python imaging library]
* some examples (refers to [https://github.com/mmartinortiz/pyePuck/tree/master/examples examples])
Follow these steps to install Python and run your first Python example (this instructions are for Windows but the procedure should be similar also for Linux and Mac OS):
# Install Python (the executable ''python-2.6.6.msi'' is in the ''Python2.6'' directory)
# Install the Python setup tools by running the script ''ez_setup.py'' you find in the ''Python2.6'' directory:
## issue the command ''python ez_setup.py'' in a terminal
## alternatively you can download an IDE that will help you in programming, run and debug your code; a valid IDE is called [https://www.jetbrains.com/pycharm/ PyCharm]
# Install e-puck Python library dependencies:
## install pybluez by issueing the command ''python setup.py install'' in a terminal (be sure to be in the ''dependencies\pybluez-master'' directory)
## install the PIL library by executing ''PIL-1.1.7.win32-py2.6.exe'' you find in the ''dependencies'' directory
# Program the e-puck with the last [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] and put the selector in position 3
# Configure the Bluetooth connection with the e-puck in the computer (add Bluetooth device and insert its pin)
## when you add the e-puck robot as Bluetooth device, right click on the device and choose property; in the "Bluetooth" tab you'll find the mac address (something like 10:00:e8:c5:61:c9). Copy this address since you'll need it to connect to the robot when running the Python scripts
# In the ''examples'' directory you'll find the e-puck library ''ePuck.py'' and 3 examples ''braitenberg.py'', ''line_follower.py'', ''photo_taker.py''
## the ''ePuck.py'' file must be placed in the same directory as your script
## to run an example issue the command ''python script_name.py mac_address'', where ''script_name'' is either ''braitenberg'' or ''line_follower'' or ''photo_taker'' and ''mac_address'' is the address that you previously annotate (e.g. ''10:00:e8:c5:61:c9'')

==PC interface==
An interface running on a computer and connecting to the e-puck through bluetooth based on the advanced sercom protocol (selector 3) was developed; from this interface it's possible to have information about all the sensors, receive camera images and control the leds and motors. The source code is available from the following links:

* Multiplatform version 3.0 ([https://projects.gctronic.com/E-Puck/Monitor/MultiPlatformMonitorSrc1.8.zip Monitor3.0 source code]); the application is a Qt project, so the compilation may be handled easily with [https://www.qt.io/product/development-tools Qt Creator]; alternatively [https://doc.qt.io/qt-6/qmake-manual.html qmake] can be used. The following executables are compiled dynamically, so the [https://www.qt.io/download Qt library (4.5.0 or higher)] must be installed in the system in order to run them:
**[https://www.gctronic.com/doc/images/EPuckMonitor Linux executable]: before running the executable, type "chmod +x file"
**[https://www.gctronic.com/doc/images/EPuckMonitor.app.zip MacOS executable]
**[https://www.gctronic.com/doc/images/EPuckMonitorWin.zip Windows executable (+ dlls); tested on Windows XP, Windows Vista, Windows 7, Windows 10] 
[[File:Monitor3.0.jpg|300px]] 
Since the last version comprises a basic OpenGL representation of the e-puck you will need also the OpenGL extension libraries in order to compile the project; these should be included in the Qt SDK, but if you encounter problems refers to [https://doc.qt.io/qt-6/qtopengl-index.html qtopengl]; basically you need to download manually the OpenGL libraries: GLX (Linux), CGL (MacOS), WGL (Windows). 
Once the project is built dynamically, some errors about missing dll may be thrown; one of these missing libraries could be the [https://projects.gctronic.com/E-Puck/Monitor/mingwm10.dll mingwm10.dll]. Others could be related to Qt. To solve the problem you need either to build the project statically, or to register the libraries on the system, or to manually include all the dll with the executable.

==Connecting to multiple robots==
A Python example is available for e-puck2 in the following section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_multiple_robots PC side development: Connecting to multiple robots]. This example is compatible also with the e-puck1 robot.

==Examples==
===Basic demos===
The following set of simple programs for the e-puck has an increasing degree of complexity, from very basic LED blinking up to motor control depending on sensor input; it's a good starting point for beginner users. The first demos do not use interrupts and keep to a minimum the use of the library.
You can download the set of these demos from this link [https://www.gctronic.com/doc/images/BasicDemos.zip BasicDemos.zip]. 
A list of these basic programs is listed below:
* demo0: very simple LEDs blinking
* demo1: LEDs blinking (pause with timer)
* demo2: selector reading + LEDs
* demo3: send selector position via Bluetooth (simplified method)
* demo4: proximity reading with interrupts + LEDs
* demo5: proximity reading with interrupts + LEDs + send values via BT (assembler version with interrupt and buffer)
* demo6: motor speed controlled depending on front proximity sensor values

Compilation: the demos can be edited and compiled using MPLAB IDE (windows), clicking directly on the project file. The demos should be compiled with MPLAB-C30 on all operating systems.
The compiled .hex file is downloaded to the e-puck robot via Bluetooth using for example tinyBootloader.

===Audio recording===
This demo program ([https://projects.gctronic.com/E-Puck/DemoGCtronic-recording/DemoGCtronic-recording.hex hex file], [https://projects.gctronic.com/E-Puck/DemoGCtronic-recording/DemoGCtronic-recording.zip MPLAB project]) let the e-puck recording for about two seconds whatever you like and then reproduces it infinitely. 
The program starts with a led animation (flow) and then turns all leds on for about two seconds, this is the moment for recording; note that only the right micro (mic0) is used. 
It's possible also to choose the volume/amplification of the reproduction using the selector (from 1 to 16).

===Still images===
This demo program is optimized to let the robot handle images with resolution up to 640x480 pixels (the maximum reachable by the camera); after acquisition, the robot sends the images to a computer through bluetooth. This zip [https://projects.gctronic.com/E-Puck/ImageReceiverBT.zip ImageReceiverBT.zip] contains both the program for the robot (hex file) and the application for the computer (Windows platform). The selector of the robot must be in position 3. 
You can find the sources for the application running on the computer side from this link [https://projects.gctronic.com/E-Puck/ImageReceiverBTsrc.rar ImageReceiverBTsrc.rar]. 
You can find the MPLAB project for the application running on the robot from this link [https://projects.gctronic.com/E-Puck/DemoGCtronic-vga-images.zip DemoGCtronic-vga-images.zip].

===Robots Collective Behavior===
This is a Bachelor project developed by Jean-Roch Lauper at the [https://www.unifr.ch/ University of Fribourg]. The project's focus is on collective behaviors as well as on the use of sound to communicate between robots; moreover there are demos to interact with the robot through sensors and play with sound. 
The code is available on [https://github.com/jrlauper/jrl_epuck Github]. Demo videos are available on [https://www.youtube.com/playlist?list=PLrscHgSUZPdr38tirAsB4_4Q93khKP9Rv Youtube].



==Bootloader==
* Windows: [https://projects.gctronic.com/E-Puck/TinyBld_1_10_6_pc_beta.zip Tiny Bootloader v1.10.6] or [https://sourceforge.net/projects/tinypicbootload/ Tiny Multi Bootloader+]
* Linux: [https://projects.gctronic.com/E-Puck/epuck-bootloader-linux.zip epuck-bootloader-linux.zip]
** requirements: <code>sudo apt-get install libbluetooth-dev</code>
* Mac OS: https://github.com/gctronic/e-puck-library/tree/master/tool/bootloader/computer_side/multi_platform
** actually it is a Perl script, thus in principle it could be used also in Linux and Windows
** after pairing with the robot, you should issuing a command similar to <code>./epuckupload -f firmware.hex /dev/tty.e-puck_3675-COM1</code> and then press the reset button on the robot


==Others tools==
From the official e-puck site you can find information about others software tools available for the e-puck robot in the following link [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=18&Itemid=24 https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=18&Itemid=24]. 
===Local communication===
An example of such tools is the [https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=32&Itemid=28 libIrcom], a local communication library exploiting the proximity sensors placed around the robot to modulate infrareds. 
If an higher throughput and longer communication distance are required, there is the [https://www.gctronic.com/doc/index.php/Others_Extensions#Range_and_bearing range and bearing extension] designed for this purpose.

=ROS=
This chapter explains how to use ROS with the e-puck robots; basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema: 
[[File:epuck-ros-schema.png|450px]] 
''Click to enlarge'' 

First of all you need to install and configure ROS, refer to [https://wiki.ros.org/Distributions https://wiki.ros.org/Distributions] for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [https://www.gctronic.com/doc/index.php/E-Puck#Virtual_machine virtual machine]; this is the preferred way.
:* This tutorial is based on ROS Hydro.
:* If you downloaded the pre-installed VM you can go directly to section [https://www.gctronic.com/doc/index.php/E-Puck#Running_the_ROS_node Running the ROS node].

The ROS epuck driver was initially developed by the [https://www.verlab.dcc.ufmg.br/ Verlab Laboratory at Universidade Federal de Minas Gerais], the related code can be found in the following repository [https://github.com/verlab-ros-pkg/epuck_driver https://github.com/verlab-ros-pkg/epuck_driver]. It is based on [https://wiki.ros.org/rospy rospy] (Python). We extended the initial driver to support all the e-puck sensors, the code can be found in the following repository [https://github.com/gctronic/epuck_driver https://github.com/gctronic/epuck_driver]. 
Starting from the work done with the ROS epuck driver for python, we developed another ROS node based on roscpp that has the same functionalities; the code can be found in the following repository [https://github.com/gctronic/epuck_driver_cpp https://github.com/gctronic/epuck_driver_cpp].

==Initial configuration==
The following steps need to be done only once after installing ROS:
:1. If not already done, create a catkin workspace, refer to [https://wiki.ros.org/catkin/Tutorials/create_a_workspace https://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands:
<pre> mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
catkin_init_workspace
cd ~/catkin_ws/
catkin_make
source devel/setup.bash </pre>
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
:3. Clone the ROS epuck driver repo:
:* if you are working with Python: from [https://github.com/gctronic/epuck_driver https://github.com/gctronic/epuck_driver]; you'll have a directory named <tt>epuck_driver</tt> that is the repo local copy
:* if you are working with cpp: from [https://github.com/gctronic/epuck_driver_cpp https://github.com/gctronic/epuck_driver_cpp]; you'll have a directory named <tt>epuck_driver_cpp</tt> that is the repo local copy
:4. Copy the repo directory <tt>epuck_driver</tt> or <tt>epuck_driver_cpp</tt> (this is the actual ros package) inside the catkin workspace source folder (<tt>~/catkin_ws/src</tt>)
:5. Install the dependencies:
:* Python:
:** The ROS epuck driver is based on the e-puck Python library that requires some dependencies:
:*** install the Python setup tools: <code>sudo apt-get install python-setuptools</code>
:*** install the Python image library: <code>sudo apt-get install python-imaging</code>
:*** install pybluez:
:**** download [https://github.com/karulis/pybluez pybluez] and extract it
:**** install pybluez dependencies: <code>sudo apt-get install libbluetooth-dev</code>
:**** go to the pybluez directory and issue the command <code>python setup.py install</code>
:* cpp:
:** install the library used to communicate with Bluetooth: <code>sudo apt-get install libbluetooth-dev</code>
:6. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
:7. Program the e-puck with the last [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] and put the selector in position 3

==Running the ROS node==
First of all get the last version of the ROS epuck driver from github:
* Python: clone the repo [https://github.com/gctronic/epuck_driver https://github.com/gctronic/epuck_driver] and copy the <tt>epuck_driver</tt> directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src)
* cpp: clone the repo [https://github.com/gctronic/epuck_driver_cpp https://github.com/gctronic/epuck_driver_cpp] and copy the <tt>epuck_driver_cpp</tt> directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src)
Finally build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws). 

If you're using Pyhton make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): <code>chmod +x ./src/epuck_driver/scripts/epuck_driver.py</code>. 

Now you can finally start the ROS node, for this purposes there are two launch scripts (based on [https://wiki.ros.org/roslaunch roslaunch]), one for working with a single robot and the other to work with multiple robots. Before actually starting the node you need to configure the e-puck robot as Bluetooth device in the system and copy its mac address (this will be needed when launching the ROS node); if you want to work with multiple robots you need to add all of them as Bluetooth devices in the system and copy all the mac addresses. The procedure to add a Bluetooth device is:
# Go to <tt>System Settings</tt> (left panel has a link)
# Click on <tt>Bluetooth</tt>
# Click on the <tt>+</tt> sign in the bottom left of the window to start the procedure
# Turn on the robot and click <tt>continue</tt>, now the search is started and after a little while the robot should appear on the list of found devices
# Click on <tt>PIN Options...</tt>, select <tt>Cutom PIN</tt>, enter the correct robot PIN (robot id) and click <tt>Close</tt>
# Now click <tt>Continue</tt> and the robot will be paired
# To know the mac address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related mac address
The ROS e-puck driver based on roscpp has the possibility to automatically search for the robots, so you don't need to specify the mac address but you need to pass only the robot id; pay attention that you still need to pair the robot to the computer as explained in the previous steps. Anyway is recommended to specify the mac address to speed up and facilitate the connection (especially with multiple robots).

First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.

===Single robot===
Open a terminal and issue the following command:
* Python: <code>roslaunch epuck_driver epuck_controller.launch epuck_address:='10:00:E8:C5:61:C9'</code>. 
* cpp: <code>roslaunch epuck_driver_cpp epuck_controller.launch epuck_id:='3000' epuck_address:='10:00:E8:C5:61:C9'</code>. 
<tt>10:00:E8:C5:61:C9</tt> is the e-puck Bluetooth mac address and <tt>3000</tt> is the e-puck id (number on the case).

If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data (the blink is done only when using the Python ROS driver) and [https://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the epuck driver node. The following graph shows all the topics published by the epuck driver node (Pyhton): 
[[File:rosgraph-single-robot.png|300px]] [[File:epuck-ros-single-robot.png|300px]] 

'''Cpp ROS driver''' 
The cpp ROS driver launch script is configured also to run the [https://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: 
{{#ev:youtube|hn1FmpbF4rM}}

===Multiple robots===
The script is designed to work with 4 e-puck robots and you need to modify the script in order to use the correct Bluetooth mac addresses:
* open the file <tt>~/catkin_ws/src/epuck_driver/launch/multi_epuck.launch</tt> (Python) or <tt>~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck.launch</tt> (cpp)
* on top of the file you'll see a list of 4 e-puck addresses, change their values accordingly
Now you can start the node by issueing the following command in a terminal:
* Python: <code>roslaunch epuck_driver multi_epuck.launch</code>
* cpp: <code>roslaunch epuck_driver_cpp multi_epuck.launch</code>
If all is going well you'll see the robots make a blink meaning they are connected and ready to exchange data (the blink is done only when using the Python ROS driver) and [https://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the proximity and odometry of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm. 

In order to move the robots you can either use a TV remote or you can directly use ROS by publishing velocities commands by issueing the following command: 
<code>rostopic pub -1 /epuck_robot_0/mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code>
* this command will move the ''first'' e-puck with a linear velocity of 1 rotation per second (robot moves straight)
* only the ''x'' component of the linear velocity and the ''z'' component of the angular velocity are used
* for more information on the ''Twist'' message refer to [https://docs.ros.org/api/geometry_msgs/html/msg/Twist.html https://docs.ros.org/api/geometry_msgs/html/msg/Twist.html]

[[File:roscpp_4robots.png|300px]]
''Click to enlarge'' 

===Visualize the camera image===
In order to visualize the image through ROS you need to use the launch script for a single robot with an additional parameter <tt>cam_en</tt> as follows: 
* Python: <code>roslaunch epuck_driver epuck_controller.launch epuck_address:='10:00:E8:C5:61:C9' cam_en:='true'</code>
* cpp: <code>roslaunch epuck_driver_cpp epuck_controller.launch epuck_id:='3000' epuck_address:='10:00:E8:C5:61:C9' cam_en:='true'</code>
Then with the Python ROS driver you need to open another terminal and issue the command <code>rosrun image_view image_view image:=/camera</code> that will open a window wiht the e-puck camera image. 
With the cpp ROS driver the image is visualized directly in the rviz window (on the right), as shown in the following image: 

[[File:roscpp_1robot.png|300px]]
''Click to enlarge'' 

==Virtual machine==
To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and e-puck. You can download the image as ''open virtualization format'' from the following link [https://projects.gctronic.com/VM/ROS-Hydro-12.04.ova ROS-Hydro-12.04.ova] (based on the VM from https://nootrix.com/2014/04/virtualized-ros-hydro/); you can then use [https://www.virtualbox.org/ VirtualBox] (together with the VirtualBox Extension Pack) to import the file and automatically create the virtual machine. Some details about the system:
* user: gctronic, pw: gctronic
* Ubuntu 12.04.4 LTS (32 bits)
* ROS Hydro installed
* PyCharm: Python IDE used to extend the rospy e-puck driver; when you open the IDE it will open a project pointing to the ROS e-puck driver so you can immediately start diving into the code
* [https://www.cyberbotics.com/ Webots] 8.0.5 is installed (last version available for 32 bits linux)
* [https://git-cola.github.io/ git-cola] (git interface) is installed
* the <tt>catkin workspace</tt> is placed in the desktop

If you encounter problems related to network adapters not recognized when booting the imported virtual machine then you need to follow these steps:
# close VirtualBox
# go to the directory <tt>C:\Users\YOUR_USER\VirtualBox VMs\ROS Hydro - 12.04</tt>
# open the file <tt>ROS Hydro - 12.04.vbox</tt> with a text editor, remove all the content of the <tt><Network</tt> tag and save
# open VirtualBox, select "ROS Hydro - 12.04" and under settings enable the network card (if you need it)
# start the virtual machine

==Webots==
The [https://www.cyberbotics.com/ Webots] simulator integrates a ROS controller that publishes the sensor data of the e-puck robot in ROS, then we can exploit the multitude of packages available in ROS to process the sensors data and simulate the behavior of the e-puck by issueing commands through ROS. 
Once we're satisfied with the results in the simulator, we can test our algorithms in the real world by remote controlling the e-puck through Webots. 
The following steps shows how to run the example included in Webots that let the e-puck follow a line using ROS: 
# Install the last version of [https://www.cyberbotics.com/ Webots] following the [https://www.cyberbotics.com/doc/guide/installing-webots instructions]; pay attention that starting from Webots 8.1.0 the support to linux 32 bit was dropped. The following instructions are based on Webots 8.2.1 and Ubuntu 14.0.4 64 bits (you can download a pre-installed virtual machine with ROS and Ubuntu from [https://nootrix.com/downloads/#RosVM https://nootrix.com/downloads/#RosVM].
# Create a catkin workspace as explained in section [https://www.gctronic.com/doc/index.php/E-Puck#Initial_configuration Initial configuration] if you didn't already done
# Copy the directory <tt>nodes</tt> from <tt>WEBOTS_MODULES_PATH/projects/languages/ros/</tt> (e.g. <tt>/home/viki/.local/share/Cyberbotics/Webots/8.2/projects/languages/ros/</tt>) to the catkin workspace source folder (e.g. <tt>~/catkin_ws/src</tt>)
# Copy the directory <tt>srv</tt> from <tt>WEBOTS_MODULES_PATH/projects/default/controllers/ros/include</tt> (e.g. <tt>/home/viki/.local/share/Cyberbotics/Webots/8.2/projects/default/controllers/ros/include</tt>) to the <tt>nodes</tt> package just copied (e.g. ~/catkin_ws/src/nodes)
# Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>
# Open another terminal and start ROS by typing <code>roscore</code>
# Start Webots and open the ROS e-puck example: File => Open Sample World => languages => ros => e-puck_line.wbt and play it
# Now from the terminal positioned to the catkin workspace issue the command <code>rosrun nodes e-puck_line 60</code>, where 60 is the duration in seconds; you should see the e-puck follow the line in the simulator
For more information have a look at the <tt>Readme</tt> you can find in <tt>WEBOTS_MODULES_PATH/projects/languages/ros/nodes</tt> (e.g. <tt>/home/viki/.local/share/Cyberbotics/Webots/8.2/projects/languages/ros/nodes</tt>) or refer to the Webots user guide chapter [https://cyberbotics.com/doc/guide/using-ros Using ROS]. 
'''The EDU license is valid to play with Webots and ROS (PRO license not required).'''

===Webots ROS SLAM with e-puck===
This example shows how to use the [https://wiki.ros.org/gmapping gmapping (SLAM)] package of ROS to let the e-puck robot construct a map of the simulated environment; the map is visualized in real-time directly in the rviz window. Here are the steps to run the demo:
# download the code from the following link [https://projects.gctronic.com/E-Puck/ROS/webots-ros-slam.zip webots-ros-slam.zip] and extract the zip
# copy the source file <tt>nodes/src/e-puck_line_slam.cpp</tt> to the catkin workspace folder of the Webots nodes (e.g. <tt>~/catkin_ws/src/nodes/src</tt>)
# copy the folders <tt>nodes/config</tt>, <tt>nodes/launch</tt> and <tt>nodes/urdf</tt> to the catkin workspace folder of the Webots nodes (e.g. <tt>~/catkin_ws/src/nodes/</tt>)
# copy the files <tt>nodes/CMakeLists.txt</tt> and <tt>package.xml</tt> to the catkin workspace folder of the Webots nodes (e.g. <tt>~/catkin_ws/src/nodes/</tt>) by substituting the current ones
# Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>
# Open another terminal and start ROS by typing <code>roscore</code>
# Start Webots and open <tt>worlds/e-puck_line_slam.wbt</tt>: File => Open World => look for the directory containing <tt>e-puck_line_slam.wbt</tt> and play it
# Now from the terminal positioned to the catkin workspace issue the command <code>roslaunch nodes epuck_controller.launch</code>
Here is a video: 
{{#ev:youtube|L-NkvSQY5tU}}

===Webots ROS and OpenCV with e-puck===
This example shows how to integrate [https://opencv.org/ OpenCV] with ROS to let the e-puck robot detect and follow a ball in the simulated environment. Here are the steps to run the demo:
# download the code from the following link [https://projects.gctronic.com/E-Puck/ROS/webots-ros-opencv.zip webots-ros-opencv.zip] and extract the zip
# copy the source file <tt>nodes/src/e-puck_opencv.cpp</tt> to the catkin workspace folder of the Webots nodes (e.g. <tt>~/catkin_ws/src/nodes/src</tt>)
# copy the files <tt>nodes/CMakeLists.txt</tt> and <tt>package.xml</tt> to the catkin workspace folder of the Webots nodes (e.g. <tt>~/catkin_ws/src/nodes/</tt>) by substituting the current ones
# Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>
# Open another terminal and start ROS by typing <code>roscore</code>
# Start Webots and open <tt>worlds/e-puck_opencv.wbt</tt>: File => Open World => look for the directory containing <tt>e-puck_opencv.wbt</tt> and play it
# Now from the terminal positioned to the catkin workspace issue the command <code>rosrun nodes e-puck_opencv 20 140 0 0 150 255 255</code>, where
::* 20 is the duration in seconds
::* 140, 0, 0 are the min H, S and V respectively of the blob to detect
::* 150, 255, 255 are the max H, S and V respectively of the blob to detect

==E-puck gumstix extension==
For more information on how to use ROS with the e-puck gumstix extension refer to section [https://www.gctronic.com/doc/index.php/Overo_Extension#ROS https://www.gctronic.com/doc/index.php/Overo_Extension#ROS].

=Test and Results=
==Bluetooth Communication Testing - PC to robot==
Some tests were performed in order to analyze the bluetooth speed between a computer and the e-puck; the following three experiments were executed sending the same total amount of data but differently subdivided:
* 19200 packets of 6 bytes each sent from computer to e-puck: about 65 seconds ([https://www.gctronic.com/doc/images/BTspeed.zip BTspeed.zip])
* 2560 packets of 45 bytes each sent from computer to e-puck: about 20 seconds ([https://www.gctronic.com/doc/images/BTspeedPackets.zip BTspeedPackets.zip])
* 1 packet of 115200 bytes sent from computer to e-puck: about 10 seconds ([https://www.gctronic.com/doc/images/BTspeedFile.zip BTspeedFile.zip])
Explanation: dividing a packet in small chunk of data (such as a single command) introduces pauses generated by the Bluetooth device of the PC. The mean measured delay time between a packet and the other is about 3 ms, but could be as high as 20 ms. Sending the packet in one single block like in the third experiment, has no pauses and thus needs exactly the theoretical time of 10 seconds for the channel at 115'200 Baud.

==Bluetooth Communication Testing - robot to robot==
Some tests were performed also to analyze the maximum speed reachable between two robots using direct communication, that is one acting as the master and the other as the slave. The Bluetooth 2.0 specification asserts 1 Mbit/s air data rate, but in practice with the Bluetooth protocol overhead the usable bandwidth is lower; moreover in our case there are others two facts to take in consideration:
# the communication between the robot and the BT chip is configured to be at 115200 bps
# the buffer handling system of the BT chip is capable of receive at maximum 200 packets per second (refers to [https://projects.gctronic.com/E-Puck/docs/BT/SB_UART_AN.pdf UART buffer AN.pdf])
From the tests the resulting throughput is '''18 Kb/s''', sending a total of 41000 bytes with 41 bytes for each packet and waiting the response from the chip before sending the next packet; moving the slave device several meters away from the master influences the communication speed, that slows down. 
The sources (MPLAB project) of the firmware used for this test can be downloaded from the following link [https://projects.gctronic.com/E-Puck/DemoGCtronic-BT.zip DemoGCtronic-BT.zip] (master=selector position 9, slave=selector position 4). 
There is an additional example that shows how to establish a direct Bluetooth link between two e-pucks. This firmware is intended to be programmed on the master robot (selector 0); the master will send commands using the "asercom protocol" to a slave robot, that is the first robot found during the search, in order to turn on its leds in sequence. The slave robot is intended to be programmed with the [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] (selector position 3). 
You can download the MPLAB X project from here [https://projects.gctronic.com/E-Puck/DemoGCtronic-BT-asercom.zip DemoGCtronic-BT-asercom.zip]; in order to build refer to section [https://www.gctronic.com/doc/index.php/E-Puck#Project_building Project_building]. The Bluetooth library was extended to build this demo, you can download it from here [https://projects.gctronic.com/E-Puck/bluetooth.zip bluetooth.zip]; this library must replace the one included in the e-puck library in order to build the project. 
There are various modes available on this demo, depending on the selector position:
* 0: search for an e-puck1 or e-puck2 and connect to the first one found, then send some commands to it through the [https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol]
* 1: receiver mode (template)
* 2: connect directly to an e-puck1 (no search is accomplished) and then send some commands to it
* 3: connect directly to an e-puck2 (no search is accomplished) and then send some commands to it

==e-puck balancing==
The users can transform the e-puck in a self balancing robot by applying some mechanical modifications as shown in the following figure. Here are the 3d models of the [https://projects.gctronic.com/E-Puck/balance/WheelExtensionD52.STL wheel tyre extension] and [https://projects.gctronic.com/E-Puck/balance/Spacer28mm.STL spacer]. For more information on the assembly please contact us. 
[[File:epuck-balance.jpg|250px]]
''Click to enlarge'' 

Here is a video of the e-puck trying to self balance; this is only a starting point to demonstrate the feasiblity, so you can take the [https://projects.gctronic.com/E-Puck/balance/DemoGCtronic-balance.zip code (MPLAB X project)] and improve it.
{{#ev:youtube|JVz0P2ZaCsw}}

==e-puck and Arduino==
The [https://www.arduino.cc/ Arduino] boards are used widely in the hobby community and you can extend the functionalities of a board by using the so called ''shields''; there are tons of shields like WiFi, SD reader/writer, battery, XBee, GSM, speech recognition, rfid, ... there is a shield for everything (almost). For these reasons we decided to connect an Arduino to the e-puck robot. 
I2C is used to communicate between the e-puck (master) and the Arduino (slave), this is the easiest way to get both a communication channel and the power from the e-puck thanks to an already available connector on the robot. The connector is placed on the bottom side of the e-puck main pcb as shown in the following figures: 
[[File:epuck-arduino-connector2.jpg|250px]]
''Click to enlarge''
[[File:epuck-arduino-connector3.jpg|250px]]
''Click to enlarge'' 
The following figure shows the schema to connect the e-puck to the Arduino Uno board; you can follow the same schema to connect to other Arduino boards paying attention to the related pinout. 
Power and voltage considerations: in this configuration, the e-puck battery (LiPo 3.7Volt) powers directly also the Arduino board to its 5 Volt line. This is ok for the tested demos but it might be limiting in some rare cases. Let us know your goals and experiments to get support. The I2C lines are simply protected with 2 series resistors in order to limit any excessive current into the PIC. 
[[File:epuck-arduino-schema.png|350px]]
''Click to enlarge'' 
Here is a video of a demo in which you can control the e-puck with your voice; the e-puck is connected to an [https://www.arduino.cc/en/Main/ArduinoBoardUno Arduino Uno] that is extended with an [https://www.veear.eu/ Easy VR shield] for speech recognition.
{{#ev:youtube|9tNM7lEzFMQ}}
The source code of the demo is available in the following links: [https://projects.gctronic.com/E-Puck/arduino/DemoGCtronic-arduino.zip MPLAB project] for the e-puck, [https://projects.gctronic.com/E-Puck/arduino/epuck_arduino.zip Arduino IDE (1.6.6) project] for the Arduino Uno board (you'll need the Easy VR Arduino library to build the project). 
A test project that works without any shield is available in the following link [https://projects.gctronic.com/E-Puck/arduino/epuck_arduino_test.zip Arduino IDE (1.6.6) test project], this demo rotates continuously the robot right and left. It works with the same robot firmware as the previous demo. 
We designed a support in order to mechanically attaching the Arduino board on top of the e-puck robot as shown in the following figure. 
[[File:epuck-arduino-support.jpg|350px]]
''Click to enlarge'' 
Here is the [https://projects.gctronic.com/E-Puck/arduino/SuppArduinoONE_V2.STL support 3D model] that you can print with your 3d printer. Alternatively you can purchase an "e-puck arduino set" from the [https://www.gctronic.com/shop.php#e-puck%20accessories shop].

=Known problems=
==Re-flashing the bootloader on e-puck==
In some cases it was reported that the internal bootloader on e-puck was corrupted due to a malfunction of the last code upload. 
In those cases the bootloader ([https://projects.gctronic.com/E-Puck/DemoGCtronic-complete/DemoGCtronic-complete-4bba145+bootloader.hex DemoGCtronic-complete-4bba145+bootloader.hex]) has to be re-flashed on the robot via cable (see figure) with ICD2 or ICD3 and MPLAB IDE or compatible HW and SW. 
See the procedure ([https://projects.gctronic.com/E-Puck/KnownProblems/Instruction-re-program-bootloader-e-puck.pdf Instruction re-program bootloader.pdf]) and in case of need contact info[at]gctronic.com. 
[[File:E-puck_prog_cable1.jpg|400px]] [[File:epuckICDProgConn.png|400px]] 

==Uncorrect/unknown bluetooth PIN code==
In a couple of rare cases it was reported that the PIN code of the Bluetooth chip was not anymore the usual one (same as e-puck number). It seems that
the issue is linked to trials of robot to robot direct communication. One robot could have picked up the PIN of the other one, so you could try that PIN to get access to the robot. Another possibility is to try the default pin number 0000. 
In order to restore the name and pin number of the robot you can either make a program specifically for this purpose (1) or use the standard firmware but you would need the serial cable (2):
# the e-puck library contains the functions to interact with the BT chip and change all its configurations including pin number and friendly name; for a code example refer to the example [https://projects.gctronic.com/E-Puck/DemoBTConfiguration-rev119.zip DemoBTConfiguration.zip], that simply rewrite the pin and friendly name (change only the pin number in the code, the friendly name will be changed accordingly). Another source of insipiration is the [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware Standard_firmware], the part of the code related to selector 11. In case the chip isn't responding be sure it is in ''command mode'' (use the function <code>e_bt_exit_tranparent_mode</code>).
# program the robot with the [https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware Standard_firmware] and put the selector in position 11. Connect the serial cable to the robot as shown in section [https://www.gctronic.com/doc/index.php/E-Puck#Serial_communication Serial_communication] and to the computer (you would need an USB to serial adapter); open the port using this configuration 115200n8. Once the communication channel is opened type the command <code>H+enter</code> to get the help. You can get the serial cable from the [https://www.gctronic.com/shop.php#e-puck%20accessories shop].

==Battery isolation (for battery up to 2012)==
You should be careful when inserting and removing the battery of the e-puck in the robot or in the charger. Otherwise in the long run your battery will eventually lose its front isolator (plastic of cardboard), causing a possible short circuit. If you are already in this situation, you could try placing some isolation tape on the battery, as illustrated in the following figure. The correct procedure to insert and remove the batteries can be found in the following document [https://projects.gctronic.com/E-Puck/docs/CambiareBatte-puck.pdf Change-batteries.pdf]. Basically you need to fully push in the battery compressing the springs before tilting the battery in the final position. 
[[File:Battery.jpg|300px]] 

==Bluetooth and MacBook==
Some users experienced problems in connecting to the robot via Bluetooth using MacBook; using an usb BT dongle solved the problem most of the time. Some users instead experienced distance problems with the internal BT chip of the MacBook, that is the robot should be kept within 1.5 meters otherwise the connection is lost/slows down.

==Memory protection==
The dsPIC processor has the possibility to protect the program memory at various levels through the configuration bits; in principle these protections can be eliminated erasing completely the memory, anyway in some cases it was reported that this procedure fails, leading to a situation in which the "memory protection" still blocks and the robot cannot be programmed anymore. Thus it is advisable to avoid playing with code protection unless strictly necessary. 
In principle the procedure to reset the configuration bits eliminating the protection is:
# Open the MPLAB project and connect the programming cable to the robot
# Select "Programmer => Select Programmer => MPLAB ICD3"
# Select "Programmer => Settings": in the "Program Memory" tab select "Manually select memories and ranges" and check all options, click also on full program memory range
# In the "Power" tab set the voltage to 5.5 V and check the option "Power target circuit from MPLAB ICD 3"
# Select "Programmer => Erase Flash Device"; erase should give no errors
# Power cycle the robot (unplug and plug again the programming cable); now the configuration bits are reset and program memory is cleared completely; it's possible to upload a new program selecting "Programmer => Program"
'''Note that this procedure works only with the ICD3 that is capable of supplying 5V to the processor'''.

==Proximity noise==
It was noticed that the proximity 0 and proximity 7 are subject to noise, in particular the value returned from these two sensors can vary up to 30 (the variation of the others is in the range of 2-3). This noise is coming from the camera clock, thus as a workaround the camera can be turned off if this noise causes problems.

==ICD2 programmer==
The Microchip ICD2 programmer P/N 10-00319 isn't supported on 64-bit OS.

==Upload failed==
If the robot was programmed with a firmware in which the Bluetooth is used to write continuously data to the computer, then you can experience problems in uploading a new firmware to the robot. To solve the problem you should try resetting the robot continuously during the connection to the robot when you are uploading a new firmware, basically you should reset the robot (press and release the button continuously) until the connection led turn on, then stop resetting; with a bit of luck you should be able to upload it.

==Speed precision at very low speed==
The e-puck motors are step motors. To save energy, the motor phases/steps at low speed are not energized all the time but just partially. This might affect the speed precision at speed below 200. If one has specific needs at that low speed and want the single steps to be more energetic, then the <code>TRESHV</code> and <code>MAXV</code> constants in the file <code>\motor_led\advance_one_timer\e_motors.c</code> within the e-puck library need to be adapted (decrease their value). Alternatively the power save feature can be completely disabled by commenting the <code>POWERSAVE</code> constant.

==Mail archive==
You can have a look at a mail archive (February 2007 - December 2016) regarding the e-puck robot from the following link [https://www.mail-archive.com/e-puck-user@gna.org/index.html https://www.mail-archive.com/e-puck-user@gna.org/index.html]. In this archive you can find problems encountered by users and related solutions.

==Bluetooth slowdown in Ubuntu==
If you experience a slowdown using the Bluetooth in Ubuntu try removing the package <code>modemmanager</code> with the following command: <code>sudo apt-get remove modemmanager</code>

=Links=
[https://e-puck.gctronic.com/ https://e-puck.gctronic.com/] 
[https://cyberbotics.com/doc/guide/epuck?version=R2023a https://cyberbotics.com/doc/guide/epuck?version=R2023a] 
[https://mobots.epfl.ch/e-puck.html https://mobots.epfl.ch/e-puck.html] 
[https://github.com/gctronic/e-puck-library https://github.com/gctronic/e-puck-library] 
[https://en.wikipedia.org/wiki/E-puck_mobile_robot https://en.wikipedia.org/wiki/E-puck_mobile_robot] 

=Videos=
{{#ev:youtube|jB0qq7ffQUg}}

File:serial-cable-shop.jpg

2026-04-22T13:05:30Z

WikiSysop:

File:RS232 connector EJumper.gif

2026-04-22T13:05:19Z

WikiSysop:

File:rosgraph-single-robot.png

2026-04-22T13:05:06Z

WikiSysop:

File:roscpp 4robots.png

2026-04-22T13:04:53Z

WikiSysop:

File:roscpp 1robot.png

2026-04-22T13:04:41Z

WikiSysop:

File:Monitor3.0.jpg

2026-04-22T13:04:27Z

WikiSysop:

File:e-puck-snapshot.png

2026-04-22T13:04:14Z

WikiSysop:

File:E-puck-serial-connector.jpg

2026-04-22T13:03:45Z

WikiSysop:

File:epuck-ros-single-robot.png

2026-04-22T13:03:33Z

WikiSysop:

File:e-puck-project-build4.png

2026-04-22T13:02:23Z

WikiSysop:

File:e-puck-project-build3.png

2026-04-22T13:02:11Z

WikiSysop:

File:e-puck-project-build2.png

2026-04-22T13:01:59Z

WikiSysop:

File:e-puck-project-build1.png

2026-04-22T13:01:46Z

WikiSysop: