e-puck2

e-puck2 main wiki

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 can open the Programs and Features panel and search for a Java 8 Update xxx install.

1. Go to the Java download page and download "Windows offline" This is the 32bits version of Java.
2. Run the downloaded installer and follow its instructions to proceed with the installation of Java 32bits.
3. Close the internet browser if it opened at the end of the installation.

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

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

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. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.

xcode-select --install

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 Java SE 8 listed to be able to run Eclipse_e-puck2.

1. Go to the Java download page and download the Mac OS X Java 8 SE Development Kit. It is the .dmg file without the Demos and Samples.

For example: jdk-8uXXX-macosx-x64.dmg

2. Open the .dmg file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.

Java download page

Eclipse_e-puck2

1. Download the Eclipse_e-puck2 package for Mac.

2. Open the .dmg file downloaded and DragAndDrop 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.

Get the source code

The source code is available in the git repo https://github.com/e-puck2/e-puck2_main-processor.

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 tab 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. If you already have a project, under the main tab, you need to select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse must have indexed the binaries and you can list the project and the compiled files using respectively the Browse... and Search Project... buttons. 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. 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 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.

Creating a project

Basic standard project

e-puck2_main-processor is the basic standard project containing all the libraries written for the e-puck2. Refer to the Library section to download the complete version.
The basic standard project shows how to use the libraries and can be interfaced with e-puck2 monitor.
This project can be added to Eclipse_e-puck2 by following the next steps:

1. Run Eclipse and then select File->New->Makefile Project with Existing Code.
2. 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 Finish button and the project is added to Eclipse.

Project template

The basic standard 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, where you want to place your project.
You can of course rename the folder to the name you want.

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

The result of the compilation will appear in a build folder in your project folder.

Adding to Eclipse_epuck2

1. To add the project into Eclipse, you need to select File->New->Makefile Project with Existing Code.
2. Next choose your project folder and set a project name. Choose None for the the toolchain.
3. Click on the Finish button and the project is added to Eclipse.
4. Rename the file Debug_project_template.launch contained in the project folder by the name you want for the debug configuration of your project.
5. 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 (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.
6. 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}".
7. 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. Go to File->New->Folder.
   2. Check Advanced >> on the bottom.
   3. Choose Link to alternate location (Linked Folder).
   4. 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.
8. 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.
9. 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.

Flashing the main microcontroller

In order to update the firmware of the main microcontroller (STM32F407) you can either use Eclipse (as explained in section 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.
1. download the gdb init file mygdbinit and place it in the same folder of the compiled firmware. This file has the following content:

target extended-remote \\.\COM72
monitor swdp_scan
attach 1
set mem inaccessible-by-default off
load

In this file you need to change the port to reflect the one of the GDB server (see chapter Finding the USB serial ports used).

2. issue the following command to start the upload

Windows: arm-none-eabi-gdb.exe --interpreter=mi -x mygdbinit firmware.elf
Linux/Mac: arm-none-eabi-gdb --interpreter=mi -x mygdbinit firmware.elf

In this command you need to change the name of the firmware with the one you have.
Moreover if the PATH variable is not set (see chapter Configuring the PATH variable) you need to insert the absolute path to the debugger that you can find in the Eclipse package (see chapter Installation of the e-puck2 environment) inside the directory Tools\gcc-arm-none-eabi-XXX\bin.

When the upload is complete you'll see an output like in the following figure:

The final line should contain ".data", , and it should all be enclosed at the end with (gdb). You can then close the terminal window.

If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.