e-puck2 robot side development: Difference between revisions

From GCtronic wiki
Jump to navigation Jump to search
 
(227 intermediate revisions by the same user not shown)
Line 1: Line 1:
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
[{{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=
=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'''.
<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'''.
Line 6: Line 12:
===Java 8 32bits===
===Java 8 32bits===
This section can be ignored if Java version >= 8 32bits is already installed on your computer.<br>
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>Java 8 Update xxx</code> install. If this entry isn't present, then you need to install it:
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) or you can directly download it from [https://projects.gctronic.com/epuck2/OpenJDK8U-jdk_x86-32_windows_hotspot_8u422b05.msi OpenJDK8U-jdk_x86-32_windows_hotspot_8u422b05.msi].
#Go to the [https://www.java.com/en/download/manual.jsp Java download page] and download the <code>Windows offline</code> pacakge. This is the 32bits version of Java.
# Run the downloaded installer and follow its instructions to proceed with the installation of OpenJDK 32bits.
#Run the downloaded installer and follow its instructions to proceed with the installation of Java 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/>
#Close the internet browser if it opened at the end of the installation.
:''OpenJDK download page''
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png">]</span><br/>
:''Java download page''


===Eclipse_e-puck2===
===Eclipse_e-puck2===
#Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Win32_11_apr_2018.zip Eclipse_e-puck2 package for windows].
#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.
#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.
#You can now run the <code>Eclipse_e-puck2.exe</code> to launch Eclipse.
#You can now run the <code>Eclipse_e-puck2.exe</code> to launch Eclipse.
#You can create a shortcut to <code>Eclipse_e-puck2.exe</code> and place it anywhere if you want.
#You can create a shortcut to <code>Eclipse_e-puck2.exe</code> and place it anywhere if you want.


:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png">]</span><br/>
:<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''
:''Eclipse_e-puck2 folder obtained after extraction''


Line 48: Line 51:
===Java 8===
===Java 8===
This section can be ignored if Java is already installed on your computer.<br>
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:
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>
<pre>update-java-alternatives -l</pre>
You need to have <code>Java 1.8.xxxx</code> listed to be able to run <code>Eclipse_e-puck2</code>.
If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
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:
Type the following commands in a terminal session to install Java SDK:
Line 60: Line 61:
===Eclipse_e-puck2===
===Eclipse_e-puck2===
#Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
#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 [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz 32bits] / [http://projects.gctronic.com/epuck2//Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_64bits.tar.gz 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 i686 (32bit) or x86_64 (64 bit).   
#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).
#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.
#You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.


:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png">]</span><br/>
:<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''
:''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.
Note : The icon of the <code>Eclipse_e-puck2</code> executable will appear after the first launch of the program.


'''Important things to avoid :'''
'''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 resource located in the Eclipse_e-puck2 folder.
: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.
:2. The path to the Eclipse_e-puck2 folder must contain zero space.  
:2. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.  
::Example :
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK  
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK  
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> 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.
: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.


===Configuring the PATH variable===
===Configuring the PATH variable===
Line 86: Line 87:
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.
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.


If you want to set the <code>PATH</code> variable permanently, then ...
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>
<code>echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile</code><br>
Close and reopen the terminal before using your newly set environment variable.


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.
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.
Line 92: Line 95:
==Installation for Mac==
==Installation for Mac==
===Command Line Tools ===
===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.<br>
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>
You can install it by typing the following command in a terminal window. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.
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.
<pre>xcode-select --install</pre>


===Java 8===
===Java 8===
This section can be ignored if Java is already installed on your computer.<br>
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. It will list all the Java runtimes installed on your Mac.
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>
<pre>/usr/libexec/java_home -V</pre>
You need to have <code>AdoptOpenJDK 8</code> listed to be able to run <code>Eclipse_e-puck2</code>.
You need to have <code>Java SE 8</code> listed to be able to run Eclipse_e-puck2.
 
:1. Go to the [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java download page] and download the <code>Mac OS X Java 8 SE Development Kit</code>. It is the .dmg file without the Demos and Samples.
::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
:2. Open the .dmg file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.


:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png">]</span><br/>
# 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).
:''Java download page''
# 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''


===Eclipse_e-puck2===
===Eclipse_e-puck2===
:1. Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_11_apr_2018.dmg Eclipse_e-puck2 package for Mac].
: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 .dmg file downloaded and DragAndDrop the Eclipse_e-puck2.app into the Applications folder
: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 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.
::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 Eclipse_e-puck2.app and place it anywhere if you want.
:3. You can create an Alias to <code>Eclipse_e-puck2.app</code> and place it anywhere if you want.


===First launch and Gatekeeper===
===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.<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>
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>
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>
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 Gatekeeper.
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>.


To do so :
To do so :
Line 124: Line 123:
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.


::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png">]</span><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/>
::''Security settings of Mac OS''
::''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.
::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.
::<pre>sudo spctl --master-disable</pre>
::<code>sudo spctl --master-disable</code>
:2. Now you can try to run the application and it should work.
: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.
:3. If Eclipse opened successfully, it is time to reactivate <code>Gatekeeper</code>. Simply set back the setting of <code>Gatekeeper</code>.
::For the ones who needed to type a command to disable Gatekeeper, here is the command to reactivate it.
::For the ones who needed to type a command to disable <code>Gatekeeper</code>, here is the command to reactivate it.
::<pre>sudo spctl --master-enable</pre>
::<code>sudo spctl --master-enable</code>


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.
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>.


'''Important things to avoid :'''
'''Important things to avoid :'''
:1. The path to the Eclipse_e-puck2.app must contain zero space.  
:1. The path to the <code>Eclipse_e-puck2.app</code> must contain zero space.  
::Example :
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK  
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK  
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> 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.
: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.


===Configuring the PATH variable===
===Configuring the PATH variable===
Line 149: Line 148:


<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>
<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>
If you put the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder then the exact command would be:
<code>export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>


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.
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.


If you want to set the <code>PATH</code> variable permanently, then ...
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>
<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>
Close and reopen the terminal before using your newly set environment variable.


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.
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.
Line 165: Line 170:
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.


This repository contains the main microcontroller standard firmware together with the e-puck2 library. This library includes all the functions needed to interact with the robot's sensors and actuators; the standard firmware shows how to use these functions.<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/>


A snapshot of the repository can be donwloaded from [http://projects.gctronic.com/epuck2/e-puck2_main-processor_snapshot_16.02.18_13fa922.zip e-puck2_main-processor_snapshot_16.02.18.zip].<br/>
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/>


=Creating a project=
=Creating a project=
==Main microcontroller standard firmware project==
==Main microcontroller factory firmware project==
[https://github.com/e-puck2/e-puck2_main-processor.git e-puck2_main-processor] is the basic standard project containing all the libraries written for the e-puck2. Refer to the [http://www.gctronic.com/doc/index.php?title=e-puck2#Library Library] section to download the complete version.<br>
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/>
The basic standard project shows how to use the libraries and can be interfaced with [[#PC interface | e-puck2 monitor]].<br/>
:1 Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
This project can be added to Eclipse_e-puck2 by following the next steps:<br>  
::<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/>
# Run Eclipse and then select '''File->New->Makefile Project with Existing Code'''.
: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.
# Next choose the project folder and set a project name (otherwise you can keep the one created by Eclipse). Choose '''None''' for the the toolchain.
:3 Click on the <code>Finish</code> button and the project is added to Eclipse.
# Click on the '''Finish''' 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>.


==Project template==
==Project template==
The basic standard project can also be used as a library to build your own project on top of it.<br>
The main microcontroller factory firmware project can also be used as a library to build your own project on top of it.<br>


To accomplish that, you have to copy the folder '''Project_template''', contained in the e-puck2_main-processor project, where you want to place your project.<br>
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>
You can of course rename the folder to the name you want.<br>
* e-puck2
** e-puck2_main-processor
** myproject


The next step is to edit the makefile of your project. Set the name of your project, write the updated path to the e-puck2_main-processor folder, and also rewrite the path to the .c files. Lastly, include the path for any desired .h files from other folders.<br>
Then you can add this project in Eclipse by following the next steps:
All the .h files 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.
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
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.
# 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.
# 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).


The result of the compilation will appear in a build folder in your project folder.
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/>
 
In the <code>makefile</code> you can also set the name of your project.<br/>
==Adding to Eclipse_epuck2==
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.
#To add the project into Eclipse, you need to select '''File->New->Makefile Project with Existing Code'''.
#Next choose your project folder and set a project name. Choose '''None''' for the the toolchain.
#Click on the '''Finish''' button and the project is added to Eclipse.
#Rename the file '''Debug_project_template.launch''' contained in the project folder by the name you want for the debug configuration of your project.
#Go to '''Run->Debug Configurations...''' and select on the left your new debug configuration and set the project to debug and the path to the compiled file of the project ([[#Configuring the Debugger's settings |as explained in the chapter before]]). If there is nothing apering when you press '''Search Project...''' then you must enter the '''.elf''' file name by hand, which can be found in your project folder under a folder named '''build'''.
#Go to  '''Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers''' and Check '''CDT Cross GCC Built-in Compiler Settings'''.<br> Then in the textbox below, write '''arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"'''.
#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.
##Go to '''File->New->Folder'''.
##Check '''Advanced >>''' on the bottom.
##Choose '''Link to alternate location (Linked Folder)'''.
##Type '''PROJECT_LOC''' and then add to this path the path to the e-puck2_main-processor folder. For example '''PROJECT_LOC/../e-puck2_main-processor''' if the library is located as the same level as your project folder.
#Before you compile, make sure the robot is turned on, and in addition make sure that the Makefile, has a capital M in the front.
#After you compile the project and if it succeeded, 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.)
 
You should now be able to use the project with Eclipse.


=Configuring the Debugger's settings=
=Configuring the Debugger's settings=
<code>Eclipse_e-puck2</code> contains everything needed to compile, program and debug the e-puck2.<br>
<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 '''Debug Configurations''' tab of Eclipse (you can also find it on '''Run->Debug Configurations''').  
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">[http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png <img width=231 src="http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png">]</span><br/>
:<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 '''Generic Blackmagic Probe''' preset on the left panel. Then you need to configure two things :
Once in the settings, select <code>Generic Blackmagic Probe</code> preset on the left panel. Then you need to configure two things :
 
# 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>).
# 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].
:* 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.


:1 If you already have a project opened in Eclipse, under the <code>main</code> tab, you need to select which project to debug and the path to the compiled file.<br/>
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/>
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/>
:<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/>
If you do not already have a project, add a random name as the title which will act as a place holder, allowing you to apply the next configuration.
:2 Under the '''Startup''' tab, you need to replace the path to the serial port written on the first line of the text box by the one used by the GDB Server of your e-puck. [[#Finding the USB serial ports used | 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.<br>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.<br>Using the variable COM_PORT instead of the real com port in a debug configuration is useful if you have multiple debug configurations for example. If for one reason you need to change the com port to use, then you can simply edit the variable COM_PORT instead of editing the com port for each debug configuration


If you want to debug another project, you can change the settings of the '''Generic Blackmagic Probe''' preset or copy it into another preset and configure this one in order to have one preset by project.
Now you should be able to use the debugger with Eclipse.
Now you should be able to use the debugger with Eclipse.


=Flashing the main microcontroller=
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.
In order to update the firmware of the main microcontroller (STM32F407) you can either use Eclipse (as explained in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_Debugger.27s_settings Configuring the Debugger settings]) or you can do it manually as explained in this section. The onboard programmer run a gdb server, so we can use gdb commands to upload a new firmware.<br/>
 
1. download the gdb init file [http://projects.gctronic.com/epuck2/mygdbinit mygdbinit] and place it in the same folder of the compiled firmware. This file has the following content:
=Running a debugging session=
<pre>target extended-remote \\.\COM72
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].
monitor swdp_scan
 
attach 1
To start a session follow the next steps:
set mem inaccessible-by-default off
# Connect the robot to the computer and turn it on
load</pre>
# 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/>
In this file you need to change the port to reflect the one of the <code>GDB server</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]).
# 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>
 
==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 <code>EmbSys Registers</code> tab on the top right side of the <code>Debug perspective</code>.
<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>
 
==Bluetooth debugging session==
It is possible to run a debugging session remotely thorugh Bluetooth following these steps:
# 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>
# pair the robot with the computer
# 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]
# 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.<br/>
 
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/>
 
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 [https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Get_the_source_code Get the source code].<br/>
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 [http://www.gctronic.com/doc/index.php/Others_Extensions#Range_and_bearing 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 [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.
 
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)].
 
===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===
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/>
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
 
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_synchronize</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).
 
