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

From GCtronic wiki
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
=Hardware=
=Introduction=
==Overview==
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>
<span class="plainlinks">[http://www.gctronic.com/doc/images/e-puck2-overview.png <img width=500 src="http://www.gctronic.com/doc/images/e-puck2-overview_small.png">]</span>
Before starting to code, you need to install the developing environment and its dependencies, all the steps are documented afterwards.<br>
<span class="plainlinks">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-features.png <img width=600 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-features_small.png">]</span><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=
The following figures show the main components offered by the e-puck2 robot and where they are physically placed:<br/>
<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'''.
<span class="plainlinks">[https://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png <img width=800 src="https://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position_small.png">]</span><br/>


==Installation for Windows==
==Specifications==
===Java 8 32bits===
The e-puck2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):
This section can be ignored if Java version >= 8 32bits is already installed on your computer.<br>
{| border="1"
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:
|'''Feature'''
# 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).
|'''e-puck1.3'''
# Run the downloaded installer and follow its instructions to proceed with the installation of OpenJDK 32bits.
|'''e-puck2'''
:<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/>
|'''Compatibility'''
:''OpenJDK download page''
|'''Additional'''
|-
|Size, weight
|70 mm diameter, 55 mm height, 150 g
|Same form factor: 70 mm diameter, 45 mm, 130 g
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|No e-jumper required
|-
|Battery, autonomy
|LiIPo rechargeable battery (external charger), 1800 mAh. <br/>About 3 hours autonomy. Recharging time about 2-3h.
|Same battery; USB charging, recharging time about 2.5h.
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|USB charging
|-
|Processor
|16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing
|32-bit STM32F407 @ 168 MHz (210 DMIPS), DSP and FPU, DMA
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|~10 times faster
|-
|Memory
|RAM: 8 KB; Flash: 144 KB
|RAM: 192 KB; Flash: 1024 KB
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|RAM: 24x more capable<br/>Flash:~7x more capable
|-
|Motors
|2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution
|Same motors
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Wheels
|Wheels diamater = 41 mm <br/>Distance between wheels = 53 mm
|Same wheels
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Speed
|Max: 1000 steps/s (about 12.9 cm/s)
|Max: 1200 steps/s (about 15.4 cm/s)
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|20% faster
|-
|Mechanical structure
|Transparent plastic body supporting PCBs, battery and motors
|Same mechanics
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Distance sensor
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm
|Same infra-red sensors <br/>Front real distance sensor, Time of fight (ToF), up to 2 meter.
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|ToF sensor
|-
|IMU
|3D accelerometer and 3D gyro
|3D accelerometer, 3D gyro, 3D magnetometer
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|3D magnetometer
|-
|Camera
|VGA color camera; typical use: 52x39 or 480x1
|Same camera; typical use: 160x120
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|Bigger images handling
|-
|Audio
|3 omni-directional microphones for sound localization<br/>speaker capable of playing WAV or tone sounds
|4 omni-directional microhpones (digital) for sound localization<br/>speaker capable of playing WAV or tone sounds
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
| +1 front microphone
|-
|LEDs
|8 red LEDs around the robot, green body light, 1 strong red LED in front
|4 red LEDs and 4 RGB LEDs around the robot, green light, 1 strong red LED in front
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|4x RGB LEDs
|-
|Communication
|RS232 and Bluetooth 2.0 for connection and programming
|USB Full-speed, Bluetooth 2.0, BLE, WiFi
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|WiFi, BLE
|-
|Storage
|Not available
|Micro SD slot
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|Micro SD
|-
|Remote Control
|Infra-red receiver for standard remote control commands
|Same receiver
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Switch / selector
|16 position rotating switch
|Same selector
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Extensions
|Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own
|All extension supported
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
|
|-
|Programming
|Free C compiler and IDE, Webots simulator, external debugger
|Free C compiler and IDE, Webots simulator, onboard debugger (GDB)
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
|Onboard debugger
|}


===Eclipse_e-puck2===
This is the overall communication schema:<br/>
#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].
<span class="plainlinks">[http://www.gctronic.com/doc/images/comm-overall-e-puck2E.jpg <img width=700 src="http://www.gctronic.com/doc/images/comm-overall-e-puck2E.jpg">]</span><br/>
#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 create a shortcut to <code>Eclipse_e-puck2.exe</code> and place it anywhere if you want.


:<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/>
==Documentation==
:''Eclipse_e-puck2 folder obtained after extraction''
* '''Main microcontroller''': STM32F407, [https://projects.gctronic.com/epuck2/doc/STM32F407xx_datasheet.pdf datasheet], [https://projects.gctronic.com/epuck2/doc/STM32F407_reference-manual.pdf reference-manual]
* '''Programmer/debugger''': STM32F413, [https://projects.gctronic.com/epuck2/doc/STM32F413x_datasheet.pdf datasheet], [https://projects.gctronic.com/epuck2/doc/STM32F413_reference-manual.pdf reference-manual]
* '''Radio module''': Espressif ESP32, [https://projects.gctronic.com/epuck2/doc/esp32_datasheet_en.pdf datasheet], [https://projects.gctronic.com/epuck2/doc/esp32_technical_reference_manual_en.pdf reference-manual]
* '''Camera''': PixelPlus PO8030D CMOS image sensor, [https://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf datasheet], no IR cut filter
: From about July 2019, the camera mounted on the e-puck2 robot is the Omnivision OV7670 CMOS image sensor, [https://projects.gctronic.com/epuck2/doc/OV7670.pdf datasheet]
* '''Microphones''': STM-MP45DT02, [https://projects.gctronic.com/epuck2/doc/mp45dt02.pdf datasheet]
* '''Optical sensors''': Vishay Semiconductors Reflective Optical Sensor, [https://projects.gctronic.com/epuck2/doc/tcrt1000.pdf datasheet]
* '''ToF distance sensor''': STM-VL53L0X, [https://projects.gctronic.com/epuck2/doc/VL53L0X-Datasheet.pdf datasheet], [https://projects.gctronic.com/epuck2/doc/VL53L0X-UserManual-API.pdf user-manual]
* '''IMU''': InvenSense MPU-9250, [https://projects.gctronic.com/epuck2/doc/MPU-9250-product-specification.pdf product-specification], [https://projects.gctronic.com/epuck2/doc/MPU-9250-Register-Map.pdf register-map]
* '''Motors''': [http://www.e-puck.org/index.php?option=com_content&view=article&id=7&Itemid=9 details]
* '''Speaker''': Diameter 13mm, power 500mW, 8 Ohm, DS-1389 or PSR12N08AK or similar
* '''IR receiver''': TSOP36230


'''Important things to avoid :'''
==Migrating from e-puck1.x to e-puck2==
:1. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.
The e-puck2 robot maintains full compatibility with its predecessor e-puck, but there are some improvements that you should be aware of.<br/>
::Example :
::<code>C:\epfl_stuff\Eclipse_e-puck2</code> OK
::<code>C:\epfl stuff\Eclipse_e-puck2</code> NOT OK
:2. You must not put <code>Eclipse_e-puck2</code> folder into <code>Program Files (x86)</code>. Otherwise the compilation when using Eclipse will not work.
:3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.


===Configuring the PATH variable===
First of all the e-jumper, that is the small board that is attached on top of the e-puck1.x, isn't anymore needed in the e-puck2. The components available on the e-jumper are integrated directly in the robot board. On top of the e-puck2 you'll see a quite big free connector, this is used to attach the extensions board designed for the e-puck1.x that are fully compatible with the e-puck2; you must not connect the e-jumper in this connector.<br/>
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
Secondly you don't need anymore to unplug and plugin the battery for charging, but instead you can charge the battery (up to 1 ampere) directly by connecting the USB cable. If you want you can still charge the battery with the e-puck1.x external charger, in case you have more than one battery.<br/>


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
Moreover you don't need anymore a special serial cable (with probably an RS232 to USB adapter) to be able to communicate with the robot, but you can use the USB cable. Once connected to the computer a serial port will be available that you can use to easily exchange data with the robot.


<code>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</code>
==Extensions==
All the extensions (ground sensors, range and bearing, RGB panel, gumstix and omnvision) are supported by the e-puck2 robot, this means that if you have some extensions for the e-puck1.x you can still use them also with e-puck2.<br/>
For more information about using the gumstix extension with e-puck2 robot refer to [http://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2 http://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2].


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.
=Getting Started=
The e-puck2 robot features 3 chips onboard:
* the main microcontroller, that is responsible for handling the sensors and actuators and which runs also the demos/algorithms
* the programmer, that provides programming/debugging capabilties and moreover it configures the USB hub and is responsible for the power management (on/off of the robot and battery measure)
* radio module, that is responsible for handling the wireless communication (WiFi, BLE, BT), the RGB LEDs and the user button (the RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller)


If you want to set the <code>PATH</code> variable permanently, then go to <code>Control panel</code> => <code>System</code> => <code>Advanced system settings</code> => <code>Environment variables</code>. A list of variables defined for the user is shown, double click on the <code>PATH</code> variable (from the user variables list) and add at the end <code>;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin</code>, then click <code>OK</code> three times.
The robot is shipped with the last firmware version programmed on all 3 chips, so you can immediately start using the robot.<br/>
The following sections explain the basic usage of the robot, <b>all the users should read this chapter completely in order to have a minimal working system ready to play with the e-puck2 robot</b>. Some sections will have more detailed information that can be read by following the links provided.


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.
When required, dedicated informations are given for all platforms (Windows, Linux, Mac). The commands given for Linux are related to the Ubuntu distribution, similar commands are available in other distributions.  


==Installation for Linux==
==Turn on/off the robot==
===Java 8===
To turn on the robot you need to press the power button (blue button) placed on the bottom side of the board, near the speaker, as shown in the following figures:
This section can be ignored if Java is already installed on your computer.<br>
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-btn-on-off2.jpg <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-btn-on-off2-small.jpg">][https://projects.gctronic.com/epuck2/wiki_images/e-puck2-btn-on-off.jpg <img width=300 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-btn-on-off-small.jpg">]</span><br/>
To verify whether it is installed or not you can type the following command into a terminal window: <code>update-java-alternatives -l</code>. If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
To turn off the robot you need to press the power button for 1 second.
You need to have <code>Java 1.8.xxxx</code> listed to be able to run <code>Eclipse_e-puck2</code>.


Type the following commands in a terminal session to install Java SDK:
==Meaning of the LEDs==
<pre>sudo add-apt-repository ppa:openjdk-r/ppa
The e-puck2 has three groups of LEDs that are not controllable by the user.
sudo apt-get update
sudo apt-get install openjdk-8-jre </pre>


===Eclipse_e-puck2===
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds.png">]</span><br/>
#Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
::''Top view of the e-puck2''
#Download the Eclipse_e-puck2 package for Linux [https://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz 32bits] / [https://github.com/e-puck2/Create_Eclipse_e-puck2/releases/download/14_aug_2020/Eclipse_e-puck2_Linux64_14_aug_2020.tar.xz 64bits]. Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand <code>uname -a</code> in the terminal window and look for <code>i686</code> (32bit) or <code>x86_64</code> (64 bit). 
#Extract the downloaded file to the location you want (can take time): <code>tar -zxvf package_name.tar.gz</code>
#You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.


:<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/>
*Charger: RED if charging, GREEN if charge complete and RED and GREEN if an error occurs
:''Eclipse_e-puck2 folder obtained after extraction''
*USB: Turned ON if the e-puck2 detects a USB connection with a computer
*STATUS: Turned ON if the robot is ON and OFF if the robot is OFF. When ON, gives an indication of the level of the battery. Also blinks GREEN if the program is running during a debug session.


Note : The icon of the <code>Eclipse_e-puck2</code> executable will appear after the first launch of the program.
Battery level indications (STATUS RGB LED):
*GREEN if the system's tension is greater than 3.5V
*ORANGE if the system's tension is between 3.5V and 3.4V
*RED if the system's tension is between 3.4V and 3.3V
*RED blinking if the system's tension is below 3.3V


'''Important things to avoid :'''
The robot is automatically turned OFF if the system's tension gets below 3.2V during 10 seconds.
: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 <code>Eclipse_e-puck2</code> folder must contain zero space.
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
: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===
==Connecting the USB cable==
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
A micro USB cable (included with the robot in the package) is needed to connect the robot to the computer. There are two connectors, one placed on top of the robot facing upwards and the other placed on the side of the robot, as shown in the following figures. Both can be used to charge the robot (up to 1 ampere) or to communicate with it, but do not connect two cables at the same time. Connect the USB cable where is more comfortable to you.
::<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-usb-conn.jpg <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-usb-conn-small.jpg">][https://projects.gctronic.com/epuck2/wiki_images/e-puck2-usb-conn2.jpg <img width=300 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-usb-conn2-small.jpg">]</span><br/>


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
==Installing the USB drivers==
The USB drivers must be installed only for the users of a Windows version older than Windows 10:


<code>export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
#Download and open [https://projects.gctronic.com/epuck2/zadig-2.3.exe zadig-2.3.exe]
#Connect the e-puck2 with the USB cable and turn it on. Three unknown devices appear in the device list of the program, namely '''e-puck2 STM32F407''', '''e-puck2 GDB Server (Interface 0)''' and '''e-puck2 Serial Monitor (Interface 2)'''.
#For each of the three devices mentioned above, select the <code>USB Serial (CDC)</code> driver and click on the <code>Install Driver</code> button to install it. Accept the different prompts which may appear during the process. At the end you can simply quit the program and the drivers are installed. These steps are illustrated on Figure 3 below.
::Note : The drivers installed are located in <code>C:\Users\"your_user_name"\usb_driver</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.
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/Zadig_e-puck2_STM32F407.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/Zadig_e-puck2_STM32F407.png">]</span><br/>
::''Example of driver installation for e-puck2 STM32F407''


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>
The drivers are automatically installed with Windows 10, Linux and Mac OS.
<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.
Anyway in Linux in order to access the serial ports, a little configuration is needed. Type the following command in a terminal session: <code>sudo adduser $USER dialout</code>. Once done, you need to log off to let the change take effect.


==Installation for Mac==
==Finding the USB serial ports used==
===Command Line Tools ===
Two ports are created by the e-puck2's programmer when the USB cable is connected to the robot (even if the robot is turned off):
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>
* '''e-puck2 GDB Server'''. The port used to program and debug the e-puck2.
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.
* '''e-puck2 Serial Monitor'''. Serial communication between the PC and the radio module (used also to program the radio module).


===Java 8===
A third port could be available depending on the code inside the e-puck2's microcontroller. With the factory firmware a port named '''e-puck2 STM32F407''' is created.
This section can be ignored if Java is already installed on your computer.<br>
===Windows===
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>
#Open the Device Manager
You need to have <code>AdoptOpenJDK 8</code> listed to be able to run <code>Eclipse_e-puck2</code>.
#Under '''Ports (COM & LPT)''' you can see the virtual ports connected to your computer.
#Do a '''Right-click -> properties''' on the COM port you want to identify.
#Go under the '''details''' tab and select '''Bus reported device description''' in the properties list.
#The name of the port should be written in the text box below.
#Once you found the desired device, you can simply look at its port number '''(COMX)'''.


# 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).
===Linux===
# Open the <code>.pkg</code> file downloaded and follow the instructions to proceed with the installation of OpenJDK.
:1. Open a terminal window (<code>ctrl+alt+t</code>) and enter the following command: <code>ls /dev/ttyACM*</code>
:<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/>
:2. Look for '''ttyACM0''' and '''ttyACM1''' in the generated list, which are respectively '''e-puck2 GDB Server''' and '''e-puck2 Serial Monitor'''. '''ttyACM2''' will be also available with the factory firmware, that is related to '''e-puck2 STM32F407''' port
:''OpenJDK download page''
Note : Virtual serial port numbering on Linux depends on the connections order, thus it can be different if another device using virtual serial ports is already connected to your computer before connecting the robot, but the sequence remains the same.


===Eclipse_e-puck2===
===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].
:1. Open a terminal window and enter the following command: <code>ls /dev/cu.usbmodem*</code>
: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
:2. Look for two '''cu.usbmodemXXXX''', where XXXX is the number attributed by your computer. You should find two names, with a numbering near to each other, which are respectively '''e-puck2 GDB Server''' (lower number) and '''e-puck2 Serial Monitor''' (higher number). A third device '''cu.usbmodemXXXX''' will be available with the factory firmware, that is related to '''e-puck2 STM32F407''' port
::Note: you can place the <code>Eclipse_e-puck2.app</code> anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in <code>Applications</code>.
:3. You can create an Alias to <code>Eclipse_e-puck2.app</code> and place it anywhere if you want.


===First launch and Gatekeeper===
Note : Virtual serial port numbering on Mac depends on the physical USB port used and the device. If you want to keep the same names, you must connect to the same USB port each time.
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 <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 :
==PC interface==
<span class="plainlinks">[https://projects.gctronic.com/epuck2/wiki_images/monitor.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/monitor_small.png">]<br/>
A PC application was developed to start playing with the robot attached to the computer via USB cable: you can have information about all the sensors, receive camera images and control the leds and motors.<br/>
Beware that it's not mandatory to download this application in order to work with the robot, but it is a nice demo that gives you an overview of all the sensors and actuators available on the robot, this is a first step to gain confidence with the robot.<br/>


:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
With the factory firmwares programmed in the robot, place the selector in position 8, attach the USB cable and turn on the robot. Enter the correct port (the one related to <code>e-puck2 STM32F407</code>) in the interface and click <code>connect</code>.


::<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/>
The source code is available from the repository [https://github.com/e-puck2/monitor https://github.com/e-puck2/monitor].<br/>
::''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.
===Available executables===
::<code>sudo spctl --master-disable</code>
* [https://projects.gctronic.com/epuck2/monitor_win.zip Windows executable]: tested on Windows 7 and Windows 10
:2. Now you can try to run the application and it should work.
* [https://projects.gctronic.com/epuck2/monitor_mac.zip Max OS X executable]
:3. If Eclipse opened successfully, it is time to reactivate <code>Gatekeeper</code>. Simply set back the setting of <code>Gatekeeper</code>.
* [https://projects.gctronic.com/epuck2/monitor_linux64bit.tar.gz Ubuntu 14.04 (or later) - 64 bit]
::For the ones who needed to type a command to disable <code>Gatekeeper</code>, here is the command to reactivate it.
On Linux remember to apply the configuration explained in the chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers Installing the USB drivers] in order to access the serial port.
::<code>sudo spctl --master-enable</code>


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>.
==Installing the dependencies for firmwares updates==
You can update the firmware for all 3 chips: the main microcontroller, the radio module and the programmer. For doing that, you need some tools to be installed on the system.


'''Important things to avoid :'''
===Windows===
:1. The path to the <code>Eclipse_e-puck2.app</code> must contain zero space.
To upload a new firmware in the microcontroller or in the radio module, you don't need to install anything, the packages provided include all the dependencies.
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
:2. The file’s structure in the <code>Eclipse_e-puck2.app</code> must remain the same. It means no file inside this app must be moved to another place.


===Configuring the PATH variable===
To upload a new firmware in the programmer you need to install an application called <code>DfuSe</code> released by STMicroelectronics. You can download it from [https://projects.gctronic.com/epuck2/en.stsw-stm32080_DfuSe_Demo_V3.0.5.zip DfuSe_V3.0.5.zip].
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
===Linux===
To upload a new firmware in the microcontroller or in the radio module, you need:
* Python (>= 3.4): <code>sudo apt-get install python3</code>
* Python pip: <code>sudo apt-get install -y python3-pip</code>
* pySerial (>= 2.5): <code>sudo pip3 install pyserial</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>
To upload a new firmware in the programmer you need:
* dfu-util: <code>sudo apt-get install dfu-util</code>


If you put the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder then the exact command would be:
===Mac===
Install the [https://brew.sh Homewbrew] package manager by opening a terminal and issueing:<br/>
<code>/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"</code><br/>
and then:<br/>
<code>brew upgrade</code><br/>


<code>export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
To upload a new firmware in the microcontroller or in the radio module, you need:
* Python (>= 3.4): <code>brew install python</code> (it will install also <code>pip</code>)
* pySerial (>= 2.5): <code>pip3 install pyserial</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.
To upload a new firmware in the programmer you need:
* dfu-util: <code>brew install dfu-util</code>


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>  
==PC side development==
<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>
This section is dedicated to the users that develop algorithms on the PC side and interact with the robot remotely through a predefined communication protocol. These users don't modify the firmware of the robot, but instead they use the factory firmware released with the robot. They update the robot firmware only when there is an official update. <br/>
Close and reopen the terminal before using your newly set environment variable.
The remote control of the robot, by receiving sensors values and setting the actuators, is done through the following channels: Bluetooth, Bluetooth Low Energy, WiFi, USB cable.<br/>
Examples of tools/environment used by these users:
# Aseba
# Simulator (e.g. Webots)
# ROS
# iOS, Android apps
# Custom PC application
# IoT (e.g. IFTTT)
If you fall into this category, then follow this section for more information: [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development PC side development].<br/>


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.
=Main microcontroller=
The e-puck2 robot main microcontroller is a 32-bit STM32F407 that runs at 168 MHz (210 DMIPS) and include DSP, FPU and DMA capabilities. The version chosen for the e-puck2 has 192 KB of total RAM and 1024 KB of flash, so there is a lot of memory to work with.<br/>
This chip is responsible for handling the sensors and actuators and runs also the demos and algorithms.


=Get the source code=
==Factory firmware==
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:
The main microcontroller of the robot is initially programmed with a firmware that includes many demos that could be started based on the selector position, here is a list of the demos with related position and a small description:
* Windows: downlaod git from [https://gitforwindows.org/ https://gitforwindows.org/] and follow the installation instructions (default configuration is ok)
* Selector position 0: Aseba
* Linux: issue the command <code>sudo apt-get install git</code>
* Selector position 1: Shell
* Mac: issue the command <code>brew install git</code>
* Selector position 2: Read proximity sensors and when an object is near a proximity, turn on the corresponding LED
* Selector position 3: Asercom protocol v2 (BT)
* Selector positoin 4: Range and bearing extension (receiver)
* Selector position 5: Range and bearing extension - clustering demo (simultaneous transmitter and receiver).
* Selector position 6: Move the robot back and forth exploiting the gyro, with LEDs animation
* Selector position 7: Play a wav (mono, 16 KHz) named "example.wav" from the micro sd when pressing the button
* Selector position 8: Asercom protocol v2 (USB)
* Selector position 9: Local communication: transceiver
* Selector position 10: this position is used to work with the Linux extensions. To work with gumstix refer to [http://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2 Overo Extension: e-puck2] , to work with Pi-puck refer to [http://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements Pi-puck: Requirements ].
* Selector position 11: Simple obstacle avoidance + some animation
* Selector position 12: Hardware test
* Selector position 13: LEDs reflect orientation of the robot
* Selector position 14: Compass
* Selector position 15: WiFi mode
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_10.12.21_52ffc6b.elf main microcontroller factory firmware (10.12.21)].


The source code can downloaded with the command: <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
==Firmware update==
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.
Now and then there could be an official firmware update for the robot and it's important to keep the robot updated with the last firmware to get possibile new features, improvements and for bug fixes.<br/>
The onboard programmer run a GDB server, so we use GDB commands to upload a new firmware, for this reason a toolchain is needed to upload a new firmware to the robot.<br/>
The following steps explain how to update the main microcontroller firmware:<br/>
1. Download the package containing the required toolchain and script to program the robot: [https://projects.gctronic.com/epuck2/e-puck2-prog-main-micro-windows.zip Windows], Linux [https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux32.tar.gz 32 bits]/[https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux64.tar.gz 64 bits], [https://projects.gctronic.com/epuck2/e-puck2-prog-main-micro-macos.zip Mac OS]<br/>
2. Download the last version of the [https://projects.gctronic.com/epuck2/e-puck2_main-processor_10.12.21_52ffc6b.elf main microcontroller factory firmware (10.12.21)], or use your custom firmware<br/>
3. Extract the package and put the firmware file (with <code>elf</code> extension) inside the package directory; beware that only one <code>elf</code> file must be present inside this directory<br/>
4. Attach the USB cable and turn on the robot<br/>
5. Run the script from the package directory:<br/>
:Windows: double click <code>program.bat</code><br/>
:Linux/Mac: issue the following command in a terminal <code>./program.sh</code>. If you get permission errors, then issue <code>sudo chmod +x program.sh</code> to let the script be executable.<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/>
When the upload is complete you'll see an output like in the following figure:<br/>
<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png">]</span><br/>
The final lines should contain the entry <code>".data",</code>, this means that the upload was successfull. You can then close the terminal window if it is still open.


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/>
If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.


=Creating a project=
==Robot side development==
==Main microcontroller factory firmware project==
If you are an embedded developer and are brave enough, then you have complete access to the source code running on the robot, so you can discover what happen inside the main microcontroller and modify it to accomodate your needs. Normally the users that fall into this category develop algorithms optimized to run directly on the microcontroller, such as:
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/>
# onboard image processing
:1 Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
# swarm algorithms
::<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/>
# fully autonomous behaviors
:2 Next click on the <code>Browse</code> button and choose the project folder of the git repository downloaded previously (should be named <code>e-puck2_main-processor</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
# ...
:3 Click on the <code>Finish</code> button and the project is added to Eclipse.
For more information about programming the robot itself, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development Robot side development]
::<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==
=Radio module=
The main microcontroller factory firmware project can also be used as a library to build your own project on top of it.<br>
The radio module chosen for the e-puck is the new ESP32 chip from [https://www.espressif.com/ Espressif], integrating a dual core that run up to 240 MHz, 4 MB of flash and 520 KB of RAM. It supports WiFi standards 802.11 b/g/n (access point mode supported), Bluetooth and Bluetooth LE 4.2. It is the successor of the ESP8266 chip. The following figure shows the various peripherals available on the ESP32:<br/>
<span class="plain links"><img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-peripherals.png"></span>


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>
This chip first of all is responsible for handling the wireless communication, moreover it handles also the RGB LEDs (with PWM) and the user button. The RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller.
* e-puck2
** e-puck2_main-processor
** myproject


Then you can add this project in Eclipse by following the next steps:
==Factory firmware==
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
The radio module of the robot is initially programmed with a firmware that supports Bluetooth communication.<br/>
# Next click on the <code>Browse</code> button and choose the project folder of your project (e.g. <code>myproject</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/esp32-firmware_11.12.18.zip radio module factory firmware (11.12.18)].
# 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).


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/>
==WiFi firmware==
In the <code>makefile</code> you can also set the name of your project.<br/>
At the moment the factory firmware supports only Bluetooth, if you want to work with WiFi you need to program the radio with a dedicated firmware, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi PC side development: WiFi].
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.


=Configuring the Debugger's settings=
==BLE firmware==
<code>Eclipse_e-puck2</code> contains everything needed to compile, program and debug the e-puck2.<br>
At the moment the factory firmware supports only calssic Bluetooth, if you want to work with Bluetooth Low Energy you need to program the radio with a dedicated firmware, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development Mobile phone development].
The only settings to configure with a new project are located under the <code>Debug Configurations</code> icon of Eclipse (you can also find it on <code>Run->Debug Configurations</code>).
:<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png <img width=231 src="https://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png">]</span><br/>
Once in the settings, select <code>Generic Blackmagic Probe</code> preset on the left panel. Then you need to configure two things :


# 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>).
==Firmware update==
# 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].
In order to update the firmware of the ESP32 WiFi module you need to use a python script called <code>esptool</code> provided by [https://www.espressif.com/ Espressif] (manufacturer of the chip). This script was modified to work with the e-puck2 robot and is included in the provided package. The following steps explain how to update the radio module firmware:<br/>
:* For Windows, it will be <code>\\.\COMX</code>, <code>X</code> being the port number.
1. Download the package containing the required tools and script to program the robot: [https://projects.gctronic.com/epuck2/e-puck2-prog-radio-windows.zip Windows], [https://projects.gctronic.com/epuck2/e-puck2-prog-radio-macos.zip Linux / Mac]<br/>
:* For Linux, it will be <code>/dev/ttyACMX</code>, <code>X</code> being the port number
2. Download the last version of the [https://projects.gctronic.com/epuck2/esp32-firmware_11.12.18.zip radio module factory firmware (11.12.18)], or use another firmware (e.g. WiFi, BLE, your own). The firmware is composed by 3 files named <code>bootloader.bin</code>, <code>ESP32_E-Puck_2.bin</code> and <code>partitions_singleapp.bin</code><br/>
:* For Mac, it will be <code>/dev/cu.usbmodemXXXXX</code>, <code>XXXXX</code> being the port number.
3. Extract the package and put the firmware files inside the package directory; beware that the name of the <code>.bin</code> files must be the same as indicated in step 2<br/>
:* 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.
4. Attach the USB cable and turn on the robot<br/>
 
5. Run the script from the package directory:<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/>
:Windows: double click <code>program.bat</code><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/>
:Linux/Mac: issue the following command in a terminal <code>./program.sh</code>. If you get permission errors, then issue <code>sudo chmod +x program.sh</code> to let the script be executable.<br/>
 
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 <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.
 
=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 [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update].
 
To start a session follow the next steps:
# Connect the robot to the computer and turn it on
# From Eclipse, launch the debug configuration previously set: from the menu <code>Run->Debug configurations...</code>, select the configuration and click on the <code>Debug</code> button.<br>Alternatively you can directly select your configuration from the debugger drop-down menu.<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png <img width=350 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png">]</span><br/>
# When the debugging session is started, Eclipse will change the view to the <code>Debug perspective</code>. Right-click on the main process and select <code>Restart</code> to restart the program from the beginning<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3-small.png">]</span>
# Click on the <code>Resume</code> button on top of the window to start your program. Now you can suspend and resume whenever you want, then when you want to modify your code again you click on the <code>Terminate</code> button and click on the <code>C/C++ perspective</code> button.<br><span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4.png <img width=500 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4-small.png">]</span>
 
==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-puck1 robots and it keeps retro-compatibility. This means that an e-puck1 is able to communicate with an e-puck2, so you can still use your e-puck1 robots together with e-puck2 to form a bigger fleet of robots for your experiments. Moreover the API is the same, thus the code developed for the e-puck1 can be used easily also with the e-puck2.<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-puck1 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 upload should last about 10-15 seconds and you'll see the progress as shown in the following figure:<br/>
The example requires a micro SD (FAT32) inserted in the robot.<br/>
<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing1.png <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing1.png">]</span><br/>
When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure:<br/>
<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing2.png <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing2.png">]</span><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
Sometime you could encounter a timeout error as shown in the following figures; in these cases you need to unplug and plug again the USB cable and power cycle the robot, then you can retry.<br/>
file. Once the recording is finished, the pitch scale is applied and then the modified voice is played.<br/>
<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing3.png <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing3.png">]</span>
<span class="plain links">[https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing4.png <img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-flashing4.png">]</span><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>:
==Development==
* if you want to get an higher pitch, then change <code>TIME_SCALE</code> to a value > 1.0
Probably, you'll never need to touch the firmware running in the radio module, but in case you need to modify the code or you're simply curious about what is happening at the low level, then refer to the section [http://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development Radio module development].
* 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===
=Programmer=
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 e-puck2 robot is equipped with an onboard programmer and debugger that let you update the firmware of the robot and debug your code easily using a standard USB interface. There is a dedicated STM32F413 microcontroller that acts as the programmer with built in GDB server, so you can control exactly what happens using the [https://www.gnu.org/software/gdb/ GNU Project Debugger] in your host machine.<br/>
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
The programmer microcontroller is also in charge of handling various low level features such as the configuration of the USB hub and the power button.
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==
==Factory firmware==
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_10.12.21_52ffc6b.bin main microcontroller factory firmware.bin (10.12.21)]; it is also available in dfu format here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_10.12.21_52ffc6b.dfu main microcontroller factory firmware.dfu (10.12.21)].
The programmer is initially programmed with a firmware based on a '''''modified version''''' of [https://github.com/blacksphere/blackmagic/wiki Black Magic Probe programmer/debugger].<br/>
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_programmer_28.05.20_3b600ec.bin programmer-firmware.bin (28.05.20)]; it is also available in dfu format here [https://projects.gctronic.com/epuck2/e-puck2_programmer_28.05.20_3b600ec.dfu programmer-firmware.dfu (28.05.20)].


==Firmware update==
==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 programmer's 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 contacting two pinholes together while inserting the USB cable (no need to turn on the robot). The two pin holes are located near the USB connector of the e-puck2, see the photo below.


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/e-puck2_top_leds_DFU_413.png <img width=200 src="https://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds_DFU_413.png">]</span><br/>
::''Location of the pin holes to put the programmer into DFU''


::<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/>
The programmer will be recognized as <code>STM Device in DFU Mode</code> device.
::''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.


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


===Linux/Mac===
===Linux/Mac===
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/>
In order to update the programmer firmware you need an utility called <code>dfu-util</code>, it should be already installed from section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates].<br/>
To uplaod the firmware, issue the following command: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin</code> (the name of the bin file must be changed accordingly).
To uplaod the firmware, issue the following command: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D programmer-firmware.bin</code>


===Windows===
===Windows===
Line 501: Line 419:
<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/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/dfu2.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu2.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/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>
<td>[https://projects.gctronic.com/epuck2/wiki_images/dfu4.png <img width=250 src="https://projects.gctronic.com/epuck2/wiki_images/dfu4.png">]</td>
Line 507: Line 425:
</table>
</table>
</span><br/>
</span><br/>
==Development==
The programmer code shouldn't be modified, but if you know what you're doing then refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development Programmer development].

Revision as of 12:55, 14 December 2021

Hardware

Overview


The following figures show the main components offered by the e-puck2 robot and where they are physically placed:

Specifications

The e-puck2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):

Feature e-puck1.3 e-puck2 Compatibility Additional
Size, weight 70 mm diameter, 55 mm height, 150 g Same form factor: 70 mm diameter, 45 mm, 130 g No e-jumper required
Battery, autonomy LiIPo rechargeable battery (external charger), 1800 mAh.
About 3 hours autonomy. Recharging time about 2-3h. 		Same battery; USB charging, recharging time about 2.5h. USB charging
Processor 16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing 32-bit STM32F407 @ 168 MHz (210 DMIPS), DSP and FPU, DMA ~10 times faster
Memory RAM: 8 KB; Flash: 144 KB RAM: 192 KB; Flash: 1024 KB RAM: 24x more capable
Flash:~7x more capable
Motors 2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution Same motors
Wheels Wheels diamater = 41 mm
Distance between wheels = 53 mm 		Same wheels
Speed Max: 1000 steps/s (about 12.9 cm/s) Max: 1200 steps/s (about 15.4 cm/s) 20% faster
Mechanical structure Transparent plastic body supporting PCBs, battery and motors Same mechanics
Distance sensor 8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm Same infra-red sensors
Front real distance sensor, Time of fight (ToF), up to 2 meter. 		ToF sensor
IMU 3D accelerometer and 3D gyro 3D accelerometer, 3D gyro, 3D magnetometer 3D magnetometer
Camera VGA color camera; typical use: 52x39 or 480x1 Same camera; typical use: 160x120 Bigger images handling
Audio 3 omni-directional microphones for sound localization
speaker capable of playing WAV or tone sounds 		4 omni-directional microhpones (digital) for sound localization
speaker capable of playing WAV or tone sounds 		+1 front microphone
LEDs 8 red LEDs around the robot, green body light, 1 strong red LED in front 4 red LEDs and 4 RGB LEDs around the robot, green light, 1 strong red LED in front 4x RGB LEDs
Communication RS232 and Bluetooth 2.0 for connection and programming USB Full-speed, Bluetooth 2.0, BLE, WiFi WiFi, BLE
Storage Not available Micro SD slot Micro SD
Remote Control Infra-red receiver for standard remote control commands Same receiver
Switch / selector 16 position rotating switch Same selector
Extensions Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own All extension supported
Programming Free C compiler and IDE, Webots simulator, external debugger Free C compiler and IDE, Webots simulator, onboard debugger (GDB) Onboard debugger

This is the overall communication schema:

Documentation

From about July 2019, the camera mounted on the e-puck2 robot is the Omnivision OV7670 CMOS image sensor, datasheet

Migrating from e-puck1.x to e-puck2

The e-puck2 robot maintains full compatibility with its predecessor e-puck, but there are some improvements that you should be aware of.

First of all the e-jumper, that is the small board that is attached on top of the e-puck1.x, isn't anymore needed in the e-puck2. The components available on the e-jumper are integrated directly in the robot board. On top of the e-puck2 you'll see a quite big free connector, this is used to attach the extensions board designed for the e-puck1.x that are fully compatible with the e-puck2; you must not connect the e-jumper in this connector.

Secondly you don't need anymore to unplug and plugin the battery for charging, but instead you can charge the battery (up to 1 ampere) directly by connecting the USB cable. If you want you can still charge the battery with the e-puck1.x external charger, in case you have more than one battery.

Moreover you don't need anymore a special serial cable (with probably an RS232 to USB adapter) to be able to communicate with the robot, but you can use the USB cable. Once connected to the computer a serial port will be available that you can use to easily exchange data with the robot.

Extensions

All the extensions (ground sensors, range and bearing, RGB panel, gumstix and omnvision) are supported by the e-puck2 robot, this means that if you have some extensions for the e-puck1.x you can still use them also with e-puck2.
For more information about using the gumstix extension with e-puck2 robot refer to http://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2.

Getting Started

The e-puck2 robot features 3 chips onboard:

  • the main microcontroller, that is responsible for handling the sensors and actuators and which runs also the demos/algorithms
  • the programmer, that provides programming/debugging capabilties and moreover it configures the USB hub and is responsible for the power management (on/off of the robot and battery measure)
  • radio module, that is responsible for handling the wireless communication (WiFi, BLE, BT), the RGB LEDs and the user button (the RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller)

The robot is shipped with the last firmware version programmed on all 3 chips, so you can immediately start using the robot.
The following sections explain the basic usage of the robot, all the users should read this chapter completely in order to have a minimal working system ready to play with the e-puck2 robot. Some sections will have more detailed information that can be read by following the links provided.

When required, dedicated informations are given for all platforms (Windows, Linux, Mac). The commands given for Linux are related to the Ubuntu distribution, similar commands are available in other distributions.

Turn on/off the robot

To turn on the robot you need to press the power button (blue button) placed on the bottom side of the board, near the speaker, as shown in the following figures:


To turn off the robot you need to press the power button for 1 second.

Meaning of the LEDs

The e-puck2 has three groups of LEDs that are not controllable by the user.


Top view of the e-puck2
  • Charger: RED if charging, GREEN if charge complete and RED and GREEN if an error occurs
  • USB: Turned ON if the e-puck2 detects a USB connection with a computer
  • STATUS: Turned ON if the robot is ON and OFF if the robot is OFF. When ON, gives an indication of the level of the battery. Also blinks GREEN if the program is running during a debug session.

Battery level indications (STATUS RGB LED):

  • GREEN if the system's tension is greater than 3.5V
  • ORANGE if the system's tension is between 3.5V and 3.4V
  • RED if the system's tension is between 3.4V and 3.3V
  • RED blinking if the system's tension is below 3.3V

The robot is automatically turned OFF if the system's tension gets below 3.2V during 10 seconds.

Connecting the USB cable

A micro USB cable (included with the robot in the package) is needed to connect the robot to the computer. There are two connectors, one placed on top of the robot facing upwards and the other placed on the side of the robot, as shown in the following figures. Both can be used to charge the robot (up to 1 ampere) or to communicate with it, but do not connect two cables at the same time. Connect the USB cable where is more comfortable to you.


Installing the USB drivers

The USB drivers must be installed only for the users of a Windows version older than Windows 10:

  1. Download and open zadig-2.3.exe
  2. Connect the e-puck2 with the USB cable and turn it on. Three unknown devices appear in the device list of the program, namely e-puck2 STM32F407, e-puck2 GDB Server (Interface 0) and e-puck2 Serial Monitor (Interface 2).
  3. For each of the three devices mentioned above, select the USB Serial (CDC) driver and click on the Install Driver button to install it. Accept the different prompts which may appear during the process. At the end you can simply quit the program and the drivers are installed. These steps are illustrated on Figure 3 below.
Note : The drivers installed are located in C:\Users\"your_user_name"\usb_driver

Example of driver installation for e-puck2 STM32F407

The drivers are automatically installed with Windows 10, Linux and Mac OS.

Anyway in Linux in order to access the serial ports, a little configuration is needed. Type the following command in a terminal session: sudo adduser $USER dialout. Once done, you need to log off to let the change take effect.

Finding the USB serial ports used

Two ports are created by the e-puck2's programmer when the USB cable is connected to the robot (even if the robot is turned off):

  • e-puck2 GDB Server. The port used to program and debug the e-puck2.
  • e-puck2 Serial Monitor. Serial communication between the PC and the radio module (used also to program the radio module).

A third port could be available depending on the code inside the e-puck2's microcontroller. With the factory firmware a port named e-puck2 STM32F407 is created.

Windows

  1. Open the Device Manager
  2. Under Ports (COM & LPT) you can see the virtual ports connected to your computer.
  3. Do a Right-click -> properties on the COM port you want to identify.
  4. Go under the details tab and select Bus reported device description in the properties list.
  5. The name of the port should be written in the text box below.
  6. Once you found the desired device, you can simply look at its port number (COMX).

Linux

1. Open a terminal window (ctrl+alt+t) and enter the following command: ls /dev/ttyACM*
2. Look for ttyACM0 and ttyACM1 in the generated list, which are respectively e-puck2 GDB Server and e-puck2 Serial Monitor. ttyACM2 will be also available with the factory firmware, that is related to e-puck2 STM32F407 port

Note : Virtual serial port numbering on Linux depends on the connections order, thus it can be different if another device using virtual serial ports is already connected to your computer before connecting the robot, but the sequence remains the same.

Mac

1. Open a terminal window and enter the following command: ls /dev/cu.usbmodem*
2. Look for two cu.usbmodemXXXX, where XXXX is the number attributed by your computer. You should find two names, with a numbering near to each other, which are respectively e-puck2 GDB Server (lower number) and e-puck2 Serial Monitor (higher number). A third device cu.usbmodemXXXX will be available with the factory firmware, that is related to e-puck2 STM32F407 port

Note : Virtual serial port numbering on Mac depends on the physical USB port used and the device. If you want to keep the same names, you must connect to the same USB port each time.

PC interface


A PC application was developed to start playing with the robot attached to the computer via USB cable: you can have information about all the sensors, receive camera images and control the leds and motors.
Beware that it's not mandatory to download this application in order to work with the robot, but it is a nice demo that gives you an overview of all the sensors and actuators available on the robot, this is a first step to gain confidence with the robot.

With the factory firmwares programmed in the robot, place the selector in position 8, attach the USB cable and turn on the robot. Enter the correct port (the one related to e-puck2 STM32F407) in the interface and click connect.

The source code is available from the repository https://github.com/e-puck2/monitor.

Available executables

On Linux remember to apply the configuration explained in the chapter Installing the USB drivers in order to access the serial port.

Installing the dependencies for firmwares updates

You can update the firmware for all 3 chips: the main microcontroller, the radio module and the programmer. For doing that, you need some tools to be installed on the system.

Windows

To upload a new firmware in the microcontroller or in the radio module, you don't need to install anything, the packages provided include all the dependencies.

To upload a new firmware in the programmer you need to install an application called DfuSe released by STMicroelectronics. You can download it from DfuSe_V3.0.5.zip.

Linux

To upload a new firmware in the microcontroller or in the radio module, you need:

  • Python (>= 3.4): sudo apt-get install python3
  • Python pip: sudo apt-get install -y python3-pip
  • pySerial (>= 2.5): sudo pip3 install pyserial

To upload a new firmware in the programmer you need:

  • dfu-util: sudo apt-get install dfu-util

Mac

Install the Homewbrew package manager by opening a terminal and issueing:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
and then:
brew upgrade

To upload a new firmware in the microcontroller or in the radio module, you need:

  • Python (>= 3.4): brew install python (it will install also pip)
  • pySerial (>= 2.5): pip3 install pyserial

To upload a new firmware in the programmer you need:

  • dfu-util: brew install dfu-util

PC side development

This section is dedicated to the users that develop algorithms on the PC side and interact with the robot remotely through a predefined communication protocol. These users don't modify the firmware of the robot, but instead they use the factory firmware released with the robot. They update the robot firmware only when there is an official update.
The remote control of the robot, by receiving sensors values and setting the actuators, is done through the following channels: Bluetooth, Bluetooth Low Energy, WiFi, USB cable.
Examples of tools/environment used by these users:

  1. Aseba
  2. Simulator (e.g. Webots)
  3. ROS
  4. iOS, Android apps
  5. Custom PC application
  6. IoT (e.g. IFTTT)

If you fall into this category, then follow this section for more information: PC side development.

Main microcontroller

The e-puck2 robot main microcontroller is a 32-bit STM32F407 that runs at 168 MHz (210 DMIPS) and include DSP, FPU and DMA capabilities. The version chosen for the e-puck2 has 192 KB of total RAM and 1024 KB of flash, so there is a lot of memory to work with.
This chip is responsible for handling the sensors and actuators and runs also the demos and algorithms.

Factory firmware

The main microcontroller of the robot is initially programmed with a firmware that includes many demos that could be started based on the selector position, here is a list of the demos with related position and a small description:

  • Selector position 0: Aseba
  • Selector position 1: Shell
  • Selector position 2: Read proximity sensors and when an object is near a proximity, turn on the corresponding LED
  • Selector position 3: Asercom protocol v2 (BT)
  • Selector positoin 4: Range and bearing extension (receiver)
  • Selector position 5: Range and bearing extension - clustering demo (simultaneous transmitter and receiver).
  • Selector position 6: Move the robot back and forth exploiting the gyro, with LEDs animation
  • Selector position 7: Play a wav (mono, 16 KHz) named "example.wav" from the micro sd when pressing the button
  • Selector position 8: Asercom protocol v2 (USB)
  • Selector position 9: Local communication: transceiver
  • Selector position 10: this position is used to work with the Linux extensions. To work with gumstix refer to Overo Extension: e-puck2 , to work with Pi-puck refer to Pi-puck: Requirements .
  • Selector position 11: Simple obstacle avoidance + some animation
  • Selector position 12: Hardware test
  • Selector position 13: LEDs reflect orientation of the robot
  • Selector position 14: Compass
  • Selector position 15: WiFi mode

The pre-built firmware is available here main microcontroller factory firmware (10.12.21).

Firmware update

Now and then there could be an official firmware update for the robot and it's important to keep the robot updated with the last firmware to get possibile new features, improvements and for bug fixes.
The onboard programmer run a GDB server, so we use GDB commands to upload a new firmware, for this reason a toolchain is needed to upload a new firmware to the robot.
The following steps explain how to update the main microcontroller firmware:
1. Download the package containing the required toolchain and script to program the robot: Windows, Linux 32 bits/64 bits, Mac OS
2. Download the last version of the main microcontroller factory firmware (10.12.21), or use your custom firmware
3. Extract the package and put the firmware file (with elf extension) inside the package directory; beware that only one elf file must be present inside this directory
4. Attach the USB cable and turn on the robot
5. Run the script from the package directory:

Windows: double click program.bat
Linux/Mac: issue the following command in a terminal ./program.sh. If you get permission errors, then issue sudo chmod +x program.sh to let the script be executable.

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

The final lines should contain the entry ".data",, this means that the upload was successfull. You can then close the terminal window if it is still open.

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

Robot side development

If you are an embedded developer and are brave enough, then you have complete access to the source code running on the robot, so you can discover what happen inside the main microcontroller and modify it to accomodate your needs. Normally the users that fall into this category develop algorithms optimized to run directly on the microcontroller, such as:

  1. onboard image processing
  2. swarm algorithms
  3. fully autonomous behaviors
  4. ...

For more information about programming the robot itself, refer to section Robot side development

Radio module

The radio module chosen for the e-puck is the new ESP32 chip from Espressif, integrating a dual core that run up to 240 MHz, 4 MB of flash and 520 KB of RAM. It supports WiFi standards 802.11 b/g/n (access point mode supported), Bluetooth and Bluetooth LE 4.2. It is the successor of the ESP8266 chip. The following figure shows the various peripherals available on the ESP32:

This chip first of all is responsible for handling the wireless communication, moreover it handles also the RGB LEDs (with PWM) and the user button. The RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller.

Factory firmware

The radio module of the robot is initially programmed with a firmware that supports Bluetooth communication.
The pre-built firmware is available here radio module factory firmware (11.12.18).

WiFi firmware

At the moment the factory firmware supports only Bluetooth, if you want to work with WiFi you need to program the radio with a dedicated firmware, refer to section PC side development: WiFi.

BLE firmware

At the moment the factory firmware supports only calssic Bluetooth, if you want to work with Bluetooth Low Energy you need to program the radio with a dedicated firmware, refer to section Mobile phone development.

Firmware update

In order to update the firmware of the ESP32 WiFi module you need to use a python script called esptool provided by Espressif (manufacturer of the chip). This script was modified to work with the e-puck2 robot and is included in the provided package. The following steps explain how to update the radio module firmware:
1. Download the package containing the required tools and script to program the robot: Windows, Linux / Mac
2. Download the last version of the radio module factory firmware (11.12.18), or use another firmware (e.g. WiFi, BLE, your own). The firmware is composed by 3 files named bootloader.bin, ESP32_E-Puck_2.bin and partitions_singleapp.bin
3. Extract the package and put the firmware files inside the package directory; beware that the name of the .bin files must be the same as indicated in step 2
4. Attach the USB cable and turn on the robot
5. Run the script from the package directory:

Windows: double click program.bat
Linux/Mac: issue the following command in a terminal ./program.sh. If you get permission errors, then issue sudo chmod +x program.sh to let the script be executable.

The upload should last about 10-15 seconds and you'll see the progress as shown in the following figure:

When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure:

Sometime you could encounter a timeout error as shown in the following figures; in these cases you need to unplug and plug again the USB cable and power cycle the robot, then you can retry.

Development

Probably, you'll never need to touch the firmware running in the radio module, but in case you need to modify the code or you're simply curious about what is happening at the low level, then refer to the section Radio module development.

Programmer

The e-puck2 robot is equipped with an onboard programmer and debugger that let you update the firmware of the robot and debug your code easily using a standard USB interface. There is a dedicated STM32F413 microcontroller that acts as the programmer with built in GDB server, so you can control exactly what happens using the GNU Project Debugger in your host machine.
The programmer microcontroller is also in charge of handling various low level features such as the configuration of the USB hub and the power button.

Factory firmware

The programmer is initially programmed with a firmware based on a modified version of Black Magic Probe programmer/debugger.
The pre-built firmware is available here programmer-firmware.bin (28.05.20); it is also available in dfu format here programmer-firmware.dfu (28.05.20).

Firmware update

The programmer's 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 contacting two pinholes together while inserting the USB cable (no need to turn on the robot). The two pin holes are located near the USB connector of the e-puck2, see the photo below.


Location of the pin holes to put the programmer into DFU

The programmer 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).

Linux/Mac

In order to update the programmer 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 programmer-firmware.bin

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]


Development

The programmer code shouldn't be modified, but if you know what you're doing then refer to section Programmer development.

Retrieved from "http://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development&oldid=2182"