Overo Extension and e-puck2 robot side development: Difference between pages

From GCtronic wiki
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
This is a mini how-to of the e-puck extension board for the Gumstix Overo COM.
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
=Introduction=
The <code>C programming</code> language is used to develop code for the main microcontroller of the e-puck2 robot. The [http://www.chibios.org ChibiOS] embedded real-time OS was chosen to be integrated in the firmware, since it support the STM32F4 family of microprocessors, it includes an HAL (Hardware Abstraction Layer), it's well documented and finally it's free.<br>
Before starting to code, you need to install the developing environment and its dependencies, all the steps are documented afterwards.<br>
The factory firmware integrates both the e-puck2 library used to handle all the sensors and actuators together with a series of demos that use this library. Thus you can either take the factory firmware and directly modify its main, otherwise you can start a fresh new project by linking the factory firmware project as an external library.<br>
You can also modify the library itself, but before digging into the details, try to contact us, maybe we're already working on that subject or we can help you.
 
=Installation of the e-puck2 environment=
<code>Eclipse_e-puck2</code> is a distribution of Eclipse IDE for C/C++ Developers specially modified to edit and compile e-puck2's projects out of the box. It doesn't require to be installed and everything needed is located in the package given. The only dependency needed to be able to run Eclipse is '''Java'''.
 
==Installation for Windows==
===Java 8 32bits===
This section can be ignored if Java version >= 8 32bits is already installed on your computer.<br>
To verify you already installed Java, you can open <code>Programs and Features</code> from the <code>control panel</code> and search for a <code>AdoptOpenJDK JDK with Hotspot xxx</code> install. If this entry isn't present, then you need to install it:
# Go to [https://adoptopenjdk.net/releases.html OpenJDK download page] and download the <code>OpenJDK 8 (LTS) HotSpot for Windows x86 JDK</code> (take the installer, aka. <code>.msi</code> file).
# Run the downloaded installer and follow its instructions to proceed with the installation of OpenJDK 32bits.
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/openjdk-windows.png <img width=700 src="https://projects.gctronic.com/epuck2/wiki_images/openjdk-windows.png">]</span><br/>
:''OpenJDK download page''


=Minimal getting started=
===Eclipse_e-puck2===
{| style="color:black; background-color:#ffffcc;" cellspacing="0" border="1"
#Download the [https://github.com/e-puck2/Create_Eclipse_e-puck2/releases/download/29_jan_2020/Eclipse_e-puck2_Win32_29_jan_2020.zip Eclipse_e-puck2 package for windows].
|
#Unzip the downloaded file to the location you want (can take time). It is strongly recommended for better performance and less extraction time to use 7Zip. You can download it on http://www.7-zip.org.
# upload the [http://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] to the e-puck robot and put selector in position 10
#You can now run the <code>Eclipse_e-puck2.exe</code> to launch Eclipse.
# connect the USB cable: mini-USB to the extension module and the other side to the PC
#You can create a shortcut to <code>Eclipse_e-puck2.exe</code> and place it anywhere if you want.
# execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
# switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
# login with user=root, password=root
|}


<font style="color:red"> Anyway you're encouraged to read all the documentation since you'll find more detailed explanations. </font>
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png <img width=800 src="https://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png">]</span><br/>
:''Eclipse_e-puck2 folder obtained after extraction''