==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.
 
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)].
 
===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).<br/>
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/>
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/>
You can try different paths and also add more robots with slighly modifications to the code, this is only a starting point.<br/>
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:  <code>git clone https://github.com/e-puck2/e-puck2_example_master_slave.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_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>
* e-puck2
** e-puck2_main-processor
** e-puck2_example_master_slave
 
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_master_slave</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).
 
=Example projects=
==Digital Signal Processing (DSP) and wav playback==
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/>
 
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)].
 
===Usage===
There are basically two demos in this example, one run on selector position 0 and the other in selector position 1.<br/>
 
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/>
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/>
 
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/>
 
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.
 
===Building===
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/>
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_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>
* e-puck2
** e-puck2_main-processor
** e-puck2_example_dsp
 
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).
 
==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/>
 
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)].
 
===Usage===
The example requires a micro SD (FAT32) inserted in the robot.<br/>
 
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/>
 
You can choose whether to get an higher or lower pitch by changing the <code>TIME_SCALE</code> parameter in <code>sola.c</code>:
* if you want to get an higher pitch, then change <code>TIME_SCALE</code> to a value > 1.0
* if you want to get a lower pitch, then change the <code>TIME_SCALE</code> 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:  <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
 
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_pitch_scale</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).
 
==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 https://github.com/e-puck2/e-puck2_cpp].<br/>
The example demonstrates simple usage of a class and for range loops.
 