=Introduction=
'''Important things to avoid :'''
<span class="plainlinks">[http://www.gctronic.com/doc/images/Ext+robot1.jpg <img width=200 src="http://www.gctronic.com/doc/images/Ext+robot1.jpg">]</span> <br/>
:1. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.  
This introductory section explains the minimal procedures needed to work with the Gumstix Overo computer-on-module (COM) mounted on the e-puck extension board and gives a general overview of the available demos and scripts shipped with the micro sd. You can also refer to [http://projects.gctronic.com/Gumstix/extension-instructions.pdf extension-instructions] that is a document containing the most important information in order to start working with the extension. The extension is mostly an interface between the e-puck robot and the Gumstix Overo COM.  
::Example :
::<code>C:\epfl_stuff\Eclipse_e-puck2</code> OK
::<code>C:\epfl stuff\Eclipse_e-puck2</code> NOT OK
:2. You must not put <code>Eclipse_e-puck2</code> folder into <code>Program Files (x86)</code>. Otherwise the compilation when using Eclipse will not work.  
:3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.


Gumstix Overo COM: [http://www.gumstix.com product information] and [http://www.gumstix.org programming information],
===Configuring the PATH variable===
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.


==Full package==
If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
The full package content is:
* e-puck extension with Gumstix Overo COM and micro sd card already inserted
* USB adapter for the micro sd
* A to mini-B USB cable
* USB wifi dongle
* external power adapter
* USB host adapter
The standard COM mounted on the e-puck extension is the Gumstix Overo EarthSTORM COM. Some extensions were delivered with the Gumstix Overo SandSTORM COM, don't worry, the main difference between the two COMs is that the SandSTORM has no flash memory, but the flash isn't necessary since the system is booted from the micro sd.


==Requirements==
<code>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</code>
In order to connect to the extension through the mini 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 visit the following site and download the drivers for your architecture (32 or 64 bits) [http://www.ftdichip.com/Drivers/VCP.htm FTDI drivers].


==General procedure==
What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
The e-puck extension board for the Gumstix Overo COM comes with a pre-configured system ready to run without any additional configuration. The whole system is installed on a micro sd and is composed of:
* U-Boot (bootloader customized for the hardware)
<!--* OMAP35x Linux PSP [https://www-a.ti.com/downloads/sds_support/targetcontent/psp/omap35x/index.html https://www-a.ti.com/downloads/sds_support/targetcontent/psp/omap35x/index.html] (linux kernel) -->
* OMAP35x Linux TI-PSP [http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary] (linux kernel)
* some demos and useful scripts in the /home/root directory
It's important to note that the flash isn't reprogrammed, so it will contain the factory system.


In order to access the system from a PC (console mode), the following steps must be performed:
If you want to set the <code>PATH</code> variable permanently, then go to <code>Control panel</code> => <code>System</code> => <code>Advanced system settings</code> => <code>Environment variables</code>. A list of variables defined for the user is shown, double click on the <code>PATH</code> variable (from the user variables list) and add at the end <code>;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin</code>, then click <code>OK</code> three times.
# connect the USB cable: mini-USB to the extension module and the other side to the PC
# execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
# switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
# login with user=root, password=root


==Wireless setup==
Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
Before proceding with the following configurations be sure that the WiFi dongle is well recognized, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#WiFi_dongle WiFi_dongle].
===Wireless configuration using a script===
The script ''setupWifi'' placed under /home/root/scripts is used to configure easily the wireless network (managed mode) and need to be adapted to your specific situation. The script is shown below:
<pre>
#!/bin/bash
ifconfig wlan0 up
iwconfig wlan0 essid SSID key HEX_KEY
iwconfig wlan0 ap MAC_ADDRESS
iwconfig wlan0 rate 54M
ifconfig wlan0 LOCAL_IP netmask SUBNET_MASK
route add default gw GATEWAY_IP
</pre>
To know the available wifi networks and related information such as mac address of the access point, you can issue the command ''iwlist scanning wlan0''.


On some platforms, udev may rename the network interface ''wlan0.'' In this event, the 'setupWifi' script will return several errors, some of which will say "No Such Device." To identify your network interfaces, use the commands ''ifconfig'' or ''iwconfig.'' These will provide a listing of your devices, and their current states. Identify the appropriate interface (typically ''wlan#'' where "#" is a number) and replace ''wlan0'' in the above script with this.
==Installation for Linux==
===Java 8===
This section can be ignored if Java is already installed on your computer.<br>
To verify whether it is installed or not you can type the following command into a terminal window: <code>update-java-alternatives -l</code>. If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
You need to have <code>Java 1.8.xxxx</code> listed to be able to run <code>Eclipse_e-puck2</code>.


If you're using dhcp, you can instead adapt the script ''setupWifiDhcp'' found under /home/root/scripts:
Type the following commands in a terminal session to install Java SDK:
<pre>
<pre>sudo add-apt-repository ppa:openjdk-r/ppa
#!/bin/bash
sudo apt-get update
ifconfig wlan0 up
sudo apt-get install openjdk-8-jre </pre>
iwconfig wlan0 essid SSID key HEX_KEY
iwconfig wlan0 ap MAC_ADDRESS
iwconfig wlan0 rate 54M
dhclient wlan0
</pre>


The parameters that must be customized are shown in capitals; after that you can execute the script typing ''./setupWifi'' (or ''./setupWifiDhcp'') and after a while a message should be displayed indicating that the wireless is ready. You can test the network configuration using ''ping''.
===Eclipse_e-puck2===
#Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
#Download the Eclipse_e-puck2 package for Linux [https://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz 32bits] / [https://github.com/e-puck2/Create_Eclipse_e-puck2/releases/download/14_aug_2020/Eclipse_e-puck2_Linux64_14_aug_2020.tar.xz 64bits]. Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand <code>uname -a</code> in the terminal window and look for <code>i686</code> (32bit) or <code>x86_64</code> (64 bit). 
#Extract the downloaded file to the location you want (can take time): <code>tar -zxvf package_name.tar.gz</code>
#You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.


It may be necessary to create a directory if you get the error "can't create /var/lib/dhcp/dhclient.leases: No such file or directory." Use the ''mkdir'' command
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png <img width=800 src="https://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png">]</span><br/>
:''Eclipse_e-puck2 folder obtained after extraction''


<pre>
Note : The icon of the <code>Eclipse_e-puck2</code> executable will appear after the first launch of the program.
mkdir /var/lib/dhcp
</pre>


Usually, when the Wifi dongle is connected to the AP, a message is written in the message buffer of the kernel. The following bash code snippet can be used to make sure that the connection is well established when the program returns:
'''Important things to avoid :'''
<pre>
:1. You cannot create a Link to the <code>Eclipse_e-puck2</code> executable because otherwise the program will think its location is where the Link is and it will not find the resources located in the <code>Eclipse_e-puck2</code> folder.
#!/bin/bash
:2. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.
echo Wait until the Wifi is connected to the AP
::Example :
while true
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
do
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
  #the text "link becomes ready" can vary according the Wifi dongle
:3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.
  a=$(dmesg | grep wlan0 | grep "link becomes ready")
  if [ -n "$a" ]
  then
    echo Wifi enabled!
    exit
  fi
  sleep 1
done
</pre>


In order for the ''setupWifi'' or ''setupWifiDhcp'' scripts to be run during boot, copy the appropriate script into the ''init.d'' directory with the other start/stop scripts.
===Configuring the PATH variable===
<pre>
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
cp -i ~/scripts/setupWifi /etc/init.d/setupWifi
</pre>
Then determine which run level the system is using with the command:
<pre>
runlevel
</pre>
This should return "N #" where # is the run level number. Create a link to your script in the ''init.d'' directory within the directory ''/etc/rc#.d'' Name the link ''S##setupWifi.'' The number ## (customarily 2 digits, which you choose) determines where in the startup sequence your script will be run. It is good advice to choose a number just smaller than the largest in the ''rc#.d'' directory, this way the script is not called before lower-level ones. The creation of this link can be done with the following command (where # and ## must be changed to their appropriate values).
<pre>
ln -i -s /etc/init.d/setupWifi /etc/rc#.d/S##setupWifi
</pre>


===Wireless configuration using a wpa_supplicant===
If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
Alternativerly, the Wifi connection can be set up by using both [http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant] and the native wifi setup. This has the advantage to be more robust against failure. In order to do that, the Wifi interface can be added to /etc/network/interfaces, this way:
<pre>
auto wlan0
iface wlan0 inet static
address 192.168.1.2
netmask 255.255.255.0
wpa-conf /path/to/wifi.conf #this should be replaced by the absolute location of wifi.conf
</pre>


And the related wifi.conf
<code>export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
<pre>
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
ap_scan=1
network={
  ssid="myssid" #this should be replaced by your ssid
  scan_ssid=1
  key_mgmt=NONE
  wep_key0=1234567890 #this should be replaced by your WEP key
  wep_tx_keyidx=0
}
</pre>


In this example, static IPs and WEP encryption have been used. DHCP and other encryption can be obviously used by following the documentation both of the linux native network setup and of [http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant].
What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.


===Network performance===
If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.profile</code> file by issuing the command:<br>
To test the network performance you could use the ''iperf'' tool installed on the system. In the server side you must issue the following command (either for TCP or UDP testing), after which the server machine is listening for incoming data:
<code>echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile</code><br>
<pre>
Close and reopen the terminal before using your newly set environment variable.
iperf -s      [TCP]
iperf -s -u  [UDP]
</pre>
In the client side you must type:
<pre>
iperf -c SERVER-IP                  [TCP]
iperf -c SERBER-IP -u -b 50000000    [UDP]
</pre>
Where ''SERVER-IP'' must be changed accordingly to the network configuration.


==Package manager==
Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
If you have an internet connection up and running you can update and install easily new packages with ''opkg''. Some of the useful operations you could do are:
* update repositories: <code>opkg update</code>
* update installed packages and kernel; pay attention that the camera driver is based on the provided kernel and upgrading it will prevent the use of the camera: <code>opkg upgrade</code>
* list of software currently installed on the machine: <code>opkg list_installed</code>
* install a new package (perl in the example): <code>opkg install perl</code>
* remove a pacakge (perl in the example): <code>opkg remove perl</code>
* list of all packages available to be installed: <code>opkg list</code>


===opkg update failed===
==Installation for Mac==
If you get errors on reaching the default repo sources you can try changing them by following these steps:
===Command Line Tools ===
# make a copy of the current repo: <code>mv /etc/opkg/base-feed.conf /dest-dir</code>
To compile on Mac with <code>Eclipse_e-puck2</code>, it is necessary to have the <code>Command Line Tools</code> installed. It is a bundle of many commonly used tools.<br>
# add the new repo: <code>echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base' > /etc/opkg/base-feed.conf</code>
You can install it by typing the following command in a terminal window: <code>xcode-select --install</code>. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.
# opkg update
The procedure shows how to change the <code>base</code> repo, the same need to be done for all others repos.


==USB ports==
===Java 8===
The e-puck extension board for the Gumstix Overo COM comes with two USB interfaces called USB host and USB otg. If you try inserting devices that require more energy than the one permitted on the otg, the device will not be enabled automatically. In these cases you can use the three scripts ''usbup'', ''usbdown'' and ''usbenable'' to respectively power up, power down and enable the USB device; they're placed under /home/root/scripts. These scripts are intended for primary use with the USB otg port, even if they're suitable for both ports (otg and host).
This section can be ignored if Java is already installed on your computer.<br>
* ''./usbup otg'' (or ''./usbup host''): power on the usb device
To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac: <code>/usr/libexec/java_home -V</code><br>
* ''./usbdown otg'' (or ''./usbdown host''): power off the usb device
You need to have <code>AdoptOpenJDK 8</code> listed to be able to run <code>Eclipse_e-puck2</code>.
* ''./usbenable otg'' (or ''./usbenable host''): activate the usb device (now is in the usb device list)


==Demos==
# Go to [https://adoptopenjdk.net/releases.html OpenJDK download page] and download the <code>OpenJDK 8 (LTS) HotSpot for MacOS x64 JDK</code> (take the installer, aka. <code>.pkg</code> file).
A specific firmware must be charged on the e-puck to run the Gumstix Overo linked demos, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#E-puck_firmware E-puck firmware].
# Open the <code>.pkg</code> file downloaded and follow the instructions to proceed with the installation of OpenJDK.
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/openjdk-mac.png <img width=700 src="https://projects.gctronic.com/epuck2/wiki_images/openjdk-mac.png">]</span><br/>
:''OpenJDK download page''


===Serial test on the Gumstix Overo COM===
===Eclipse_e-puck2===
This small program read and write from a serial port (non-canonical mode). For more information on the usage refers to [http://docwiki.gumstix.org/index.php?title=Sample_code/C/Serial sertest] ([http://projects.gctronic.com/Gumstix/sertest.tar.gz sertest sources]). It's placed under /home/root/demos/gumstix-common, and it's called ''sertest''.
:1. Download the [https://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_03.21.dmg Eclipse_e-puck2 package for Mac].
:2. Open the <code>.dmg</code> file downloaded (confirm opening if a warning message appear) and ''drag and drop'' the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder
::Note: you can place the <code>Eclipse_e-puck2.app</code> anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in <code>Applications</code>.
:3. You can create an Alias to <code>Eclipse_e-puck2.app</code> and place it anywhere if you want.


===Advanced sercom===
===First launch and Gatekeeper===
Once the new firmware is running on the e-puck, the selector must be set in position 10 to run the advanced sercom for the Gumstix Overo. <br/>
It’s very likely that <code>Gatekeeper</code> (one of the protections of Mac OS) will prevent you to launch <code>Eclipse_e-puck2.app</code> because it isn’t signed from a known developer.<br>
Now you can type (after being in /home/root/demos/gumstix-common) ''./sertest -p /dev/ttyS0 -b 230400'' (or simply ''./ser+ENTER'') to enter the e-puck menu in console mode; for a list of all available commands type ''h+ENTER''. After stopping the sertest program (CTRL+C), the display may not respond correctly; to reset the display run the script ''r'' by simply typing ''./r+ENTER''. Now the display should behave normally.<br/>
If you can’t run the program because of a warning of the system, press <code>OK</code> and try to launch it by right clicking on it and choosing <code>open</code> in the contextual menu (may be slow to open the first time).<br>
For more information about the advanced sercom refer to the page [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol Advanced sercom protocol].
If <code>Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.</code> or if <code>"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.</code> appears after executing the app the first time, it is needed to disable temporarily <code>Gatekeeper</code>.


===Images grabbing (camera driver)===
To do so :
<!-- A small utility called ''v4l2grab'' was used for grabbing JPEGs from V4L2 devices ([http://github.com/twam/v4l2grab http://github.com/twam/v4l2grab]). <br/>
In order to get an image from the e-puck camera you need to follow these steps:
# load the driver typing (after being in /home/root/demos) ''insmod po6030cam.ko po6030_format=1''; a message should be displayed indicating that the camera is successfully detected
# run the program typing (after being in /home/root/demos) ''./v4l2grab -o image.jpg''
For more information on the options available refer to ''./v4l2grab -h''.
-->
A small application called ''v4l2grab'' ([http://projects.gctronic.com/Gumstix/v4l2grab-2buff-rev17-13.08.14.zip v4l2grab.zip]) based on [http://github.com/twam/v4l2grab http://github.com/twam/v4l2grab] was used for grabbing JPEGs from V4L2 devices. In order to get an image from the e-puck camera you need to run the program typing (after being in <code>/home/root/demos/gumstix-common/</code>) <code>./v4l2grab -o image.jpg</code>. The application communicates also with the robot through the serial line to know the camera orientation and rotates the image automatically in case the camera is rotated (refer to section [http://www.gctronic.com/doc/index.php/E-Puck#Camera e-puck camera] for more information on camera orientation).
For more information on the options available refer to the help by typing<code>./v4l2grab -h</code>.


===Images transfer (camera driver)===
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
This demo is divided in two parts: one running on the e-puck extension board for the Gumstix Overo COM that continuously request images to the e-puck camera and transfers them over UDP, and the other running on a PC that acts as a server and is listening for the images visualizing them as soon as they are available. A network link must be established between the two in order to run this demo; for more information on how to configure the network refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Wireless_setup Wireless setup].


First of all you need to start the server ([http://projects.gctronic.com/Gumstix/Receiver.zip Receiver QT project]). The application is a Qt project, so the compilation may be handled easily with [https://wiki.qt.io/Category:Tools::QtCreator Qt Creator]; alternatively [http://doc.qt.io/qt-5/qmake-manual.html qmake] can be used. The usage is very simple: the server listening port and the protocol (only UDP available at the moment) must be selected first, then click on the button ''Connect''; at this moment the application is waiting images.<br/>
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png">]</span><br/>
On the e-puck extension board side, you need to run the program typing (after being in /home/root/demos) ''./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0''. ''SERVER_IP'' is the address of the PC and ''SERVER_PORT'' should be the same as configured when the receiver was started. The ''f'' option indicates the format (in this case RGB) and ''t'' indicates the transfer mode (0=UDP, 1=TCP).
::''Security settings of Mac OS''
<!--
On the e-puck extension board side, you need to follow these steps:
# load the driver typing (after being in /home/root/demos) ''insmod po6030cam.ko po6030_format=0''; a message should be displayed indicating that the camera is successfully detected
# run the program typing (after being in /home/root/demos) ''./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0''. ''SERVER_IP'' is the address of the PC and ''SERVER_PORT'' should be the same as configured when the receiver was started. The ''f'' option indicates the format (in this case RGB) and ''t'' indicates the transfer mode (0=UDP, 1=TCP but still not available).
-->
For more information on the options available refer to ''./v4l2grab-send -h''. <br/>
The sources for the sender, that is an extension of the ''v4l2grab'' application, could be found in the following link [http://projects.gctronic.com/Gumstix/v4l2grab-send.zip v4l2grab-send.zip]; in order to compile the application the ''Makefile'' must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to [http://focus.ti.com/docs/prod/folders/print/omap3503.html http://focus.ti.com/docs/prod/folders/print/omap3503.html]).


===Music player===
::If you are on Mac OS Sierra or greater (greater or equal to Mac OS 10.12), you must type the following command on the terminal to make the option above appear.
This isn't really a demo, it's only one of the possible way on how to listen something from the extension module. The system comes with a tool called [http://www.mplayerhq.hu/ mplayer] that supports many multimedia formats. You can use it to play for example an mp3 file in this way:
::<code>sudo spctl --master-disable</code>
<pre>
:2. Now you can try to run the application and it should work.
mplayer file.mp3
:3. If Eclipse opened successfully, it is time to reactivate <code>Gatekeeper</code>. Simply set back the setting of <code>Gatekeeper</code>.
</pre>
::For the ones who needed to type a command to disable <code>Gatekeeper</code>, here is the command to reactivate it.
You can then adjust the volume with either the ''alsamixer'' graphical tool (adjusting DAC2 control) or using the command line tool ''amixer''; the following command can be used for instance to set the volume to 80%:
::<code>sudo spctl --master-enable</code>
<pre>
amixer set 'DAC2 Analog' 80%
</pre>


==File transfer==
This procedure is only needed the first time. After that <code>Gatekeeper</code> will remember your choice to let run this application and will not bother you anymore, as long as you use this application. If you re-download it, you will have to redo the procedure for <code>Gatekeeper</code>.
===ssh===
The e-puck extension board for the Gumstix Overo COM supports ssh connections through dropbear (small SSH 2 server and client) that is installed on the system.<br/>
To exchange file between the module and the PC, the ''scp'' tool (secure copy) will be used; the general command is the following:
<pre>
scp user@ip:path-to-file file-name
</pre>
As an example of transfer a file from the PC to the extension, let the PC user be ''stefano'' and its IP be 192.168.1.10, then the command will be:
<pre>
scp stefano@192.168.1.10:/home/stefano/file-to-send prova
</pre>
The file ''file-to-send'' will be renamed in ''prova'' and placed in the current directory.


If you are working in Windows you can use [http://winscp.net WinSCP] to exchange data between the robot and the computer.
'''Important things to avoid :'''
:1. The path to the <code>Eclipse_e-puck2.app</code> must contain zero space.
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
:2. The file’s structure in the <code>Eclipse_e-puck2.app</code> must remain the same. It means no file inside this app must be moved to another place.


===zmodem===
===Configuring the PATH variable===
The following instructions to exchange data between the extension and the computer refer to ''minicom'' as the terminal.<br/>
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
If you want to receive a file, that is transfer a file from the PC to the e-puck extension board for the Gumstix Overo COM, you need to follow these steps:
# open a terminal window with minicom; now you access the linux system in console mode
# type ''lrz''
# press ''CTRL+A'' and then ''S''
# select ''zmodem'' and navigate to find the file you want to tranfer
# select the file with the ''SPACEBAR'' and then press ''ENTER'' to start the transfer
# when transfer is complete press ''ENTER'' once more to come back to the command line
For more information type ''lrz -h''.


If you want to send a file, that is transfer a file from the e-puck extension board to the PC, you need to follow these steps:
If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
# open a terminal window with minicom; now you access the linux system in console mode
# type ''lsz file-name'', where ''file-name'' is the file you want to transfer
# when transfer is complete press ''ENTER'' to return to the command line
The file will be placed in the directory where minicom is started. For more information type ''lsz -h''.


==Extension LEDs==
<code>export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
The e-puck extension board for the Gumstix Overo COM comprises 8 new small leds that can be turned on/off easily from the file system in this way:
<pre>
echo 1 > /sys/class/gpio/gpio7x/value  [turn on]
echo 0 > /sys/class/gpio/gpio7x/value  [turn off]
</pre>
where x ranges from 0 to 7. For more information on gpio refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode GPIO - pins mode].


==File system image==
If you put the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder then the exact command would be:
You can download the entire system running on the micro sd released with the e-puck extension board from the following links: [http://projects.gctronic.com/Gumstix/epuck-overo-e2fs-12.08.14.tar.gz file system] and [http://projects.gctronic.com/Gumstix/epuck-overo-fat-30.03.15.tar.gz FAT] (with camera driver 1.3). <br/>
In order to prepare the micro sd you can use a script ([http://projects.gctronic.com/Gumstix/prepareMicroSD.sh prepareMicroSD.sh]), in which you need only to specify where to find the two previously downloaded files and run it (''./prepareMicroSD.sh /path/to/dev'') to have your micro sd ready to be used. Alternatively you can have a look the gumstix documentation on how to [https://www.gumstix.com/support/getting-started/create-bootable-microsd-card/ create a bootable microsd card].<br/>
<!--
<font style="color:red"> A new camera driver release (1.1) is available, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#Camera_driver Camera driver] for information on how to update the system</font>. <br/>
-->
If you experience problems in booting from mmc enter u-boot and issue the following command:
<pre>
nand erase 240000 20000
reset
</pre>
Moreover if you need you can find pre-built images for the Gumstix Overo in the following link: [http://gumstix.org/download-prebuilt-images.html http://gumstix.org/download-prebuilt-images.html].
===Sources===
The complete kernel sources (comprising the camera driver) can be downloaded from the following link [http://projects.gctronic.com/Gumstix/gctronic-ti-psp-omap-2.6.32-12.08.14.zip gctronic-ti-psp-omap-2.6.32-12.08.14.zip] if you want to try to build it your own (anyway you don't need to do it because the released micro SD is ready to run with this system). The system is based on:
<!--* [http://www.sakoman.com/feeds/omap3/glibc/images/overo/201005041130/ sakoman's pre-built file system image]-->
* sakoman's pre-built file system image
* [http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary ti-psp-2.6.32 kernel]


===Camera driver===
<code>export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
The driver of the camera is open-source, you can download the code in the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Sources kernel source]. The driver is located in <code>/ti-psp-omap/drivers/media/video/po6030cam.c</code>; related ISP code is located in <code>/ti-psp-omap/drivers/media/video/isp</code>.
====Release notes====
:1.0
* support for PO6030 camera (front e-puck camera or camera of omnicam module version 1)
* support for RGB565 output format
* only 640x480 resolution images
:1.1
* added support for PO3030 camera
* added support for YUV422 output format
* brightness, contrast, saturation, auto-white balance, red gain, blue gain controls available
:1.2
* exposure control available
* support for 480x480 color and greyscale images
:1.3
* added support for PO8030 camera


====System update====
What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
In order to update the system released in the micro sd with the new driver you need to download the kernel modules from [http://projects.gctronic.com/Gumstix/driver-update/1.3/linux-2.6.32.tar.gz linux-2.6.32.tar.gz] and the kernel image from
[http://projects.gctronic.com/Gumstix/driver-update/1.3/uImage uImage]. Then:
# insert the micro sd in the computer; two partitions will be recognized
# copy the kernel image (uImage) in the FAT partition
# extract the kernel modules in the second partition:
## cd path/to/partition
## sudo tar zxvf path/to/kernel-modules
# unmount the micro sd from the computer and insert it in the extension; at first boot type ''depmod -a'' and reboot


==Daemon==
If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.bash_profile</code> file by issuing the command:<br>
It can be useful to start a daemon at the end of the boot process in order to run your own program at the start up of the e-puck (when the console mode won't be accessible). This can be done by placing your program executable into ''/etc/init.d'' and then:
<code>echo 'export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.bash_profile</code><br>
<pre>
Close and reopen the terminal before using your newly set environment variable.
cp /path/to/your/executable /usr/sbin/mainProgram
cd /etc/init.d
update-rc.d mainProgram defaults 99
</pre>


The daemon can be removed by removing these files:
Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
<pre>
rm /etc/rc*/*mainProgram*
</pre>


Remember to give execution permission to the program by typing <code>chmod +x mainProgram</code>.
=Get the source code=
The code of the e-puck2 is open source and is available as a git repository. To download the source code you need to install git on your system:
* Windows: downlaod git from [https://gitforwindows.org/ https://gitforwindows.org/] and follow the installation instructions (default configuration is ok)
* Linux: issue the command <code>sudo apt-get install git</code>
* Mac: issue the command <code>brew install git</code>


=Hardware=
The source code can downloaded with the command:  <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
The following figure shows the main components offered by the e-puck extension for the Gumstix Overo COM and their interconnection with the e-puck robot and the Gumstix Overo COM.<br/>
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-schema.jpg <img width=600 src="http://www.gctronic.com/doc/images/Gumstix-schema.jpg">]</span> <br/>
In particular there are:
* a Gumstix Overo COMs: compatible with all Gumstix Overo COM models. The communication between the Gumstix Overo COM (OMAP 35xx) and the e-puck (dsPIC) is handled with a serial line at 230400 baud
* a mini-usb connector (console) used to enter the linux system through a terminal
* one usb otg and one usb host: these two connectors are really useful to connect whatever peripheral you need, like a WiFi dongle or simply a pen drive to extend the memory
* a speaker ([http://projects.gctronic.com/Gumstix/datasheet-speaker.pdf speaker specification]): with Linux running on the Gumstix Overo COM, it's really easy play any audio format you need or implement a speech synthesizer. If the user prefer to have the speaker on the extension linked to the e-puck processor, it can simply be done changing two small resistors
* 8 LEDs: have you ever seen a board without leds?! Anyway they are completely controllable through GPIO lines (gpio70-gpio77), for detailed information refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode GPIO - pins mode]
* an I2C connector (@5 V)
* a rotary selector: one could choose what program is running on the e-puck based on the selector position
* 2 long range infrared proximity sensors ([http://projects.gctronic.com/Gumstix/datasheet-long-range.pdf long range specification]) <!-- , up to 15-20 cm -->
* the PixelPlus PO6030 camera remains mounted on the robot, but you could receive image from it by using the OMAP ISP (Camera Interface Subsystem); this way we can receive up to 18 frames per second (VGA color images)


The following figure illustrates where the components are physically placed on the e-puck extension board for the Gumstix Overo COM. <br/>
This repository contains the main microcontroller factory firmware together with the e-puck2 library. This library includes all the functions needed to interact with the robot's sensors and actuators; the factory firmware shows how to use these functions.<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-schema2.jpg <img width=600 src="http://www.gctronic.com/doc/images/Gumstix-schema2.jpg">]</span> <br/>


==Electrical schema==
A snapshot of the repository can be downloaded from [https://projects.gctronic.com/epuck2/e-puck2_main-processor_snapshot_17.03.20_1f56587.zip e-puck2_main-processor_snapshot_17.03.20.zip].<br/>
The circuit diagram of the e-puck extension for Gumstix Overo COM is available to the community on the following link [http://projects.gctronic.com/Gumstix/GC_EXT5_V3.pdf electrical schema].


==Long range proximity sensors==
=Creating a project=
The following chart illustrates the long range proximity sensors response towards a white surface. These results should be considered indicative.<br/>
==Main microcontroller factory firmware project==
<span class="plainlinks">[http://www.gctronic.com/doc/images/IR-characterization.jpg <img width=400 src="http://www.gctronic.com/doc/images/IR-characterization.jpg">]</span>
If you want to modify the code of the factory firmware running on the main microcontroller, or if you want to have a look at the implementation details, then you can add this project in Eclipse by following the next steps:<br/>
:1 Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-dev3-1.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-dev3-1_small.png">]</span><br/>
:2 Next click on the <code>Browse</code> button and choose the project folder of the git repository downloaded previously (should be named <code>e-puck2_main-processor</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
:3 Click on the <code>Finish</code> button and the project is added to Eclipse.
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-dev3-2.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-dev3-2_small.png">]</span><br/>
:4 Build the project by selecting one directory of the project from the left panel and then <code>Project->Build Project</code>.


A zoom in the bigger distances shows that the values returned from the sensors are still usable to react to obstacles.
==Project template==
The main microcontroller factory firmware project can also be used as a library to build your own project on top of it.<br>


<chart width="600" height="300" legend_title="Legend" x_type="length" x_unit="cm" x_title="Distance" y_type="general" y_unit="ADC value" y_title="Prox">
To accomplish that, you have to copy the folder <code>Project_template</code>, contained in the <code>e-puck2_main-processor</code> project, and place it in the same directory of the <code>e-puck2_main-processor</code> project; you can of course rename the folder to the name you want (e.g. <code>myproject</code>). You must end up with the following directory tree:<br>
Prox;14;203
* e-puck2
Prox;16;154
** e-puck2_main-processor
Prox;18;128
** myproject
Prox;20;105
Prox;22;88
Prox;24;78
Prox;26;70
</chart>


==WiFi dongle==
Then you can add this project in Eclipse by following the next steps:
===Zyxel===
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
The WiFi dongle shipped with the extension board for the Gumstix Overo COM is a ZyXEL NWD271N USB adapter, 802.11n compatible. It's based on an Atheros chipset, for more infromation about the linux driver visit the following site [http://linuxwireless.org/en/users/Drivers/ar9170 http://linuxwireless.org/en/users/Drivers/ar9170]. <br/>
# Next click on the <code>Browse</code> button and choose the project folder of your project (e.g. <code>myproject</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
The measured throughput with the e-puck extension and provided wifi dongle is '''20 Mb/s'''. <br/>
# Click on the <code>Finish</code> button and the project is added to Eclipse.
The consumption of the wifi dongle is 100 mA in standby and 300 mA when active.
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
<!--During prototyping another WiFi dongle was used, the Trendnet -->
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
##Select the project root folder and go to <code>File->New->Folder</code>.
##Check <code>Advanced >></code> on the bottom.
##Choose <code>Link to alternate location (Linked Folder)</code>.
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).


===Edimax===
Now you can write your own program. If you want to add source files (<code>.c</code>) to the project you need to add them also in the <code>makefile</code>, in the <code>CSRC</code> definition. All the headers files (<code>.h</code>) located next to the <code>makefile</code> are automatically included in the compilation, but if you need to place them into folders, you have to specify these folders in the <code>makefile</code>, in the <code>INCDIR</code> definition. The same is needed for any desired <code>.h</code> files from other external folders.<br/>
A new WiFi dongle is shipped starting from January 2012, it is the Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu).  
In the <code>makefile</code> you can also set the name of your project.<br/>
The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it:
This <code>makefile</code> uses the main makefile of the <code>e-puck2_main-processor</code> project. This means you can add custom commands to the <code>makefile</code> but it should not interfere with the main makefile.
# turn on the robot and login with <code>user=root, password=root</code>
# only needed if the wifi dongle is connected to the USB OTG: type <code>./scripts/gumstix-common/usbenable otg</code>. Don't worry about the warning <code>usb 1-1: new config #1 exceeds power limit by 400mA</code>
# type <code>insmod 8192cu.ko</code> (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created
# type <code>ifconfig wlanX up</code> (where X is a number) to turn on the device; now the wifi can be configured and used normally
The following figures show how the device is mounted on the extension: on the left the WiFi dongle is connected to the USB HOST connector (pay attention to the position on the connector), on the right the WiFi dongle is connected to the USB OTG (this is needed when using an [http://www.gctronic.com/doc/index.php/Omnivision_Module_V2 omnivsion extension]):<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-nano-wifi.jpg <img width=400 src="http://www.gctronic.com/doc/images/Gumstix-nano-wifi.jpg">]</span>  
<span class="plainlinks">[http://www.gctronic.com/doc/images/edimax-otg.jpg <img width=350 src="http://www.gctronic.com/doc/images/edimax-otg-small.jpg">]</span> <br/>


==Consumption==
=Configuring the Debugger's settings=
The consumption of the robot and extension is 300 mA; with the Zyxel wifi dongle inserted (standby) the consumption goes up to 400 mA; when the wifi dongle becomes active, the consumption reaches 700 mA. If the wifi isn't used it can be turned off completely using the usb scripts [http://www.gctronic.com/doc/index.php/Overo_Extension#USB_ports http://www.gctronic.com/doc/index.php/Overo_Extension#USB_ports].
<code>Eclipse_e-puck2</code> contains everything needed to compile, program and debug the e-puck2.<br>
The only settings to configure with a new project are located under the <code>Debug Configurations</code> icon of Eclipse (you can also find it on <code>Run->Debug Configurations</code>).  
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png <img width=231 src="https://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png">]</span><br/>
Once in the settings, select <code>Generic Blackmagic Probe</code> preset on the left panel. Then you need to configure two things :


Two different tests were performed to provide an estimation of the duration of the battery:
# In the <code>main</code> tab, select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse should have indexed the binaries and you can list the project and the compiled files using respectively the <code>Browse...</code> and <code>Search Project...</code> buttons.<br/> If nothing is appearing when you press <code>Search Project...</code> then you must enter the <code>.elf</code> file name by hand, which can be found in your project <code>build</code> folder (e.g. <code>build/e-puck2_main-processor.elf</code>).
# e-puck and gumstix active (gumstix sends commands via serial to robot; movement every 3s lasting 1s at 30% of maximum speed): '''3h and 30 minutes'''
# In the <code>Startup</code> tab, you need to replace the serial port name written on the first line of the text box by the one used by the GDB Server of your robot. [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used See how to find it].
# e-puck, gumstix and wifi active (same as above, moreover wifi active all the time with continuous ping): '''1h and 25 minutes'''
:* For Windows, it will be <code>\\.\COMX</code>, <code>X</code> being the port number.
:* For Linux, it will be <code>/dev/ttyACMX</code>, <code>X</code> being the port number
:* For Mac, it will be <code>/dev/cu.usbmodemXXXXX</code>, <code>XXXXX</code> being the port number.
:* You can also type <code>${COM_PORT}</code> instead of the com port in order to use the variable <code>COM_PORT</code> for the debug configuration.<br>To change the value of this variable, go to the <code>main</code> tab again, click on the <code>Variables...</code> button and click on the <code>Edit Variables...</code> button. The opened window will let you edit the value of the variable.<br>Using the variable <code>COM_PORT</code> instead of the real com port in a debug configuration is useful if for example you have multiple debug configurations. If for some reason you need to change the serial port to use, then you can simply edit the variable <code>COM_PORT</code> instead of editing the serial port for each debug configuration.


==External power==
If you want to debug another project, you can duplicate this settings and change the relevant parts (project name and path to compiled file) in order to have one launch configuration for each project.<br/>
In the package you'll find also an external power adapter that will be useful during development of your applications. As power supply you could use the one of the e-puck battery charger. The following figure shows the power supply cable, the external power cable and the extension.<br/>
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug.jpg <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug-small.jpg">]</span><br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/External-power.jpg <img width=400 src="http://www.gctronic.com/doc/images/External-power.jpg">]</span> <br/>
You need to simply attach the power supply in one side, and the other side of the external power cable on top of the extension (near the USB plug). Once the cable is connected a green led should turn on indicating that the extension is running. <br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/External-power-attached.jpg <img width=400 src="http://www.gctronic.com/doc/images/External-power-attached.jpg">]</span> <br/>
The external power cable could also be plugged in when the extension is mounted on the e-puck, but '''<font style="color:red"> pay attention to not turn on the robot when the external cable supplies the energy, otherwise there could be serious damages of the devices and the battery</font>'''.


==3.3V and 5V source==
Now you should be able to use the debugger with Eclipse.
The 3.3 V comes from the e-puck robot and the 5V comes from the gumstix extension. The gumstix extension can be used alone (without the robot attached to it) but some things are related to the 3.3 V thus without the robot connected they will not work; an example are the RGB leds of the omnivion module, that need the robot to be connected to the extension in order to be used.


=Software=
Notice that the settings are saved in the project folder in a file with extension <code>.launch</code>. If you want, you can rename this file (e.g. <code>Debug_project_template.launch</code>) with the name you want for the debug configuration of your project.
==E-puck firmware==
<!-- The firmware that has to be uploaded on the e-puck when working with the extension for Gumstix Overo COM can be downloaded from [http://projects.gctronic.com/E-Puck/DemoGCtronic-gumstix/DemoGCtronic-gumstix.hex hex]; the related MPLAB project can also be downloaded from [http://projects.gctronic.com/E-Puck/DemoGCtronic-gumstix/DemoGCtronic-gumstix.zip MPLAB project]. -->
Refers to the section [http://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware E-Puck Standard firmware] for the firmware that need to be uploaded to the robot.
Essentially in this firmware a new version of the ''advanced sercom'' is included (selector position 10) in which the bluetooth communication is replaced by the serial line communication, running at 230400 between robot and gumstix. Moreover the I2C is disabled temporary from the dsPIC side (the dsPIC cannot communicate through I2C) in order to avoid conflicts. As a last note, the body led and front led aren't anymore usable with the extension due to the two extra long range proximity sensors and for power saving purposes the motors are configured to the minimum energy consumption during movement.<br/>
The values of the two extra proximity sensors can be retrieved with the command ''N'' in the ''advanced sercom'' (selector position 10); the last two values returned by the command refer to these proximity sensors (the others values refer to the proximity sensors mounted on the e-puck as usual).


===Project building===
=Running a debugging session=
Refer to section [http://www.gctronic.com/doc/index.php/E-Puck#Project_building Project building] for information on how to build the project for the e-puck firmware.
Once the debugger is configured, you can start a debugging session. When starting a session, the robot is programmed with the current developed program, thus starting a debugging session means also updating the main microcontroller firmware. This is in fact the way to update the firwmare via Eclipse; to do it manually refer to the section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update].


==Cross compilation==
To start a session follow the next steps:
If you want to develop some applications that will run on the gumstix you need to firstly download the toolchain.
# Connect the robot to the computer and turn it on
# From Eclipse, launch the debug configuration previously set: from the menu <code>Run->Debug configurations...</code>, select the configuration and click on the <code>Debug</code> button.<br>Alternatively you can directly select your configuration from the debugger drop-down menu.<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png <img width=350 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png">]</span><br/>
# When the debugging session is started, Eclipse will change the view to the <code>Debug perspective</code>. Right-click on the main process and select <code>Restart</code> to restart the program from the beginning<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3-small.png">]</span>
# Click on the <code>Resume</code> button on top of the window to start your program. Now you can suspend and resume whenever you want, then when you want to modify your code again you click on the <code>Terminate</code> button and click on the <code>C/C++ perspective</code> button.<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4-small.png">]</span>


If you're using Ubuntu you can simply type <code>sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi</code> to install the required toolchain (have a look at [http://www.gumstix.org/basic-cross-compilation.html http://www.gumstix.org/basic-cross-compilation.html] and [http://wiki.gumstix.org/index.php?title=Toolchain http://wiki.gumstix.org/index.php?title=Toolchain] for more information).
==Adding breakpoints==


Alternatively when you need to handle external dependencies is better using the toolchain integrated in OpenEmbedded (${OVEROTOP}/tmp/cross or ${OVEROTOP}/tmp/sysroots/i686-linux/usr/armv7a/bin/ with recent version) if you have it in your system. For more information refers to the [http://wiki.gumstix.org/index.php?title=Category:How_to_-_OpenEmbedded gumstix wiki].<br/>
==Watch variables==


For other linux systems you can find a toolchain in the following link [http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/ http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/] (30 days trial); this toolchain is useful for small programs:
==Analyze microcontroller registers content==
# download the Lite Edition, you'll have a file named something like ''arm-2009q3-67-arm-none-linux-gnueabi.bin''
When a debugging session is started, the microcontroller's registers state can be inspected by clicking on the <code>EmbSys Registers</code> tab on the top right side of the <code>Debug perspective</code>.
# open a terminal, go to the directory of the file, type ''chmod +x arm-2009q3-67-arm-none-linux-gnueabi.bin'', after execute the file ''./arm-2009q3-67-arm-none-linux-gnueabi.bin'' to start the installation
<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug5.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug5-small.png">]</span>
# follow the installation steps; you have to choose where to install the toolchain, this is the path you will specify in the makefile


Once a toolchain is installed in the system the process will be simply something like this:
==Bluetooth debugging session==
# develop your application as you do normally in your developing machine
It is possible to run a debugging session remotely thorugh Bluetooth following these steps:
# cross-compile in your developing machine using the tools previously downloaded
# change the programmer's mode to <code>mode 1</code> with the command <code>monitor select_mode 1</code>, for more informations refer to [https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development e-puck2 programmer development], chapter <code>Configuring the Programmer's settings</code>
# copy the executable in the extension's micro SD and run it
# pair the robot with the computer
You can download the [http://projects.gctronic.com/Gumstix/helloworld.zip hello world example] containing a makefile in which you have to specify the path to the toolchain you previously installed in order to build the program; you can use it for others programs.<br/>
# in the debugger's settings, setup the port with the <code>Bluetooth channel 1, GDB port</code> name, for more informations refer to [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth]
Refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#Demos http://www.gctronic.com/doc/index.php/Overo_Extension#Demos] for some application examples.
# start the debugging session and the Bluetooth connection will be established automatically; now you can program/debug the robot remotely


Of course you can also install the compiler directly on the embedded system and build the applications from it, but the process will take longer due to limited computational power compared to a developing machine.
Beware that GDB over the Bluetooth connection of the e-puck2 is much slower than with USB and it doesn't work with Windows due to GDB limitations on this OS.


===External dependencies===
=Local communication=
Some applications may require external libraries not contained within the standard toolchain package. For instance if your application depends on ''libjpeg'' then you need to tell the cross-compiler where to look to find this library (compiled for the target machine) otherwise your application will not be compiled. If you have OpenEmbedded installed in your system you could simply bitbake the external dependencies (in our example ''bitbake jpeg'') and then compile your application. Instead if you rely on the CodeSourcery toolchain you need to follow these steps:
Local range infrared communication between e-puck2 robots can be achieved using the infrared sensors of the robots to transmit and receive information. The communication system is multiplexed with the proximity sensing system commonly used on the robots, thus it is possible to both communicate and avoid obstacles.<br/>
# download the sources of the library
# cross-compile the library
# install the library (and include files) in the right places
# compile your application


==Ground sensor==
The implementation is based on the [http://www.e-puck.org/index.php?option=com_content&view=article&id=32&Itemid=28 libIrcom] library developed for the e-puck version 1 robots and it keeps retro-compatibility. This means that an e-puck version 1 is able to communicate with an e-puck version 2, so you can still use your e-puck version 1 robots together with e-puck version 2 to form a bigger fleet of robots for your experiments. Moreover the API is the same, thus the code developed for the e-puck version 1 can be used easily also with the e-puck version 2.<br/>
It's possible to use contemporaneously both the e-puck extension for gumstix overo and the ground sensor; in this case the camera and the ground sensor will share the same I2C bus and like the camera, also the ground sensor will not be anymore reachable from the e-puck side, but only from the overo side. <br/>
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo, thus we need to change the bus speed to 100 KHz in order to communicate with the ground sensor module; the simplest way is to set a kernel parameter in u-boot:
# enter u-boot by pressing any key at boot start
# type the command <code>setenv i2cspeed 3,100</code>; this init the I2C bus 3 to 100 KHz
# type the command <code>setenv mmcargs setenv bootargs console=${console} i2c_bus=${i2cspeed} ${optargs} mpurate=${mpurate} vram=${vram} omapfb.mode=dvi:${dvimode} omapdss.def_disp=${defaultdisplay} root=${mmcroot} rootfstype=${mmcrootfstype} </code>; basically we pass an additional parameter to the kernel that is the <code>i2c_bus=${i2cspeed}</code>
# type the command <code>saveenv</code> to save the environment changes
# type <code>boot</code> to start booting
Pay attention that all the peripherals connected to the bus will now work at 100 KHz, thus also the e-puck camera and the LSM330 (accelerometer + gyroscope) present with e-puck HwRev 1.3.<br/>
If you want to set back the bus speed to 400 KHz you need to follow steps 2-4, by setting the <code>i2cspeed</code> u-boot environment variable with <code>setenv i2cspeed 3,400</code>.<br/>
Communicating with the ground sensor is as easy as open a device and reading from it; a source code example can be found in the following link [http://projects.gctronic.com/Gumstix/groundsensor.c http://projects.gctronic.com/Gumstix/groundsensor.c]. You will find this application example in the <code>/home/root/demos/gumstix-common</code> directory; start it by executing <code>./i2c_groundsensors</code> and the sensors values will be displayed in the terminal.<br/>
Make sure that you have installed the last system update otherwise you'll encounter some problems.<br/>
You can find more information about the I2C and gumstix in the following links:
* [https://wiki.gumstix.com/index.php/Category:How_to_-_i2c https://wiki.gumstix.com/index.php/Category:How_to_-_i2c]
<!--
===Examples===
====Images transfer (serial line)====
The application "transfer_images" running on the Gumstix Overo COM performs a request of a variable number of images to the e-puck and transfers them over either TCP or UDP to a server machine (a connection must be configured on both sides before running this program). For more information on the usage refers to the help (-h option). This demo works with the ''advanced sercom'' protocol, so the new e-puck firmware must be already charged and selector 10 must be chosen.<br/>
In order to compile the application the Makefile must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to [http://focus.ti.com/docs/prod/folders/print/omap3503.html http://focus.ti.com/docs/prod/folders/print/omap3503.html]).
[[image:ImageReceiver.jpeg|thumb|Image receiver application.]]
The application "ImageReceiver" running on the server machine is used to visualize the images received from the e-puck. <br/>
The usage is very simple: the server listening port and the protocol must be first selected and then the button "Connect" clicked; at this moment the application is waiting images.
The application is a Qt project, so the compilation may be handled easily with [http://www.qtsoftware.com/products/developer-tools Qt Creator]; alternatively [http://doc.trolltech.com/4.2/qmake-manual.html qmake] can be used.


It's worth to note that the server application must be started before sending images, thus the "ImageReceiver" application must be first executed on the PC side, and the "transfer_images" application must be then executed on the Gumstix Overo side.
Here are some details about the current implementation of the local communication module:
* messages are encoded using a frequency modulation that permits usage in a wide range of light conditions
* the module allows communications at a rate of up to 30 bytes per seconds (maximum theoretical throughput)
* support half-duplex communication
* use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; the sensors update frequency is at most 5 Hz
* messages can be detected at a distance of about 7 cm (good reception), and even up to 12-13 cm (sparse reception)
* messages are stored in a queue (up to 20 messages) and can be retrieved at any time, unless they are overwritten when the queue is full


[http://www.gctronic.com/doc/images/Image_transfer.tar Download Transfer images (Linux)] <br/>
The local communication module is integrated in the factory firmware, so if you want to have a look at the code refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Get_the_source_code Get the source code].<br/>
[http://www.gctronic.com/doc/images/Image_receiver.tar Download Image receiver (Linux)]
A simple exmaple exploiting the local communication can be found in the factory firmware. Put the selector in position 9 and connect the USB cable to the robot: the messages received will be printed in the terminal while the robot continuously send messages to other robots (transceiver behavior). The body led is toggled at each message reception.


====Images grabbing (serial line)====
If an higher throughput and a longer communication distance are required, there is the [http://www.gctronic.com/doc/index.php/Others_Extensions#Range_and_bearing range and bearing extension] designed for this purpose.
This application, running on the Overo COM, requests to the e-puck a customizable number of images that can be parametrized by size, zoom factor, type (gray-scale or color) and window position and save them as bmp; for more information on the usage refers to the help (-h option). This demo works with the ''advanced sercom'' protocol, so the new e-puck firmware must be already charged and selector 10 must be chosen.<br/>
In order to compile the application the Makefile must be modified specifying the path to the cross-compiler like with the "Images transfer" application.


[http://www.gctronic.com/doc/images/GrabCustomImages.tar Download Grab custom images (Linux)]
==Synchronize example==
This is a more advanced example exploiting the local communication. Basically the robots programmed with this demo will eventually orient themselves in the same direction, this is accomplished by exchanging data locally between them.


-->
The same example is also available for e-puck version 1 robots (see [http://www.e-puck.org/index.php?option=com_content&view=article&id=32&Itemid=28 libIrcom]), so you can test it with a mix of robots.


==OpenCV==
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_example_synchronize_10.12.19_734d1f7.elf e-puck2_example_synchronize.elf (10.12.19)].
The Open Computer Vision Library has more than 500 algorithms, documentation and sample code for real time computer vision; you can download it from [http://sourceforge.net/projects/opencvlibrary/ http://sourceforge.net/projects/opencvlibrary/], and find information about it from the official wiki [http://docs.opencv.org/index.html http://docs.opencv.org/index.html]. <br/>
The released system comes with OpenCV version 2.0.0 pre-installed and a demo that shows an example of what can be performed with this library. The demo let the robot follow a black filled circle placed in front of it; if the circle is moved right or left the robot turns consequently. The following figure shows an example of the circle detected by the robot:<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/circle-detection.jpg <img width=200 src="http://www.gctronic.com/doc/images/circle-detection.jpg">]</span> <br/>
In order to start the demo follows these steps:
# turn on the robot with the gumstix extension and login as ''root'' with password ''root''
# go to the directory ''/home/root/demos/gumstix-common'' and execute ''./v4l2grab-opencv -o image.jpg''
# the demo should return the number of circles detected and save a resulting image showing the circles detected if any
Alternatively you can use the following script, that launches the demo and send it through serial (using zmodem) iteratively:
<pre>
#!/bin/bash
while true; do
./v4l2grab-opencv -o image.jpg -q 50
lsz img1.jpg
done
</pre>


The source code can be downloaded from the following link [http://projects.gctronic.com/Gumstix/v4l2grab-opencv-rev15.zip v4l2grab-opencv.zip].  
===Usage===
When the robot is turned on, it starts exchanging information with other robots and try to align with them.<br/>
Beware that the selector position is taken as the id of the robot, so you need to place the selector in a different position for each robot.<br/>
Basically you need to put the selector in an unused position, turn on the robot and place it near the others. The robots will eventually align in the same direction.


<!--
===Building===
====Opencv-linux 1.1pre1 version====
First of all download the source code with the command:  <code>git clone https://github.com/e-puck2/e-puck2_example_synchronize.git</code><br/>
OpenCV can be easily installed on the Gumstix Overo COM, following these steps:
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
Place the cloned repo folder <code>e-puck2_example_synchronize</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
* e-puck2
** e-puck2_main-processor
** e-puck2_example_synchronize


:1. [http://sourceforge.net/projects/opencvlibrary/ Donwload] OpenCV.
Then you can add this project in Eclipse by following the next steps:
:2. Extract the content (tar -xzvf opencv-1.1pre1.tar.gz) of the file in a directory, let it be in "opencv".
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
:3. Open a terminal, and access the directory (cd path/to/opencv).
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_synchronize</code>. Choose <code>None</code> for the the toolchain.
:4. Configure the environment in order to use the cross-compilation tools (if you installed OpenEmbedded, you can find these tools in /tmp/cross/bin/ within the OE main directory): <br/>
# Click on the <code>Finish</code> button and the project is added to Eclipse.
<pre>
# Select the project root folder and go to <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
export CC=/path_to_OE_home_dir/tmp/cross/bin/arm-angstrom-linux-gnueabi-gcc
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
export CXX=/path_to_OE_home_dir/tmp/cross/bin/arm-angstrom-linux-gnueabi-g++
##Select the project root folder and go to <code>File->New->Folder</code>.
</pre>
##Check <code>Advanced >></code> on the bottom.
:5. Now configure OpenCV with the following command; in this configuration several packages are disabled (e.g. gtk) because useless when using console mode to work with the gumstix. Another important option is ''prefix'', which tell where the OpenCV library will be installed. For more information on the configuration refers to the help (--help).<br/>
##Choose <code>Link to alternate location (Linked Folder)</code>.
<pre>
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
./configure --host=arm-linux --build=i686-linux --prefix=/install_dir_path/ --without-gthread --without-gtk --without-python --disable-apps
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
</pre>
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
:6. Type ''make'' and then ''make install''; the directory specified with the ''prefix'' options will contain the compiled library.
:7. Copy the content of this directory to the gumstix, for example in an external SD card.
:8. Before trying to execute an OpenCV based application, you must specify to the system where to find the OpenCV library; you can do this by typing the following command; alternatively it's possible to install directly the library in the /usr/lib directory in the system.
<pre>
export LD_LIBRARY_PATH=/path_to_OpenCV/lib
</pre>


A detailed tutorial on the OpenCV setup for Gumstix can be found in the following link [http://danielbaggio.blogspot.com/2009/01/compiling-opencv-for-gumstix.html Compiling OpenCV for Gumstix].
==Master-slave example==
For this example two robots equipped with the [https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors ground sensors extension] are needed: one acts as a master (transmitter) and the other as a slave (receiver). The master send a command (1 byte) to the slave indicating the current color of its RGB LEDs and the slave when receives the command, interpret it and set its RGB LEDs color to the same color of the master. The ground sensors extension is used to move the robots along a black line in order to follow a desired path.


====Later versions (> 1.1)====
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_example_master_slave_03.03.20_00311f3.elf e-puck2_example_master_slave.elf (03.03.20)].
It's possible to have the OpenCV framework available on your system in two ways:
:1. if OpenEmbedded and bitbake are already configured in the system you can simply type ''bitbake opencv'' and then install the libraries on the micro-sd of the overo
:2. if you have internet access from the overo you can use the package manager by typing ''opkg install opencv'' (it takes a while to complete)
-->


<!--
===Usage===
Later versions of OpenCV (current is 2.0.0) rely on [http://www.cmake.org/ CMake], the cross-platform, open-source build system.You can install it in Ubuntu by typing ''sudo apt-get install cmake''; you can also install a nice front-end for CMake by typing ''sudo apt-get install cmake-gui''; in this way the configuration process of OpenCV becomes easier.<br>
Program the two robots with this demo and set the selector to position 0 for one robot (master) and position 1 (any position but zero would be ok) for the other (slave).<br/>
Follow the steps afterwards to get the newer version of OpenCV compiled for the gumstix:
Print this [https://projects.gctronic.com/epuck2/master-slave-path.pdf master-slave-path.pdf] and place the master on one side and the slave in the other side.<br/>
:1. [http://sourceforge.net/projects/opencvlibrary/ Donwload] OpenCV.
Both robots will move back and forth and when they encounter each other, the master will send its RGB LEDs state to the slave that will reflect the same state on its own RGB LEDs.<br/>
:2. Extract the content (tar -xzvf opencv-2.0.0.tar.gz) of the file in a directory, let it be in "opencv".
You can try different paths and also add more robots with slighly modifications to the code, this is only a starting point.<br/>
:3. Start the CMake interface, by typing in a terminal ''cmake-gui''.
Beware that the robots will detect each other thanks to the proximity sensors values and they start to exchange data only when they're facing each other. This behavior can be changed by continuously exchanging data, in this way you can play also with different distances between the robot's path.
:4. ...to be finished!
-->


==Accelerometer and gyroscope (e-puck HWRev 1.3)==
===Building===
When the e-puck extension for gumstix overo is mounted on the e-puck hardware revision 1.3 the same I2C bus is shared by all the devices (camera, accelerometer, gyroscope) and the overo; since there is only one master (the overo) these devices will not be anymore reachable from the e-puck side. <br/>
First of all download the source code with the command:  <code>git clone https://github.com/e-puck2/e-puck2_example_master_slave.git</code><br/>  
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo and this is fine to work with the accelerometer and gyroscope. <br/>
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
Communicating with the accelerometer and gyroscope is as easy as open a device and reading from it; a source code example can be found in the following link [http://projects.gctronic.com/Gumstix/i2c_lsm330.c i2c_lsm330.c]. You will find this application example in the <code>/home/root/demos/gumstix-common</code> directory; start it by executing <code>./i2c_lsm330</code>, type <code>0</code> to get the accelerometer values or <code>1</code> to get the gyroscope values printed on the terminal.<br/>
Place the cloned repo folder <code>e-puck2_example_master_slave</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
The values of the accelerometer and gyroscope read from the gumstix through the I2C are 16 bits (1g = 16384); beware that regarding the accelerometer values there is a mismatch between the values read from the gumstix through I2C and the values read from the [{{fullurl:Advanced sercom protocol}} advanced sercom protocol] through Bluetooth, the latter are converted in the firmware to maintain compatibility with older e-puck hardware revisions.<br/>
* e-puck2
The orientation of the accelerometer for the values read from the gumstix through the I2C is also different from the one used in the e-puck firmware; the orientation is shown below, the x axis points forward, the y axis points left and the z axis points upward:<br/>
** e-puck2_main-processor
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck-acc-directions1.3.png <img width=150 src="http://www.gctronic.com/doc/images/epuck-acc-directions1.3.png">]</span><br/>
** e-puck2_example_master_slave
===Python===
An example in python is available from the following link [http://projects.gctronic.com/Gumstix/i2c_lsm330.py i2c_lsm330.py]. In order to run the script, some additional dependencies need to be installed in the system, follow these steps:
# configure the network in order to have internet access
# update the package manager repos:
##<code>echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/base/' > /etc/opkg/base-feed.conf</code>
##<code>echo 'src/gz python http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/python/' > /etc/opkg/python-feed.conf</code>
# add <code>arch armv7a-vfp-neon 45</code> to the file <code>/etc/opkg/arch.conf</code>
# <code>opkg update</code>
# <code>opkg -force-overwrite install python-smbus</code>
# optionally you can also remove some warnings related to the update by running the following script [http://projects.gctronic.com/omnicam/remove-warnings.sh remove-warnings.sh]
Once the system is configured you can start the script by executing <code>python i2c_lsm330.py</code>, type <code>0</code> to get the accelerometer values or <code>1</code> to get the gyroscope values printed on the terminal.<br/>


==ROS==
Then you can add this project in Eclipse by following the next steps:
We tested ROS on the gumstix extension with the Yocto system. Follow these steps to get ROS running on the e-puck extension:
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
:1. prepare a micro sd following the instructions from [http://gumstix.org/create-a-bootable-microsd-card.html http://gumstix.org/create-a-bootable-microsd-card.html]
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_master_slave</code>. Choose <code>None</code> for the the toolchain.
:2. download the file system and fat from the following links: [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-FAT.tar.gz yocto-ros-3.5.7-FAT.tar.gz], [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-rootfs.tar.gz yocto-ros-3.5.7-rootfs.tar.gz]
# Click on the <code>Finish</code> button and the project is added to Eclipse.
:3. login with user=root and empty password
# Select the project root folder and go to <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
:4. issue the following commands to enable the WiFi dongle:
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
::<code>echo host > /sys/bus/platform/devices/musb-hdrc/mode</code>
##Select the project root folder and go to <code>File->New->Folder</code>.
::<code>echo -n 1 > /sys/bus/usb/devices/2-1/bConfigurationValue</code>
##Check <code>Advanced >></code> on the bottom.
:5. follow the instructions from [https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#the-fun-part https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#the-fun-part] to run a demo
##Choose <code>Link to alternate location (Linked Folder)</code>.
<!--
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
We tested ROS on the gumstix extension with the Yocto pre-built system. Follow these steps to get ROS running on the e-puck extension:
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
:1. download the Yocto pre-built image from [https://www.gumstix.com/software/software-downloads/ https://www.gumstix.com/software/software-downloads/] (Overo Series COMs)
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
:2. prepare a micro sd following the instructions from [http://gumstix.org/create-a-bootable-microsd-card.html http://gumstix.org/create-a-bootable-microsd-card.html]
:3. configure the network settings in order to get internet access (at the moment you need to plug the WiFi dongle on the USB host)
:4. follow the instructions from [https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#one-time-on-system-setup https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#one-time-on-system-setup] (skip step 1)
If you prefer you can directly download the file system and fat from the following links: [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-FAT.tar.gz yocto-ros-3.5.7-FAT.tar.gz], [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-rootfs.tar.gz yocto-ros-3.5.7-rootfs.tar.gz].
-->


==Python==
=Example projects=
In order to install python 2.6 on the e-puck extension for Gumstix follow these steps:
==Digital Signal Processing (DSP) and wav playback==
# download the package [http://projects.gctronic.com/Gumstix/python-gumstix.tar.gz python-gumstix.tar.gz]
In this example the [http://www.keil.com/pack/doc/CMSIS/DSP/html/index.html CMSIS-DSP] library is used to compute the Fast Fourier Transform of the signal coming from the microphones. The processing power of the main microntroller let the signal to be processed continuously. Moreover this example shows how to play wav files stored in the micro sd.<br/>
# extract the package: <code>tar -zxvf python-gumstix.tar.gz</code>
# remove the micro sd from the robot and connect it to your computer; two partitions will be opened, one called <code>FAT</code> and the other called <code>overo</code> containing the file system (the partitions name could be a little different)
# copy the content of the decompressed file to the same position in the <code>overo</code> partition:
##<code>sudo cp -R /python-gumstix/usr/lib/* /overo/usr/lib</code>
##<code>sudo cp /python-gumstix/usr/bin/* /overo/usr/bin</code>


Alternatively if you have access to internet you can use the package manager:
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_example_dsp_05.10.18_3aa8b81.elf e-puck2_example_dsp.elf (05.10.18)].
# <code>opkg install python</code>
# <code>opkg install python-modules</code>
# <code>opkg install python-pyserial</code>


In order to test your python installation you can download the following script [http://projects.gctronic.com/Gumstix/printhelp.py printhelp.py]; execute it by typing <code>python printhelp.py</code>.
===Usage===
This is a minimal example of serial communication in python that let the gumstix communicate with the robot; basically it opens a serial connection with the robot and ask the available commands that you can use to get sensors data and change actuators state.<br/>
There are basically two demos in this example, one run on selector position 0 and the other in selector position 1.<br/>
Another example is available here [http://projects.gctronic.com/Gumstix/getprox.py getprox.py]; in this script the values of the proximities are requested to the robot and printed to the console. The data are requested in binary format, for more information about the communication protocol refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Advanced_sercom advanced sercom].


=Configuration=
When the selector is in position 0, then the resulting frequency (max amplitude bin) of the computed FFT is mapped to the RGB LEDs: LEDs will be blue when frequency detected is around 250..900 Hz, green when frequency is around 900..1500 Hz and red with 1500..2200 Hz. The brightness of the LEDs is also changed with the frequency.<br/>
==Graphic mode==
The distance sensor (ToF) is also used to detect people in front of the robot. When someone is detected within 50 cm, then the measured distance is mapped to a frequency emitted through the speaker; the generated tone is between 260 Hz (far) and 2240 Hz (near). You can use your hand to play some melody, the robot in the meantime will detect the frequency and show it through the RGB.<br/>
The resolution of the monitor can be modified in the u-boot command line, that can be entered at booting. In the u-boot command line type:
<pre>
setenv dvimode "1280x720MR-16@60"
saveenv
boot
</pre>
Now the configuration is saved in the flash; if your monitor doesn't support the current resolution, repeat the procedure with a different configuration (change the resolution numbers).


Note that the DVI Controller ([http://projects.gctronic.com/Gumstix/tfp410.pdf TFP410]) mounted on Summit and Tobi supports resolutions from VGA (640x480) to UXGA (1600x1200).
When the selector is in position 1, the robot will play a wav file stored in the micro sd when one of the proximity sensors is "touched" (with your finger you go near the proximity and then you go away, like pressing a button). For each proximity there is a different wav file that will be played: for proximity 0 it will be played <code>0.wav</code>, for proximity 1 it will be played <code>1.wav</code> and so on till proximity 7 with <code>7.wav</code>.<br/>


Useful files to look at:
All the wav files you need are stored in the <code>wav</code> directory within the project, put all of them in a micro sd partitioned in FAT32 and you're ready to go. Alternatively you can play your own wav files, beware to name them from <code>0.wav</code> to <code>7.wav</code> and they must be 16 KHz, mono.
* linux_source_home/drivers/video/modedb.c: explains what's the mean of the dvimode names
* linux_source_home/Documentation/fb/viafb.modes: list of available modes usable with the ''fbset'' tool


==GPIO - pins mode==
===Building===
There are three different ways to read GPIO lines:  
First of all download the source code with the command: <code>git clone https://github.com/e-puck2/e-puck2_example_dsp.git</code><br/>
:1. Kernel space: GPIO lines handled through an API
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
:2. User space:  
Place the cloned repo folder <code>e-puck2_example_dsp</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
::2.1. standard filesystem commands like ''cat'' and ''echo'' (static configuration)
* e-puck2
::2.2 direct physical memory access using ''devmem2'' or with a C application (dynamic configuration)
** e-puck2_main-processor
** e-puck2_example_dsp


Afterward will be explained how to handle the GPIO lines on the Gumstix Overo COM in all different methods; information about this topic were found from various sites, but especially from the [http://sourceforge.net/p/gumstix/mailman/ mailing list]. Moreover for a general howto on GPIO refers to the linux documentation [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"].
Then you can add this project in Eclipse by following the next steps:
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_dsp</code>. Choose <code>None</code> for the the toolchain.
# Click on the <code>Finish</code> button and the project is added to Eclipse.
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
##Select the project root folder and go to <code>File->New->Folder</code>.
##Check <code>Advanced >></code> on the bottom.
##Choose <code>Link to alternate location (Linked Folder)</code>.
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).


===Kernel space===
==Microphones recording and pitch scaling==
This example shows how to record the audio (voice) from the onboard microphones and save it in the micro SD.<br/>
Moreover it applies a pitch scaling algorithm to the data before playing it from the micro SD.<br/>
The pitch scale processing is based on the SOLA algorithm and a simple implementation is available from the following link [https://www.surina.net/article/time-and-pitch-scaling.html https://www.surina.net/article/time-and-pitch-scaling.html]. Have a look at this site bacause it has a good explanation of the algorithm.<br/>


===User space===
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_example_pitch_scale_07.11.18_26d16f0.elf e-puck2_example_pitch_scale.elf (07.11.18)].
====Static configuration====
Each of the microprocessor IO pins can be configured to work in different ways for different purposes; in case we desire a certain pin to be configured as a gpio line, we must modify the function assigned to that pin (mux configuration) in the U-Boot board configuration file, that for the Gumstix Overo COM is located at "U-BootSrc/board/overo/overo.h". <!-- you can have a look at it [http://www.sakoman.net/cgi-bin/gitweb.cgi?p=u-boot-omap3.git;a=blob;f=board/overo/overo.h;h=4c7ac27fa6818d4f474bc42330134fd0a5520a37;hb=HEAD here].--> <br/>


To know which modes are available for the pins consult the chapter ''7-System Control Module'' (more specifically ''7.4.4-Pad Functional Multiplexing and Configuration'') in the [http://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf OMAP35x TRM]. <br/>
===Usage===
The example requires a micro SD (FAT32) inserted in the robot.<br/>


Assume we want to have the possibility to switch on and off a led attached to the line gpio70; in order to accomplish this task, we need to follow these steps:
When the robot is turned on, it waits for the button press that triggers the recording. The voice is recorded for about 2 seconds and saved into the micro SD as wav
file. Once the recording is finished, the pitch scale is applied and then the modified voice is played.<br/>


:'''1.''' Modify the board configuration file "overo.h" specifying that the pin has to behave as a gpio line:
You can choose whether to get an higher or lower pitch by changing the <code>TIME_SCALE</code> parameter in <code>sola.c</code>:
<pre>
* if you want to get an higher pitch, then change <code>TIME_SCALE</code> to a value > 1.0
MUX_VAL(CP(DSS_DATA0), (IDIS | PTU | DIS | M4)) /*DSS_DATA0 => GPIO70*/\
* if you want to get a lower pitch, then change the <code>TIME_SCALE</code> to a value < 1.0
</pre>
Of course, if the parameter is changed, you need to rebuild the project and reflash the robot.
:*IDIS = input disable, namely output pin
:*PTU = pull type up, but could be also PTD (pull type down) because of the third parameter
:*DIS = disable pull type up/down
:*M4 = mode 4 (gpio)
:This give us a GPIO pin that is output and not pulled up or down.
:'''2.''' Build U-Boot and place the generated ''u-boot.bin'' image in the flash ([http://www.gumstix.org/how-to/70-writing-images-to-flash.html Writing images to onboard nand]) or in a micro sd card ([http://www.gumstix.org/create-a-bootable-microsd-card.html Creating a bootable microSD card])
:'''3.''' After login, we can see all the GPIO pins that have been exported by the kernel to userspace in the /sys/class/gpio/ directory. In order to access the gpio70 line, we should export it first, by typing:
<pre>
echo "70" > /sys/class/gpio/export
</pre>
:Now the following line is active /sys/class/gpio/gpio70.
:'''4.''' At this point we must configure the direction of the exported line and set a logical value (1 or 0) to that line, we can do that by typing:
<pre>
echo "high" > /sys/class/gpio/gpio70/direction
</pre>
:This command set the pin in output and give it a value of 1.
:'''5.''' Finally we can switch on or off the led, by setting the value of the gpio line:
<pre>
echo "value" > /sys/class/gpio/gpio70/value
</pre>
:Where value=1 means switch on, and value=0 means switch off.


===Building===
First of all download the source code with the command:  <code>git clone https://github.com/e-puck2/e-puck2_example_pitch_scale.git</code><br/>
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
Place the cloned repo folder <code>e-puck2_example_pitch_scale</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
* e-puck2
** e-puck2_main-processor
** e-puck2_example_pitch_scale


In order to automate the process of creating a gpio line accessible through "/sys/class/gpio/", we must modify the board configuration file in the kernel source; this file can be found in "KernelSrc/arch/arm/mach-omap2/board-overo.c" (and related definitions in "KernelSrc/arch/arm/plat-omap/include/mach/board-overo.h"). These files must contain instructions to initialize the gpio line that we want to export in user space and set their direction and initial value. <br/>
Then you can add this project in Eclipse by following the next steps:
Consider the previous example in which we would like to control a led with the gpio70 pin; for this purpose the following instructions must be added in the board configuration file ''board.overo.c'' within the ''overo_init'' function:
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
<pre>
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_pitch_scale</code>. Choose <code>None</code> for the the toolchain.
if ((gpio_request(70, "OVERO_GPIO_DD00") == 0) && (gpio_direction_output(70, 1) == 0)) {
# Click on the <code>Finish</code> button and the project is added to Eclipse.
gpio_export(70, 0);
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
gpio_set_value(70, 1); //not really needed, the initial output value is set with gpio_direction_output
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
} else {
##Select the project root folder and go to <code>File->New->Folder</code>.
printk(KERN_ERR "could not obtain gpio for OVERO_GPIO_DD00\n");
##Check <code>Advanced >></code> on the bottom.
}
##Choose <code>Link to alternate location (Linked Folder)</code>.
</pre>
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
After this modification we need to build the kernel and copy it to the flash or micro sd card, and after login we will have the /sys/class/gpio/gpio70 line automatically active.<br/>
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
For more information on the previous snippet code refers to [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"].
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).


<!--
==C++==
Read a value
A basic example showing how to integrate C++ code in your project is available in the following repository: [https://github.com/e-puck2/e-puck2_cpp https://github.com/e-puck2/e-puck2_cpp].<br/>
Set a pin in input
The example demonstrates simple usage of a class and for range loops.
-->


====Dynamic configuration====
===Building===
If you aren't familiar with modifying and building U-Boot and kernel, you would probably choose to modify the pin configuration at runtime, without the need to touch any board configuration file. The only way to change the configuration of the pins is to access directly the physical memory of the microprocessor, in particular its configuration registers. <br/>
First of all download the source code with the command:  <code>git clone https://github.com/e-puck2/e-puck2_cpp.git</code><br/>
The utility [http://buildroot.uclibc.org/downloads/sources/devmem2.c devmem2] allows for easy reading and writing of the memory; after building and installing this utility on the Gumstix Overo COM, you are ready to change the ports functionality. Consider the previous example of the led on gpio70, to change the pin mode to gpio you must issue the following command:
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
<pre>
Place the cloned repo folder <code>e-puck2_cpp</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
devmem2 0x480020DC b 0x14
* e-puck2
</pre>
** e-puck2_main-processor
''0x480020DC'' is the address of the register we want to write to and can be found observing the table 7-4 on chapter 7.4.4.3 of the [http://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf OMAP35x TRM]; ''b'' means we want to write a byte to that register and finally ''0x14'' is the value we want to write. The pin mode depends on the last three bits, in this case the mode is set to 4, namely the pin is a gpio. From now on we can follow steps from 3 to 5 of the previous chapter to switch on and off the led.
** e-puck2_cpp


An example on modifying the pins configuration through the C programming language can be found in the following link [http://docwiki.gumstix.org/index.php?title=Sample_code/C/gpregs gpregs.c].
Then you can add this project in Eclipse by following the next steps:
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_cpp</code>. Choose <code>None</code> for the the toolchain.
# Click on the <code>Finish</code> button and the project is added to Eclipse.
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
##Select the project root folder and go to <code>File->New->Folder</code>.
##Check <code>Advanced >></code> on the bottom.
##Choose <code>Link to alternate location (Linked Folder)</code>.
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).


===Useful links/resources===
==Bluetooth echo==
For more information on GPIO usage, have a look at the following links:
The aim of this example is to show how to exchange data between the robot and the computer through a Bluetooth connection. The project implements a simple echo behavior, that is what is received by the robot is sent back to the computer.
* [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"]
* [http://sourceforge.net/p/gumstix/mailman/ gumstix mailing list]
* [http://wiki.gumstix.org/index.php?title=GPIO http://wiki.gumstix.org/index.php?title=GPIO]
* [http://www.avrfreaks.net/wiki/index.php/Documentation:Linux/GPIO http://www.avrfreaks.net/wiki/index.php/Documentation:Linux/GPIO]
* [http://www.hy-research.com/omap3_pinmux.html http://www.hy-research.com/omap3_pinmux.html]
* [http://focus.ti.com/docs/prod/folders/print/omap3530.html http://focus.ti.com/docs/prod/folders/print/omap3530.html]
* [http://pixhawk.ethz.ch/omap/start http://pixhawk.ethz.ch/omap/start]
* [http://docs.blackfin.uclinux.org/doku.php?id=gpio http://docs.blackfin.uclinux.org/doku.php?id=gpio]


<!--
===Building===
==U-Boot==
First of all download the source code with the command:  <code>git clone https://github.com/e-puck2/e-puck2_example_bluetooth_echo.git</code><br/>
You can find the U-Boot source at "git://gitorious.org/u-boot-omap3/mainline.git" or "http://git.gitorious.org/u-boot-omap3/mainline.git".
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
-->
Place the cloned repo folder <code>e-puck2_example_bluetooth_echo</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
* e-puck2
** e-puck2_main-processor
** e-puck2_example_bluetooth_echo


=Webots interface=
Then you can add this project in Eclipse by following the next steps:
Nikola Velickovic developed an interface with the Webots simulator during his MSc Thesis in 2012.
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
His report is available [http://projects.gctronic.com/Gumstix/MScThesis_NikolaVelickovic_2012.tar.gz here].
# Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_bluetooth_echo</code>. Choose <code>None</code> for the the toolchain.
His files are available [http://projects.gctronic.com/Gumstix/ThesisProjectFiles(30.12.2011).tar.gz here].
# Click on the <code>Finish</code> button and the project is added to Eclipse.
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
##Select the project root folder and go to <code>File->New->Folder</code>.
##Check <code>Advanced >></code> on the bottom.
##Choose <code>Link to alternate location (Linked Folder)</code>.
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).


=FAQ=
==Ball detection==
'''1. Why the serial communication between Gumstix Overo COM and the robot doesn't work?''' <br/>
Pierre Oppliger and WIlliam Galand, during their semester project at EPFL, were able to let the e-puck2 robot reliably recognize a ball independently of light conditions. This is a step towards an e-puck2 football soccer player. For more information about the project (French) and source code, have a look at the repository [https://github.com/e-puck2/e-puck-2-footy https://github.com/e-puck2/e-puck-2-footy].
There could be three possible reasons for the communication problem:
* selector position incorrect: you need to be sure that the robot selector is in position 10 in order to start the right software on the robot side
* wrong device: the serial device is identified as /dev/ttyS0 in the linux machine, be sure to use it when you're using for example the sertest demo ("./sertest -p /dev/ttyS0 -b 230400")
* battery discharged: somebody could be deceived from the fact that the linux console is still usable, but if the orange led on the robot indicating the low battery level is turned on, then the robot will not be able anymore to respond, even if you are working on the linux console; either change or charge your battery and try again. <br/>


'''2. I am able to communicate with the robot through the serial line, but seems that I receive only garbage, why?''' <br/>
=Firmware update using factory bootloader=
Probably the baudrate isn't correct; with the robot selector in position 10 you need to configure the baudrate at 230400 (e.g "./sertest -p /dev/ttyS0 -b 230400"). <br/>
==Factory firmware==
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_29.03.23_6363512.bin  main microcontroller factory firmware.bin (29.03.23)]; it is also available in dfu format here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_29.03.23_6363512.dfu main microcontroller factory firmware.dfu (29.03.23)].


'''3. Can I use bluetooth to connect to the robot? Can I use the [http://www.gctronic.com/doc/index.php/E-Puck#PC_interface monitor]?''' <br/>
==Firmware update==
Yes, you can connect to the robot with bluetooth and play with the monitor interface placing the selector in position 3. You'll experience some errors on the values displayed on the monitor due to the additional two long IR sensors that aren't considered when the interface was developed; moreover you will not be able to receive images from the robot. <br/>
This procedure should be used only if the normal firmware update steps described in the section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update] don't work. This is a recovery procedure.<br/>


'''4. Why I cannot connect to the robot through SSH? <br/>
The main microcontroller features a factory bootloader that can be entered by acting on some special pins, the bootloader mode is called DFU (device firmware upgrade). You can enter DFU mode by first connecting the USB cable, then pressing the button called <code>407 boot</code> while turning on the robot. The button is located near the left wheel, on the bottom side of the electronic board, see the photo below.
* first of all be sure that the network is well configured (you can i.e. ping the robot sucessfully)
* check the SSH daemon is running typing: ''ps -ef | grep sshd''; if it is not running then setup the SSH daemon to run automatically at boot; for this purpose you can type ''update-rc.d sshd defaults 99''. This command will install the links to ''sshd'' into rc*.d dirs. See the man page for more informations.
* if the SSH server is running, but you get an error like "ssh: connect to host 192.168.1.2 port 22: Connection refused" when trying to connect, you can check whether a user and group sshd are created. If not, add the following entries in the system:
<pre>
/etc/group:sshd:*:27:
/etc/passwd:sshd:*:27:27:sshd privsep:/var/empty:/sbin/nologin
</pre>


'''5. How to auto-login and execute applications automatically at startup? <br/>
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/F407-dfu.jpg <img width=200 src="https://projects.gctronic.com/epuck2/wiki_images/F407-dfu-small.jpg">]</span><br/>
Refers to the instructions explained here [https://wiki.gumstix.com/index.php/AutoLogin https://wiki.gumstix.com/index.php/AutoLogin].
::''Location of the button to put the main microcontroller into DFU''


'''6. Are micro SDHC supported? <br/>
The main microcontroller will be recognized as <code>STM Device in DFU Mode</code> device.
Yes they are supported.


=Videos=
'''Note for Windows users''': the device should be recognized automatically (in all Windows versions), but in case it won't be detected then you need to install a <code>libusbK</code> driver for the DFU device.<br>
<!--{{#ev:youtube|LQC9lvn9w8Q}}
Follow the same procedure as explained in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers Installing the USB drivers] using <code>libusbK</code> driver instead of <code>USB Serial (CDC)</code>.<br/>
Comments:
If you still have problems, try to install the drivers you can find in <code>C:\Program Files (x86)\STMicroelectronics\Software\DfuSe v3.0.6\Bin\Driver</code>.
We have sent an e-puck on a mission to find our office plant.  
It's actually a standard e-puck with a wifi connection to the laptop and the Gumstix's overo extention  with Linux OS, all runned by a powerful 0.6 Ghz processor. -->


{{#ev:youtube|a0Ozy-oRQIs}} <br/>
===Linux/Mac===
Comments: This e-puck is on an exploration, his camera sends continuous image to the computer with a wifi connection.
In order to update the main microcontroller firmware you need an utility called <code>dfu-util</code>, it should be already installed from section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates].<br/>
To uplaod the firmware, issue the following command: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin</code> (the name of the bin file must be changed accordingly).


=Useful links=
===Windows===
[http://www.gumstix.org/ http://www.gumstix.org/] <br/>
Start the <code>DfuSe</code> application (previously installed from section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates]). The programmer in DFU mode will be automatically detected as shown in figure 1. Then you need to open the compiled firmware by clicking on <code>choose</code> and then locating the file with <code>dfu</code> extension,  as shown in figure 2. Now click on the <code>upgrade</code> button, a warning message will be shown, confirm the action by clicking on <code>yes</code> as shown in figure 3. If all is ok you'll be prompted with a message saying that the upgrade was successfull as shown in figure 4.<br/>
[http://wiki.gumstix.org/index.php?title=Main_Page http://wiki.gumstix.org/index.php?title=Main_Page] <br/>
<span class="plainlinks">
[http://docwiki.gumstix.org/index.php/Gumstix_Buildroot_Support_Wiki http://docwiki.gumstix.org/index.php/Gumstix_Buildroot_Support_Wiki] <br/>
<table>
[http://docwiki.gumstix.org/index.php?title=U-Boot http://docwiki.gumstix.org/index.php?title=U-Boot] <br/>
<tr>
[http://www.openembedded.org/wiki/Main_Page http://www.openembedded.org/wiki/Main_Page] <br/>
<td align="center">[1]</td>
[http://www.e-puck.org/ http://www.e-puck.org/] <br/>
<td align="center">[2]</td>
[http://www.jumpnowtek.com/ http://www.jumpnowtek.com/] <br/>
<td align="center">[3]</td>
<td align="center">[4]</td>
</tr>
<tr>
<td>[https://projects.gctronic.com/epuck2/wiki_images/dfu1.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu1.png">]</td>
<td>[https://projects.gctronic.com/epuck2/wiki_images/dfu2_f407.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu2_f407.png">]</td>
<td>[https://projects.gctronic.com/epuck2/wiki_images/dfu3.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu3.png">]</td>
<td>[https://projects.gctronic.com/epuck2/wiki_images/dfu4.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu4.png">]</td>
</tr>
</table>
</span><br/>

Revision as of 13:59, 29 March 2023

e-puck2 main wiki

Introduction

The C programming language is used to develop code for the main microcontroller of the e-puck2 robot. The ChibiOS embedded real-time OS was chosen to be integrated in the firmware, since it support the STM32F4 family of microprocessors, it includes an HAL (Hardware Abstraction Layer), it's well documented and finally it's free.
Before starting to code, you need to install the developing environment and its dependencies, all the steps are documented afterwards.
The factory firmware integrates both the e-puck2 library used to handle all the sensors and actuators together with a series of demos that use this library. Thus you can either take the factory firmware and directly modify its main, otherwise you can start a fresh new project by linking the factory firmware project as an external library.
You can also modify the library itself, but before digging into the details, try to contact us, maybe we're already working on that subject or we can help you.

Installation of the e-puck2 environment

Eclipse_e-puck2 is a distribution of Eclipse IDE for C/C++ Developers specially modified to edit and compile e-puck2's projects out of the box. It doesn't require to be installed and everything needed is located in the package given. The only dependency needed to be able to run Eclipse is Java.

Installation for Windows

Java 8 32bits

This section can be ignored if Java version >= 8 32bits is already installed on your computer.
To verify you already installed Java, you can open Programs and Features from the control panel and search for a AdoptOpenJDK JDK with Hotspot xxx install. If this entry isn't present, then you need to install it:

  1. Go to OpenJDK download page and download the OpenJDK 8 (LTS) HotSpot for Windows x86 JDK (take the installer, aka. .msi file).
  2. Run the downloaded installer and follow its instructions to proceed with the installation of OpenJDK 32bits.

OpenJDK download page

Eclipse_e-puck2

  1. Download the Eclipse_e-puck2 package for windows.
  2. Unzip the downloaded file to the location you want (can take time). It is strongly recommended for better performance and less extraction time to use 7Zip. You can download it on http://www.7-zip.org.
  3. You can now run the Eclipse_e-puck2.exe to launch Eclipse.
  4. You can create a shortcut to Eclipse_e-puck2.exe and place it anywhere if you want.

Eclipse_e-puck2 folder obtained after extraction

Important things to avoid :

1. The path to the Eclipse_e-puck2 folder must contain zero space.
Example :
C:\epfl_stuff\Eclipse_e-puck2 OK
C:\epfl stuff\Eclipse_e-puck2 NOT OK
2. You must not put Eclipse_e-puck2 folder into Program Files (x86). Otherwise the compilation when using Eclipse will not work.
3. The file’s structure in the Eclipse_e-puck2 folder must remain the same. It means no file inside this folder must be moved to another place.

Configuring the PATH variable

The PATH variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.

If you want to use the arm-none-eabi toolchain provided inside the Eclipse_e-puck2 package, you have to add it to the PATH variable to be able to call it inside a terminal window. To set the PATH variable you need to issue the following command:

set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%

What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the PATH variable.

If you want to set the PATH variable permanently, then go to Control panel => System => Advanced system settings => Environment variables. A list of variables defined for the user is shown, double click on the PATH variable (from the user variables list) and add at the end ;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin, then click OK three times.

Note : The arm-none-eabi version can differ from the one given in this example. It could be needed to adapt the path to the correct version.

Installation for Linux

Java 8

This section can be ignored if Java is already installed on your computer.
To verify whether it is installed or not you can type the following command into a terminal window: update-java-alternatives -l. If Java is installed, you will get some information about it, otherwise the command will be unknown.
You need to have Java 1.8.xxxx listed to be able to run Eclipse_e-puck2.

Type the following commands in a terminal session to install Java SDK: 

sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jre

Eclipse_e-puck2

  1. Install make (probably you already have it installed) by issueing the command: sudo apt-get install make
  2. Download the Eclipse_e-puck2 package for Linux 32bits / 64bits. Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand uname -a in the terminal window and look for i686 (32bit) or x86_64 (64 bit).
  3. Extract the downloaded file to the location you want (can take time): tar -zxvf package_name.tar.gz
  4. You can now run the Eclipse_e-puck2 executable to launch Eclipse.

Eclipse_e-puck2 folder obtained after extraction

Note : The icon of the Eclipse_e-puck2 executable will appear after the first launch of the program.

Important things to avoid :

1. You cannot create a Link to the Eclipse_e-puck2 executable because otherwise the program will think its location is where the Link is and it will not find the resources located in the Eclipse_e-puck2 folder.
2. The path to the Eclipse_e-puck2 folder must contain zero space.
Example :
/home/student/epfl_stuff/Eclipse_e-puck2 OK
/home/student/epfl stuff/Eclipse_e-puck2 NOT OK
3. The file’s structure in the Eclipse_e-puck2 folder must remain the same. It means no file inside this folder must be moved to another place.

Configuring the PATH variable

The PATH variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.

If you want to use the arm-none-eabi toolchain provided inside the Eclipse_e-puck2 package, you have to add it to the PATH variable to be able to call it inside a terminal window. To set the PATH variable you need to issue the following command:

export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH

What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the PATH variable.

If you want to set the PATH variable permanently, then you need to set it in the .profile file by issuing the command:
echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile
Close and reopen the terminal before using your newly set environment variable.

Note : The arm-none-eabi version can differ from the one given in this example. It could be needed to adapt the path to the correct version.

Installation for Mac

Command Line Tools

To compile on Mac with Eclipse_e-puck2, it is necessary to have the Command Line Tools installed. It is a bundle of many commonly used tools.
You can install it by typing the following command in a terminal window: xcode-select --install. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.

Java 8

This section can be ignored if Java is already installed on your computer.
To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac: /usr/libexec/java_home -V
You need to have AdoptOpenJDK 8 listed to be able to run Eclipse_e-puck2.

  1. Go to OpenJDK download page and download the OpenJDK 8 (LTS) HotSpot for MacOS x64 JDK (take the installer, aka. .pkg file).
  2. Open the .pkg file downloaded and follow the instructions to proceed with the installation of OpenJDK.

OpenJDK download page

Eclipse_e-puck2

1. Download the Eclipse_e-puck2 package for Mac.
2. Open the .dmg file downloaded (confirm opening if a warning message appear) and drag and drop the Eclipse_e-puck2.app into the Applications folder
Note: you can place the Eclipse_e-puck2.app anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in Applications.
3. You can create an Alias to Eclipse_e-puck2.app and place it anywhere if you want.

First launch and Gatekeeper

It’s very likely that Gatekeeper (one of the protections of Mac OS) will prevent you to launch Eclipse_e-puck2.app because it isn’t signed from a known developer.
If you can’t run the program because of a warning of the system, press OK and try to launch it by right clicking on it and choosing open in the contextual menu (may be slow to open the first time).
If Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer. or if "Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash. appears after executing the app the first time, it is needed to disable temporarily Gatekeeper.

To do so :

1. Go to System Preferences->security and privacy->General and authorize downloaded application from Anywhere.

Security settings of Mac OS
If you are on Mac OS Sierra or greater (greater or equal to Mac OS 10.12), you must type the following command on the terminal to make the option above appear.
sudo spctl --master-disable
2. Now you can try to run the application and it should work.
3. If Eclipse opened successfully, it is time to reactivate Gatekeeper. Simply set back the setting of Gatekeeper.
For the ones who needed to type a command to disable Gatekeeper, here is the command to reactivate it.
sudo spctl --master-enable

This procedure is only needed the first time. After that Gatekeeper will remember your choice to let run this application and will not bother you anymore, as long as you use this application. If you re-download it, you will have to redo the procedure for Gatekeeper.

Important things to avoid :

1. The path to the Eclipse_e-puck2.app must contain zero space.
Example :
/home/student/epfl_stuff/Eclipse_e-puck2 OK
/home/student/epfl stuff/Eclipse_e-puck2 NOT OK
2. The file’s structure in the Eclipse_e-puck2.app must remain the same. It means no file inside this app must be moved to another place.

Configuring the PATH variable

The PATH variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.

If you want to use the arm-none-eabi toolchain provided inside the Eclipse_e-puck2 package, you have to add it to the PATH variable to be able to call it inside a terminal window. To set the PATH variable you need to issue the following command:

export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH

If you put the Eclipse_e-puck2.app into the Applications folder then the exact command would be:

export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH

What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the PATH variable.

If you want to set the PATH variable permanently, then you need to set it in the .bash_profile file by issuing the command:
echo 'export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.bash_profile
Close and reopen the terminal before using your newly set environment variable.

Note : The arm-none-eabi version can differ from the one given in this example. It could be needed to adapt the path to the correct version.

Get the source code

The code of the e-puck2 is open source and is available as a git repository. To download the source code you need to install git on your system:

  • Windows: downlaod git from https://gitforwindows.org/ and follow the installation instructions (default configuration is ok)
  • Linux: issue the command sudo apt-get install git
  • Mac: issue the command brew install git

The source code can downloaded with the command: git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.

This repository contains the main microcontroller factory firmware together with the e-puck2 library. This library includes all the functions needed to interact with the robot's sensors and actuators; the factory firmware shows how to use these functions.

A snapshot of the repository can be downloaded from e-puck2_main-processor_snapshot_17.03.20.zip.

Creating a project

Main microcontroller factory firmware project

If you want to modify the code of the factory firmware running on the main microcontroller, or if you want to have a look at the implementation details, then you can add this project in Eclipse by following the next steps:

1 Run Eclipse and then select File->New->Makefile Project with Existing Code.

2 Next click on the Browse button and choose the project folder of the git repository downloaded previously (should be named e-puck2_main-processor) and set a project name (otherwise you can keep the one created by Eclipse). Choose None for the the toolchain.
3 Click on the Finish button and the project is added to Eclipse.

4 Build the project by selecting one directory of the project from the left panel and then Project->Build Project.

Project template

The main microcontroller factory firmware project can also be used as a library to build your own project on top of it.

To accomplish that, you have to copy the folder Project_template, contained in the e-puck2_main-processor project, and place it in the same directory of the e-puck2_main-processor project; you can of course rename the folder to the name you want (e.g. myproject). You must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • myproject

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder of your project (e.g. myproject) and set a project name (otherwise you can keep the one created by Eclipse). Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Now you can write your own program. If you want to add source files (.c) to the project you need to add them also in the makefile, in the CSRC definition. All the headers files (.h) located next to the makefile are automatically included in the compilation, but if you need to place them into folders, you have to specify these folders in the makefile, in the INCDIR definition. The same is needed for any desired .h files from other external folders.
In the makefile you can also set the name of your project.
This makefile uses the main makefile of the e-puck2_main-processor project. This means you can add custom commands to the makefile but it should not interfere with the main makefile.

Configuring the Debugger's settings

Eclipse_e-puck2 contains everything needed to compile, program and debug the e-puck2.
The only settings to configure with a new project are located under the Debug Configurations icon of Eclipse (you can also find it on Run->Debug Configurations).


Once in the settings, select Generic Blackmagic Probe preset on the left panel. Then you need to configure two things :

  1. In the main tab, select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse should have indexed the binaries and you can list the project and the compiled files using respectively the Browse... and Search Project... buttons.
    If nothing is appearing when you press Search Project... then you must enter the .elf file name by hand, which can be found in your project build folder (e.g. build/e-puck2_main-processor.elf).
  2. In the Startup tab, you need to replace the serial port name written on the first line of the text box by the one used by the GDB Server of your robot. See how to find it.
  • For Windows, it will be \\.\COMX, X being the port number.
  • For Linux, it will be /dev/ttyACMX, X being the port number
  • For Mac, it will be /dev/cu.usbmodemXXXXX, XXXXX being the port number.
  • You can also type ${COM_PORT} instead of the com port in order to use the variable COM_PORT for the debug configuration.
    To change the value of this variable, go to the main tab again, click on the Variables... button and click on the Edit Variables... button. The opened window will let you edit the value of the variable.
    Using the variable COM_PORT instead of the real com port in a debug configuration is useful if for example you have multiple debug configurations. If for some reason you need to change the serial port to use, then you can simply edit the variable COM_PORT instead of editing the serial port for each debug configuration.

If you want to debug another project, you can duplicate this settings and change the relevant parts (project name and path to compiled file) in order to have one launch configuration for each project.


Now you should be able to use the debugger with Eclipse.

Notice that the settings are saved in the project folder in a file with extension .launch. If you want, you can rename this file (e.g. Debug_project_template.launch) with the name you want for the debug configuration of your project.

Running a debugging session

Once the debugger is configured, you can start a debugging session. When starting a session, the robot is programmed with the current developed program, thus starting a debugging session means also updating the main microcontroller firmware. This is in fact the way to update the firwmare via Eclipse; to do it manually refer to the section Main microcontroller: firmware update.

To start a session follow the next steps:

  1. Connect the robot to the computer and turn it on
  2. From Eclipse, launch the debug configuration previously set: from the menu Run->Debug configurations..., select the configuration and click on the Debug button.
    Alternatively you can directly select your configuration from the debugger drop-down menu.

  3. When the debugging session is started, Eclipse will change the view to the Debug perspective. Right-click on the main process and select Restart to restart the program from the beginning
  4. Click on the Resume button on top of the window to start your program. Now you can suspend and resume whenever you want, then when you want to modify your code again you click on the Terminate button and click on the C/C++ perspective button.

Adding breakpoints

Watch variables

Analyze microcontroller registers content

When a debugging session is started, the microcontroller's registers state can be inspected by clicking on the EmbSys Registers tab on the top right side of the Debug perspective.

Bluetooth debugging session

It is possible to run a debugging session remotely thorugh Bluetooth following these steps:

  1. change the programmer's mode to mode 1 with the command monitor select_mode 1, for more informations refer to e-puck2 programmer development, chapter Configuring the Programmer's settings
  2. pair the robot with the computer
  3. in the debugger's settings, setup the port with the Bluetooth channel 1, GDB port name, for more informations refer to Connecting to the Bluetooth
  4. start the debugging session and the Bluetooth connection will be established automatically; now you can program/debug the robot remotely

Beware that GDB over the Bluetooth connection of the e-puck2 is much slower than with USB and it doesn't work with Windows due to GDB limitations on this OS.

Local communication

Local range infrared communication between e-puck2 robots can be achieved using the infrared sensors of the robots to transmit and receive information. The communication system is multiplexed with the proximity sensing system commonly used on the robots, thus it is possible to both communicate and avoid obstacles.

The implementation is based on the libIrcom library developed for the e-puck version 1 robots and it keeps retro-compatibility. This means that an e-puck version 1 is able to communicate with an e-puck version 2, so you can still use your e-puck version 1 robots together with e-puck version 2 to form a bigger fleet of robots for your experiments. Moreover the API is the same, thus the code developed for the e-puck version 1 can be used easily also with the e-puck version 2.

Here are some details about the current implementation of the local communication module:

  • messages are encoded using a frequency modulation that permits usage in a wide range of light conditions
  • the module allows communications at a rate of up to 30 bytes per seconds (maximum theoretical throughput)
  • support half-duplex communication
  • use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; the sensors update frequency is at most 5 Hz
  • messages can be detected at a distance of about 7 cm (good reception), and even up to 12-13 cm (sparse reception)
  • messages are stored in a queue (up to 20 messages) and can be retrieved at any time, unless they are overwritten when the queue is full

The local communication module is integrated in the factory firmware, so if you want to have a look at the code refer to section Get the source code.
A simple exmaple exploiting the local communication can be found in the factory firmware. Put the selector in position 9 and connect the USB cable to the robot: the messages received will be printed in the terminal while the robot continuously send messages to other robots (transceiver behavior). The body led is toggled at each message reception.

If an higher throughput and a longer communication distance are required, there is the range and bearing extension designed for this purpose.

Synchronize example

This is a more advanced example exploiting the local communication. Basically the robots programmed with this demo will eventually orient themselves in the same direction, this is accomplished by exchanging data locally between them.

The same example is also available for e-puck version 1 robots (see libIrcom), so you can test it with a mix of robots.

The pre-built firmware is available here e-puck2_example_synchronize.elf (10.12.19).

Usage

When the robot is turned on, it starts exchanging information with other robots and try to align with them.
Beware that the selector position is taken as the id of the robot, so you need to place the selector in a different position for each robot.
Basically you need to put the selector in an unused position, turn on the robot and place it near the others. The robots will eventually align in the same direction.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_example_synchronize.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_example_synchronize in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_example_synchronize

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_example_synchronize. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Master-slave example

For this example two robots equipped with the ground sensors extension are needed: one acts as a master (transmitter) and the other as a slave (receiver). The master send a command (1 byte) to the slave indicating the current color of its RGB LEDs and the slave when receives the command, interpret it and set its RGB LEDs color to the same color of the master. The ground sensors extension is used to move the robots along a black line in order to follow a desired path.

The pre-built firmware is available here e-puck2_example_master_slave.elf (03.03.20).

Usage

Program the two robots with this demo and set the selector to position 0 for one robot (master) and position 1 (any position but zero would be ok) for the other (slave).
Print this master-slave-path.pdf and place the master on one side and the slave in the other side.
Both robots will move back and forth and when they encounter each other, the master will send its RGB LEDs state to the slave that will reflect the same state on its own RGB LEDs.
You can try different paths and also add more robots with slighly modifications to the code, this is only a starting point.
Beware that the robots will detect each other thanks to the proximity sensors values and they start to exchange data only when they're facing each other. This behavior can be changed by continuously exchanging data, in this way you can play also with different distances between the robot's path.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_example_master_slave.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_example_master_slave in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_example_master_slave

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_example_master_slave. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Example projects

Digital Signal Processing (DSP) and wav playback

In this example the CMSIS-DSP library is used to compute the Fast Fourier Transform of the signal coming from the microphones. The processing power of the main microntroller let the signal to be processed continuously. Moreover this example shows how to play wav files stored in the micro sd.

The pre-built firmware is available here e-puck2_example_dsp.elf (05.10.18).

Usage

There are basically two demos in this example, one run on selector position 0 and the other in selector position 1.

When the selector is in position 0, then the resulting frequency (max amplitude bin) of the computed FFT is mapped to the RGB LEDs: LEDs will be blue when frequency detected is around 250..900 Hz, green when frequency is around 900..1500 Hz and red with 1500..2200 Hz. The brightness of the LEDs is also changed with the frequency.
The distance sensor (ToF) is also used to detect people in front of the robot. When someone is detected within 50 cm, then the measured distance is mapped to a frequency emitted through the speaker; the generated tone is between 260 Hz (far) and 2240 Hz (near). You can use your hand to play some melody, the robot in the meantime will detect the frequency and show it through the RGB.

When the selector is in position 1, the robot will play a wav file stored in the micro sd when one of the proximity sensors is "touched" (with your finger you go near the proximity and then you go away, like pressing a button). For each proximity there is a different wav file that will be played: for proximity 0 it will be played 0.wav, for proximity 1 it will be played 1.wav and so on till proximity 7 with 7.wav.

All the wav files you need are stored in the wav directory within the project, put all of them in a micro sd partitioned in FAT32 and you're ready to go. Alternatively you can play your own wav files, beware to name them from 0.wav to 7.wav and they must be 16 KHz, mono.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_example_dsp.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_example_dsp in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_example_dsp

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_example_dsp. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Microphones recording and pitch scaling

This example shows how to record the audio (voice) from the onboard microphones and save it in the micro SD.
Moreover it applies a pitch scaling algorithm to the data before playing it from the micro SD.
The pitch scale processing is based on the SOLA algorithm and a simple implementation is available from the following link https://www.surina.net/article/time-and-pitch-scaling.html. Have a look at this site bacause it has a good explanation of the algorithm.

The pre-built firmware is available here e-puck2_example_pitch_scale.elf (07.11.18).

Usage

The example requires a micro SD (FAT32) inserted in the robot.

When the robot is turned on, it waits for the button press that triggers the recording. The voice is recorded for about 2 seconds and saved into the micro SD as wav file. Once the recording is finished, the pitch scale is applied and then the modified voice is played.

You can choose whether to get an higher or lower pitch by changing the TIME_SCALE parameter in sola.c:

  • if you want to get an higher pitch, then change TIME_SCALE to a value > 1.0
  • if you want to get a lower pitch, then change the TIME_SCALE to a value < 1.0

Of course, if the parameter is changed, you need to rebuild the project and reflash the robot.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_example_pitch_scale.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_example_pitch_scale in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_example_pitch_scale

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_example_pitch_scale. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

C++

A basic example showing how to integrate C++ code in your project is available in the following repository: https://github.com/e-puck2/e-puck2_cpp.
The example demonstrates simple usage of a class and for range loops.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_cpp.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_cpp in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_cpp

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_cpp. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Bluetooth echo

The aim of this example is to show how to exchange data between the robot and the computer through a Bluetooth connection. The project implements a simple echo behavior, that is what is received by the robot is sent back to the computer.

Building

First of all download the source code with the command: git clone https://github.com/e-puck2/e-puck2_example_bluetooth_echo.git
The command must be issued in Git bash on Windows, or in a terminal on Linux / Mac.
Place the cloned repo folder e-puck2_example_bluetooth_echo in the same directory of the e-puck2_main-processor project; you must end up with the following directory tree:

  • e-puck2
    • e-puck2_main-processor
    • e-puck2_example_bluetooth_echo

Then you can add this project in Eclipse by following the next steps:

  1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
  2. Next click on the Browse button and choose the project folder e-puck2_example_bluetooth_echo. Choose None for the the toolchain.
  3. Click on the Finish button and the project is added to Eclipse.
  4. Select the project root folder and go to Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers and check CDT Cross GCC Built-in Compiler Settings.
    Then in the textbox below, write arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}".
  5. Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
    1. Select the project root folder and go to File->New->Folder.
    2. Check Advanced >> on the bottom.
    3. Choose Link to alternate location (Linked Folder).
    4. Type PROJECT_LOC/../e-puck2_main-processor and click the Finish button.
  6. Build the project by selecting one file of the project from the left panel and then Project->Build Project. The result of the compilation will appear in the build folder in your project folder.
  7. After you compile the project, select the project root folder and go to Project->C/C++ Index->Rebuild to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).

Ball detection

Pierre Oppliger and WIlliam Galand, during their semester project at EPFL, were able to let the e-puck2 robot reliably recognize a ball independently of light conditions. This is a step towards an e-puck2 football soccer player. For more information about the project (French) and source code, have a look at the repository https://github.com/e-puck2/e-puck-2-footy.

Firmware update using factory bootloader

Factory firmware

The pre-built firmware is available here main microcontroller factory firmware.bin (29.03.23); it is also available in dfu format here main microcontroller factory firmware.dfu (29.03.23).

Firmware update

This procedure should be used only if the normal firmware update steps described in the section Main microcontroller: firmware update don't work. This is a recovery procedure.

The main microcontroller features a factory bootloader that can be entered by acting on some special pins, the bootloader mode is called DFU (device firmware upgrade). You can enter DFU mode by first connecting the USB cable, then pressing the button called 407 boot while turning on the robot. The button is located near the left wheel, on the bottom side of the electronic board, see the photo below.


Location of the button to put the main microcontroller into DFU

The main microcontroller will be recognized as STM Device in DFU Mode device.

Note for Windows users: the device should be recognized automatically (in all Windows versions), but in case it won't be detected then you need to install a libusbK driver for the DFU device.
Follow the same procedure as explained in section Installing the USB drivers using libusbK driver instead of USB Serial (CDC).
If you still have problems, try to install the drivers you can find in C:\Program Files (x86)\STMicroelectronics\Software\DfuSe v3.0.6\Bin\Driver.

Linux/Mac

In order to update the main microcontroller firmware you need an utility called dfu-util, it should be already installed from section Installing the dependencies for firmwares updates.
To uplaod the firmware, issue the following command: sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin (the name of the bin file must be changed accordingly).

Windows

Start the DfuSe application (previously installed from section Installing the dependencies for firmwares updates). The programmer in DFU mode will be automatically detected as shown in figure 1. Then you need to open the compiled firmware by clicking on choose and then locating the file with dfu extension, as shown in figure 2. Now click on the upgrade button, a warning message will be shown, confirm the action by clicking on yes as shown in figure 3. If all is ok you'll be prompted with a message saying that the upgrade was successfull as shown in figure 4.

[1] [2] [3] [4]


Retrieved from "http://www.gctronic.com/doc/index.php?title=Overo_Extension&oldid=2326"