===Building===
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 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_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>
* e-puck2
** e-puck2_main-processor
** e-puck2_cpp
 
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).
 
==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:  <code>git clone https://github.com/e-puck2/e-puck2_example_bluetooth_echo.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_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
 
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_bluetooth_echo</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).
 
==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 https://github.com/e-puck2/e-puck-2-footy].
 
=Firmware update using factory bootloader=
==Factory firmware==
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_26.04.23_f4f3582.bin  main microcontroller factory firmware.bin (26.04.23)]; it is also available in dfu format here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_26.04.23_f4f3582.dfu main microcontroller factory firmware.dfu (26.04.23)].
 
==Firmware update==
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/>
 
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.
 
::<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/>
::''Location of the button to put the main microcontroller into DFU''
 
The main microcontroller will be recognized as <code>STM Device in DFU Mode</code> device.


2. issue the following command to start the upload
'''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>
<pre>Windows: arm-none-eabi-gdb.exe --interpreter=mi -x mygdbinit firmware.elf
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/>
Linux/Mac: arm-none-eabi-gdb --interpreter=mi -x mygdbinit firmware.elf</pre>
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>.
In this command you need to change the name of the firmware with the one you have.<br/>
Moreover if the <code>PATH</code> variable is not set (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_PATH_variable Configuring the PATH variable]) you need to insert the absolute path to the debugger that you can find in the Eclipse package (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Installation_of_the_e-puck2_environment Installation of the e-puck2 environment]) inside the directory <code>Tools\gcc-arm-none-eabi-XXX\bin</code>.


When the upload is complete you'll see an output like in the following figure:<br/>
===Linux/Mac===
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png">]</span><br/>
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/>
The final line should contain <code>".data",</code> , and it should all be enclosed at the end with <code>(gdb)</code>. You can then close the terminal window.
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).


If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.
===Windows===
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/>
<span class="plainlinks">
<table>
<tr>
<td align="center">[1]</td>
<td align="center">[2]</td>
<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/>

Latest revision as of 10:29, 3 October 2024

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) or you can directly download it from OpenJDK8U-jdk_x86-32_windows_hotspot_8u422b05.msi.
  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 (26.04.23); it is also available in dfu format here main microcontroller factory firmware.dfu (26.04.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]