Difference between revisions of "e-puck2"

From GCtronic wiki
Jump to: navigation, search
(Flashing the main microcontroller)
(Available executables)
 
(476 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
=Hardware=
 
=Hardware=
 
==Overview==
 
==Overview==
<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>
+
<span class="plainlinks">[https://www.gctronic.com/doc/images/e-puck2-overview.png <img width=500 src="https://www.gctronic.com/doc/images/e-puck2-overview_small.png">]</span>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-features.png <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-features_small.png">]</span><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 following figures show the main components offered by the e-puck2 robot and where they are physically placed:<br/>
 
The following figures show the main components offered by the e-puck2 robot and where they are physically placed:<br/>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position_small.png">]</span><br/>
+
<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/>
  
 
==Specifications==
 
==Specifications==
The e-puck2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):
+
The e-puck version 2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):
 
{| border="1"
 
{| border="1"
 
|'''Feature'''
 
|'''Feature'''
|'''e-puck1.3'''
+
|'''e-puck version 1.3'''
|'''e-puck2'''
+
|'''e-puck version 2'''
 
|'''Compatibility'''
 
|'''Compatibility'''
 
|'''Additional'''
 
|'''Additional'''
Line 19: Line 19:
 
|70 mm diameter, 55 mm height, 150 g
 
|70 mm diameter, 55 mm height, 150 g
 
|Same form factor: 70 mm diameter, 45 mm, 130 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">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|No e-jumper required
 
|No e-jumper required
 
|-
 
|-
Line 25: Line 25:
 
|LiIPo rechargeable battery (external charger), 1800 mAh. <br/>About 3 hours autonomy. Recharging time about 2-3h.
 
|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.
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|USB charging
 
|USB charging
 
|-
 
|-
Line 31: Line 31:
 
|16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing
 
|16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing
 
|32-bit STM32F407 @ 168 MHz (210 DMIPS), DSP and FPU, DMA
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|~10 times faster
 
|~10 times faster
 
|-
 
|-
Line 37: Line 37:
 
|RAM: 8 KB; Flash: 144 KB
 
|RAM: 8 KB; Flash: 144 KB
 
|RAM: 192 KB; Flash: 1024 KB
 
|RAM: 192 KB; Flash: 1024 KB
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|RAM: 24x more capable<br/>Flash:~7x more capable
 
|RAM: 24x more capable<br/>Flash:~7x more capable
 
|-
 
|-
Line 43: Line 43:
 
|2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution
 
|2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution
 
|Same motors
 
|Same motors
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 49: Line 49:
 
|Wheels diamater = 41 mm <br/>Distance between wheels = 53 mm
 
|Wheels diamater = 41 mm <br/>Distance between wheels = 53 mm
 
|Same wheels
 
|Same wheels
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 55: Line 55:
 
|Max: 1000 steps/s (about 12.9 cm/s)
 
|Max: 1000 steps/s (about 12.9 cm/s)
 
|Max: 1200 steps/s (about 15.4 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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|20% faster
 
|20% faster
 
|-
 
|-
Line 61: Line 61:
 
|Transparent plastic body supporting PCBs, battery and motors
 
|Transparent plastic body supporting PCBs, battery and motors
 
|Same mechanics
 
|Same mechanics
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 67: Line 67:
 
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm
 
|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.
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|ToF sensor
 
|ToF sensor
 
|-
 
|-
Line 73: Line 73:
 
|3D accelerometer and 3D gyro
 
|3D accelerometer and 3D gyro
 
|3D accelerometer, 3D gyro, 3D magnetometer
 
|3D accelerometer, 3D gyro, 3D magnetometer
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|3D magnetometer
 
|3D magnetometer
 
|-
 
|-
Line 79: Line 79:
 
|VGA color camera; typical use: 52x39 or 480x1
 
|VGA color camera; typical use: 52x39 or 480x1
 
|Same camera; typical use: 160x120
 
|Same camera; typical use: 160x120
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|Bigger images handling
 
|Bigger images handling
 
|-
 
|-
Line 85: Line 85:
 
|3 omni-directional microphones for sound localization<br/>speaker capable of playing WAV or tone sounds
 
|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
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
| +1 front microphone
 
| +1 front microphone
 
|-
 
|-
Line 91: Line 91:
 
|8 red LEDs around the robot, green body light, 1 strong red LED in front
 
|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
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|4x RGB LEDs
 
|4x RGB LEDs
 
|-
 
|-
Line 97: Line 97:
 
|RS232 and Bluetooth 2.0 for connection and programming
 
|RS232 and Bluetooth 2.0 for connection and programming
 
|USB Full-speed, Bluetooth 2.0, BLE, WiFi
 
|USB Full-speed, Bluetooth 2.0, BLE, WiFi
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|WiFi, BLE
 
|WiFi, BLE
 
|-
 
|-
Line 103: Line 103:
 
|Not available
 
|Not available
 
|Micro SD slot
 
|Micro SD slot
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|Micro SD
 
|Micro SD
 
|-
 
|-
Line 109: Line 109:
 
|Infra-red receiver for standard remote control commands
 
|Infra-red receiver for standard remote control commands
 
|Same receiver
 
|Same receiver
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 115: Line 115:
 
|16 position rotating switch
 
|16 position rotating switch
 
|Same selector
 
|Same selector
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 121: Line 121:
 
|Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own
 
|Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own
 
|All extension supported
 
|All extension supported
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
+
|style="text-align:center;" | <img width=40 src="https://www.gctronic.com/doc/images/ok.png">
 
|
 
|
 
|-
 
|-
Line 127: Line 127:
 
|Free C compiler and IDE, Webots simulator, external debugger
 
|Free C compiler and IDE, Webots simulator, external debugger
 
|Free C compiler and IDE, Webots simulator, onboard debugger (GDB)
 
|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">
+
|style="text-align:center;" | <img width=30 src="https://www.gctronic.com/doc/images/plus.png">
 
|Onboard debugger
 
|Onboard debugger
 
|}
 
|}
  
 
This is the overall communication schema:<br/>
 
This is the overall communication schema:<br/>
<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/>
+
<span class="plainlinks">[https://www.gctronic.com/doc/images/comm-overall-e-puck2E.jpg <img width=700 src="https://www.gctronic.com/doc/images/comm-overall-e-puck2E.jpg">]</span><br/>
  
 
==Documentation==
 
==Documentation==
* '''Main microcontroller''': STM32F407, [http://projects.gctronic.com/epuck2/doc/STM32F407xx_datasheet.pdf datasheet], [http://projects.gctronic.com/epuck2/doc/STM32F407_reference-manual.pdf reference-manual]
+
* '''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, [http://projects.gctronic.com/epuck2/doc/STM32F413x_datasheet.pdf datasheet], [http://projects.gctronic.com/epuck2/doc/STM32F413_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, [http://projects.gctronic.com/epuck2/doc/esp32_datasheet_en.pdf datasheet], [http://projects.gctronic.com/epuck2/doc/esp32_technical_reference_manual_en.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, [http://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf datasheet], no IR cut filter
+
* '''Camera''': PixelPlus PO8030D CMOS image sensor, [https://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf datasheet], no IR cut filter
* '''Microphones''': STM-MP45DT02, [http://projects.gctronic.com/epuck2/doc/mp45dt02.pdf datasheet]
+
: 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]
* '''Optical sensors''': Vishay Semiconductors Reflective Optical Sensor, [http://projects.gctronic.com/epuck2/doc/tcrt1000.pdf datasheet]
+
* '''Microphones''': STM-MP45DT02, [https://projects.gctronic.com/epuck2/doc/mp45dt02.pdf datasheet]
* '''ToF distance sensor''': STM-VL53L0X, [http://projects.gctronic.com/epuck2/doc/VL53L0X-Datasheet.pdf datasheet], [http://projects.gctronic.com/epuck2/doc/VL53L0X-UserManual-API.pdf user-manual]
+
* '''Optical sensors''': Vishay Semiconductors Reflective Optical Sensor, [https://projects.gctronic.com/epuck2/doc/tcrt1000.pdf datasheet]
* '''IMU''': InvenSense MPU-9250, [http://projects.gctronic.com/epuck2/doc/MPU-9250-product-specification.pdf product-specification], [http://projects.gctronic.com/epuck2/doc/MPU-9250-Register-Map.pdf register-map]
+
* '''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]
* '''Motors''': [http://www.e-puck.org/index.php?option=com_content&view=article&id=7&Itemid=9 details]
+
* '''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''': [https://e-puck.gctronic.com/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
 
* '''Speaker''': Diameter 13mm, power 500mW, 8 Ohm, DS-1389 or PSR12N08AK or similar
 
* '''IR receiver''': TSOP36230
 
* '''IR receiver''': TSOP36230
  
=Installation of the e-puck2 environment=
+
==Migrating from e-puck version 1.x to e-puck version 2==
Some programs are needed to program the e-puck2.
+
The e-puck version 2 robot maintains full compatibility with its predecessor e-puck, but there are some improvements that you should be aware of.<br/>
  
#Eclipse_e-puck2 is a distribution of Eclipse IDE for C/C++ Developers specially modified to edit and compile e-puck2's projects out of the box. It doesn't require to be installed and everything needed is located in the package given. The only dependency needed to be able to run Eclipse is '''Java'''.
+
First of all the e-jumper, that is the small board that is attached on top of the e-puck version 1.x, isn't anymore needed in the e-puck version 2. The components available on the e-jumper are integrated directly in the robot board. On top of the e-puck version 2 you'll see a quite big free connector, this is used to attach the extensions board designed for the e-puck version 1.x that are fully compatible with the e-puck version 2; you must not connect the e-jumper in this connector.<br/>
#Drivers must also be installed for Windows older than Windows 10.
+
 +
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-puck version 1.x external charger, in case you have more than one battery.<br/>
  
==Installation for Windows==
+
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.
===Java 8 32bits===
 
This section can be ignored if Java version 8 32bits is already installed on your computer.<br>
 
To verify, you can open the '''Programs and Features''' panel and search for a '''Java 8 Update xxx''' install.  
 
  
#Go to the [https://www.java.com/en/download/manual.jsp Java download page] and download "Windows offline" This is the 32bits version of Java.
+
==Extensions==
#Run the downloaded installer and follow its instructions to proceed with the installation of Java 32bits.
+
All the extensions (ground sensors, range and bearing, RGB panel, gumstix and omnvision) are supported by the e-puck version 2 robot, this means that if you have some extensions for the e-puck version 1.x you can still use them also with e-puck version 2.<br/>
#Close the internet browser if it opened at the end of the installation.
+
For more information about using the gumstix extension with e-puck version 2 robot refer to [https://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2 https://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2].
  
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png">]</span><br/>
+
=Getting Started=
:''Java download page''
+
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
===Eclipse_e-puck2===
+
* 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)
#Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Win32_11_apr_2018.zip Eclipse_e-puck2 package for windows].
+
* 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)
#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 Eclipse_e-puck2.exe and place it anywhere if you want.
 
 
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png">]</span><br/>
 
:''Eclipse_e-puck2 folder obtained after extraction''
 
 
 
'''Important things to avoid :'''
 
:1. The path to the Eclipse_e-puck2 folder must contain zero space.
 
::Example :
 
::<code>C:\epfl_stuff\Eclipse_e-puck2</code> OK
 
::<code>C:\epfl stuff\Eclipse_e-puck2</code> NOT OK
 
:2. You must not put Ellipse_e-puck2 folder into '''Program Files (x86)'''. Otherwise the compilation when using Eclipse will not work.
 
:3. The file’s structure in the Eclipse_e-puck2 folder must remain the same. It means no file inside this folder must be moved to another place.
 
 
 
===Drivers===
 
This part concerns only the users of a Windows version older than Windows 10. The drivers are automatically installed with Windows 10.
 
 
 
#Open <code>zadig-2.3.exe</code> located in the <code>Eclipse_e-puck2\Tools\</code> folder you installed before.
 
#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. After that 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>
 
 
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Zadig_e-puck2_STM32F407.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Zadig_e-puck2_STM32F407.png">]</span><br/>
 
::''Example of driver installation for e-puck2 STM32F407''
 
 
 
==Installation for Linux==
 
===Java 8===
 
This section can be ignored if Java is already installed on your computer.<br>
 
To verify whether it is installed or not you can type the following command into a terminal window:
 
<pre>update-java-alternatives -l</pre>
 
If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
 
You need to have Java 1.8.xxxx listed to be able to run Eclipse_e-puck2.
 
 
 
Type the following commands in a terminal session to install Java SDK:
 
<pre>sudo add-apt-repository ppa:openjdk-r/ppa
 
sudo apt-get update
 
sudo apt-get install openjdk-8-jre </pre>
 
 
 
===Eclipse_e-puck2===
 
#Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
 
#Download the Eclipse_e-puck2 package for Linux [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz 32bits] / [http://projects.gctronic.com/epuck2//Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_64bits.tar.gz 64bits]. Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand <code>uname -a</code> in the terminal window and look for i686 (32bit) or x86_64 (64 bit). 
 
#Extract the downloaded file to the location you want (can take time).
 
#You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.
 
 
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png">]</span><br/>
 
:''Eclipse_e-puck2 folder obtained after extraction''
 
 
 
Note : The icon of the Eclipse_e-puck2 executable will appear after the first launch of the program.
 
 
 
'''Important things to avoid :'''
 
:1. You cannot create a Link to the Eclipse_e-puck2 executable because otherwise the program will think its location is where the Link is and it will not find the resource located in the Eclipse_e-puck2 folder.
 
:2. The path to the Eclipse_e-puck2 folder must contain zero space.
 
::Example :
 
::<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 Eclipse_e-puck2 folder must remain the same. It means no file inside this folder must be moved to another place.
 
 
 
===Serial Port===
 
In order to let Eclipse (or any program ran by you) to access the serial ports, a little configuration is needed.
 
 
 
Type the following command in a terminal session. Once done, you need to log off to let the change take effect.
 
 
 
<pre>sudo adduser $USER dialout</pre>
 
 
 
==Installation for Mac==
 
===Command Line Tools ===
 
To compile on Mac with Eclipse_e-puck2, it is necessary to have the Command Line Tools installed. It is a bundle of many commonly used tools.<br>
 
You can install it by typing the following command in a terminal window. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.
 
<pre>xcode-select --install</pre>
 
 
 
===Java 8===
 
This section can be ignored if Java is already installed on your computer.<br>
 
To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac.
 
<pre>/usr/libexec/java_home -V</pre>
 
You need to have <code>Java SE 8</code> listed to be able to run Eclipse_e-puck2.
 
 
 
:1. Go to the [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java download page] and download the <code>Mac OS X Java 8 SE Development Kit</code>. It is the .dmg file without the Demos and Samples.
 
::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
 
:2. Open the .dmg file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.
 
 
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png">]</span><br/>
 
:''Java download page''
 
 
 
===Eclipse_e-puck2===
 
:1. Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_11_apr_2018.dmg Eclipse_e-puck2 package for Mac].
 
:2. Open the .dmg file downloaded and DragAndDrop the Eclipse_e-puck2.app into the Applications folder
 
::Note : You can place the Eclipse_e-puck2.app anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in Applications.
 
:3. You can create an Alias to Eclipse_e-puck2.app and place it anywhere if you want.
 
 
 
===First launch and Gatekeeper===
 
It’s very likely that Gatekeeper (one of the protections of Mac OS) will prevent you to launch Eclipse_e-puck2.app because it isn’t signed from a known developer.<br>
 
If you can’t run the program because of a warning of the system, press <code>OK</code> and try to launch it by right clicking on it and choosing <code>open</code> in the contextual menu (may be slow to open the first time).<br>
 
If <code>Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.</code> or if <code>"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.</code> appears after executing the app the first time, it is needed to disable temporarily Gatekeeper.
 
 
 
To do so :
 
 
 
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
 
 
 
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png">]</span><br/>
 
::''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.
+
The robot is shipped with the last firmware version programmed on all 3 chips, so you can immediately start using the robot.<br/>
::<pre>sudo spctl --master-disable</pre>
+
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.
:2. Now you can try to run the application and it should work.
 
:3. If Eclipse opened successfully, it is time to reactivate Gatekeeper. Simply set back the setting of Gatekeeper.
 
::For the ones who needed to type a command to disable Gatekeeper, here is the command to reactivate it.
 
::<pre>sudo spctl --master-enable</pre>
 
  
This procedure is only needed the first time. After that Gatekeeper will remember your choice to let run this application and will not bother you anymore, as long as you use this application. If you re-download it, you will have to redo the procedure for Gatekeeper.
+
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.  
  
'''Important things to avoid :'''
+
==Turn on/off the robot==
:1. The path to the Eclipse_e-puck2.app must contain zero space.
+
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:
::Example :
+
::<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/>
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
+
To turn off the robot you need to press the power button for 1 second.
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
 
:2. The file’s structure in the Eclipse_e-puck2.app must remain the same. It means no file inside this app must be moved to another place.
 
  
=Getting Started=
+
==Meaning of the LEDs==
===Meaning of the LEDs===
 
 
The e-puck2 has three groups of LEDs that are not controllable by the user.
 
The e-puck2 has three groups of LEDs that are not controllable by the user.
  
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds.png">]</span><br/>
+
::<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/>
 
::''Top view of the e-puck2''
 
::''Top view of the e-puck2''
  
*Charger : RED if charging, GREEN if charge complete and RED and GREEN if an error occurs
+
*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
+
*USB: Turned ON if the e-puck2 detects a USB connection with a computer
*STATUS : Turned ON if the robot is ON and OFF is 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.
+
*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):
 
Battery level indications (STATUS RGB LED):
Line 303: Line 194:
  
 
The robot is automatically turned OFF if the system's tension gets below 3.2V during 10 seconds.
 
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.
 +
::<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/>
 +
 +
==Installing the USB drivers==
 +
The USB drivers must be installed only for the users of a Windows version older than Windows 10:
 +
 +
#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>
 +
 +
:<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''
 +
 +
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: <code>sudo adduser $USER dialout</code>. Once done, you need to log off to let the change take effect.
  
 
==Finding the USB serial ports used==
 
==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):
 
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 with Eclipse_e-puck2 (GDB).
+
* '''e-puck2 GDB Server'''. The port used to program and debug the e-puck2.
* '''e-puck2 Serial Monitor'''. A serial monitor. [[#see dedicated chapter(not yet ready)]]
+
* '''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 standard firmware a port named '''e-puck2 STM32F407''' is created.
+
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===
 
===Windows===
 
#Open the Device Manager
 
#Open the Device Manager
Line 319: Line 229:
  
 
===Linux===
 
===Linux===
:1. Open a terminal window (ctrl+alt+t) and enter the following command.
+
:1. Open a terminal window (<code>ctrl+alt+t</code>) and enter the following command: <code>ls /dev/ttyACM*</code>
:<pre>ls /dev/ttyACM*</pre>
+
: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
:2. Look for '''ttyACM0''' and '''ttyACM1''' in the generated list, which are respectively '''e-puck2 GDB Server''' and '''e-puck2 Serial Monitor'''.
+
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.
Note : Virtual serial port numbering on Linux is made by the connections order, thus it can be different if another device using virtual serial ports is already connected to your computer.
 
  
 
===Mac===
 
===Mac===
:1. Open a terminal window and enter the following command.
+
:1. Open a terminal window and enter the following command: <code>ls /dev/cu.usbmodem*</code>
:<pre>ls /dev/cu.usbmodem*</pre>
+
: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
:2. Look for two '''cu.usbmodemXXXX''', where XXXX is the number attributed by your computer. You should find two names, more or less following in the numbering, which are respectively '''e-puck2 GDB Server''' and '''e-puck2 Serial Monitor'''.
 
  
 
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.
 
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.
  
==Configuring the Debugger's settings==
+
==PC interface==
Eclipse_e-puck2 contains everything needed to compile, program and debug the e-puck2.<br>
+
<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/>
The only settings to configure with a new project are located under the '''Debug Configurations''' tab of Eclipse (you can also find it on '''Run->Debug Configurations''').
+
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/>
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png <img width=231 src="http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png">]</span><br/>
+
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/>
Once in the settings, select '''Generic Blackmagic Probe''' preset on the left panel. Then you need to configure two things :
 
  
#If you already have a project, under the '''main''' tab, you need to select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse must have indexed the binaries and you can list the project and the compiled files using respectively the '''Browse...''' and '''Search Project...''' buttons. If you do not already have a project, add a random name as the title which will act as a place holder, allowing you to aply the next configuration.
+
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>.
#Under the '''Startup''' tab, you need to replace the path to the serial port written on the first line of the text box by the one used by the GDB Server of your e-puck. [[#Finding the USB serial ports used | See how to find it]].
 
:* For Windows, it will be '''\\.\COMX''', X being the port number.
 
:* For Linux, it will be '''/dev/ttyACMX''', X being the port number
 
:* For Mac, it will be '''/dev/cu.usbmodemXXXXX''', XXXXX being the port number.
 
:* You can also type '''${COM_PORT}''' instead of the com port in order to use the variable COM_PORT for the debug configuration.<br>To change the value of this variable, go to the '''main''' tab again, click on the '''Variables...''' button and click on the '''Edit Variables...''' button. The opened window will let you edit the value of the variable.<br>Using the variable COM_PORT instead of the real com port in a debug configuration is useful if you have multiple debug configurations for example. If for one reason you need to change the com port to use, then you can simply edit the variable COM_PORT instead of editing the com port for each debug configuration
 
  
If you want to debug another project, you can change the settings of the '''Generic Blackmagic Probe''' preset or copy it into another preset and configure this one in order to have one preset by project.
+
The source code is available from the repository [https://github.com/e-puck2/monitor https://github.com/e-puck2/monitor].<br/>
Now you should be able to use the debugger with Eclipse.
 
  
==Creating a project==
+
===Available executables===
===Basic standard project===
+
* [https://projects.gctronic.com/epuck2/monitor_win.zip Windows executable]: tested on Windows 7 and Windows 10
[https://github.com/e-puck2/e-puck2_main-processor.git e-puck2_main-processor] is the basic standard project containing all the libraries written for the e-puck2. Refer to the [http://www.gctronic.com/doc/index.php?title=e-puck2#Library Library] section to download the complete version.<br>
+
* [https://projects.gctronic.com/epuck2/monitor_mac.zip Max OS X executable (compatibles with all OS versions and hardware architectures)]
The basic standard project shows how to use the libraries and can be interfaced with [[#PC interface | e-puck2 monitor]].<br/>
+
* [https://projects.gctronic.com/epuck2/monitor_linux64bit.tar.gz Ubuntu 14.04 (or later) - 64 bit]
This project can be added to Eclipse_e-puck2 by following the next steps:<br>
+
On Linux remember to apply the configuration explained in the chapter [https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers Installing the USB drivers] in order to access the serial port.
# Run Eclipse and then select '''File->New->Makefile Project with Existing Code'''.
 
# Next choose the project folder and set a project name (otherwise you can keep the one created by Eclipse). Choose '''None''' for the the toolchain.
 
# Click on the '''Finish''' button and the project is added to Eclipse.  
 
  
===Project template===
+
==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.
  
Alternativly this project can also be used as a library to build your own project on top of it.<br>
+
===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 accomplish that, you have to copy the folder '''Project_template''', contained in the e-puck2_main-processor project, where you want to place your project.<br>
+
To 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].
You can of course rename the folder to the name you want.<br>
 
  
The next step is to edit the makefile of your project. Set the name of your project, write the updated path to the e-puck2_main-processor folder, and also rewrite the path to the .c files. Lastly, include the path for any the desired .h files form other folders.<br>
+
===Linux===
All the .h files located next to the makefile are automatically included in the compilation. But if you need to place them into folders, you have to specify these folders in the makefile.
+
To upload a new firmware in the microcontroller or in the radio module, you need:
This makefile uses the main makefile of the e-puck2_main-processor project. This means you can add custom commands to the makefile but it should not interfere with the main makefile.
+
* 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>
  
The result of the compilation will appear in a build folder in your project folder.
+
To upload a new firmware in the programmer you need:
 +
* dfu-util: <code>sudo apt-get install dfu-util</code>
  
===Adding to Eclipse_epuck2===
+
===Mac===
#To add the project into Eclipse, you need to select '''File->New->Makefile Project with Existing Code'''.
+
Install the [https://brew.sh Homewbrew] package manager by opening a terminal and issueing:<br/>
#Next choose your project folder and set a project name. Choose '''None''' for the the toolchain.
+
<code>/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"</code><br/>
#Click on the '''Finish''' button and the project is added to Eclipse.
+
and then:<br/>
#Rename the file '''Debug_project_template.launch''' contained in the project folder by the name you want for the debug configuration of your project.
+
<code>brew upgrade</code><br/>
#Go to '''Run->Debug Configurations...''' and select on the left your new debug configuration and set the project to debug and the path to the compiled file of the project ([[#Configuring the Debugger's settings |as explained in the chapter before]]). If there is nothing apering when you press '''Search Project...''' then you must enter the '''.elf''' file name by hand, which can be found in your project folder under a folder named '''build'''.
 
#Go to  '''Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers''' and Check '''CDT Cross GCC Built-in Compiler Settings'''.<br> Then in the textbox below, write '''arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"'''.
 
#Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
 
##Go to '''File->New->Folder'''.
 
##Check '''Advanced >>''' on the bottom.
 
##Choose '''Link to alternate location (Linked Folder)'''.
 
##Type '''PROJECT_LOC''' and then add to this path the path to the e-puck2_main-processor folder. For example '''PROJECT_LOC/../e-puck2_main-processor''' if the library is located as the same level as your project folder.
 
#Before you compile, make sure the robot is turned on, and in addition make sure that the Makefile, has a capital M in the front.
 
#After you compile the project and if it succeeded, go to '''Project->C/C++ Index->Rebuild''' to rebuild the index. (We need to have compiled at least one time in order to let Eclipse find all the paths to the files used.)
 
  
You should now be able to use the project with Eclipse.
+
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>
  
==Flashing the main microcontroller==
+
To upload a new firmware in the programmer you need:
In order to update the firmware of the main microcontroller (STM32F407) you can either use Eclipse (as explained in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_Debugger.27s_settings Configuring the Debugger settings]) or you can do it manually as explained in this section. The onboard programmer run a gdb server, so we can use gdb commands to upload a new firmware.<br/>
+
* dfu-util: <code>brew install dfu-util</code>
1. download the gdb init file [http://projects.gctronic.com/epuck2/mygdbinit mygdbinit] and place it in the same folder of the compiled firmware. This file has the following content:
 
<pre>target extended-remote \\.\COM72
 
monitor swdp_scan
 
attach 1
 
set mem inaccessible-by-default off
 
load</pre>
 
In this file you need to change the port to reflect the one of the <code>GDB server</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]).
 
  
2. issue the following command to start the upload
+
==PC side development==
<pre>Windows: arm-none-eabi-gdb.exe --interpreter=mi -x mygdbinit firmware.elf
+
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/>
Linux/Mac: arm-none-eabi-gdb --interpreter=mi -x mygdbinit firmware.elf</pre>
+
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/>
In this command you need to change the name of the firmware with the one you have.<br/>
+
Examples of tools/environment used by these users:
Moreover if the <code>PATH</code> variable is not set (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_PATH_variable Configuring the PATH variable]) you need to insert the absolute path to the debugger that you can find in the Eclipse package (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Installation_of_the_e-puck2_environment Installation of the e-puck2 environment]) inside the directory <code>Tools\gcc-arm-none-eabi-XXX\bin</code>.
+
# 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: [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development PC side development].<br/>
  
When the upload is complete you'll see an output like in the following figure:<br/>
+
=Main microcontroller=
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/f407-flashing.png">]</span><br/>
+
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/>
The final line should contain <code>".data",</code> , and it should all be enclosed at the end with <code>(gdb)</code>. You can then close the terminal window.
+
This chip is responsible for handling the sensors and actuators and runs also the demos and algorithms.
  
If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.
+
==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 or transmitter, switch between them with button)
 +
* 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(A): this position is used to work with the Linux extensions. To work with gumstix refer to [https://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2 Overo Extension: e-puck2] , to work with Pi-puck refer to [https://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements Pi-puck: Requirements ].
 +
* Selector position 11(B): Simple obstacle avoidance + some animation
 +
* Selector position 12(C): Hardware test
 +
* Selector position 13(D): LEDs reflect orientation of the robot
 +
* Selector position 14(E): Compass
 +
* Selector position 15(F): WiFi mode
 +
The pre-built firmware is available here [https://projects.gctronic.com/epuck2/e-puck2_main-processor_26.04.23_f4f3582.elf main microcontroller factory firmware (26.04.23)].
  
==Flashing the radio module==
+
==Firmware update==
In order to update the firmware of the ESP32 WiFi module you need to use a python script called <code>esptool</code> provided by Espressif (manufacturer of the chip). This script was modified to work with the e-puck2 robot and is available from the following link:
+
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/>
* Windows: [http://projects.gctronic.com/epuck2/esptool.exe esptool.exe]; Python not required on the system.
+
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/>  
* Linux/Mac: [http://projects.gctronic.com/epuck2/esptool.py esptool.py]; Python 3.4 and pySerial 2.5 need to be installed on the system.
+
The following steps explain how to update the main microcontroller firmware:<br/>
Place the script in the same folder as the firmware (composed by 3 bin files: <code>bootloader.bin</code>, <code>ESP32_E-Puck_2.bin</code> and <code>partitions_singleapp.bin</code>) and then issue the following command:
+
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_14.02.23.zip Windows], Linux [https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux32_14.02.23.tar.gz 32 bits]/[https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux64_14.02.23.tar.gz 64 bits], [https://projects.gctronic.com/epuck2/e-puck2-prog-main-micro-macos_14.02.23.zip Mac OS]<br/>
* Windows:  
+
2. Download the last version of the [https://projects.gctronic.com/epuck2/e-puck2_main-processor_26.04.23_f4f3582.elf main microcontroller factory firmware (26.04.23)], or use your custom firmware<br/>
<pre>esptool.exe --chip esp32 --port COM96 --baud 230400 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader.bin 0x10000 ESP32_E-Puck_2.bin 0x8000 partitions_singleapp.bin</pre>
+
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/>
Alternatively you can download the following batch file [http://projects.gctronic.com/epuck2/esp32-flashing.bat esp32-flashing.bat]
+
4. Attach the USB cable and turn on the robot<br/>
*Linux/Mac:
+
5. Run the script from the package directory:<br/>
<pre>python esptool.py --chip esp32 --port COM96 --baud 230400 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader.bin 0x10000 ESP32_E-Puck_2.bin 0x8000 partitions_singleapp.bin</pre>
+
:Windows: double click <code>program.bat</code><br/>
In all cases you need to specify the correct port (with <code>--port</code> parameter) that is the one labeled <code>Serial monitor</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]).
+
: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. Beware that the script requires the <code>pyserial</code> module, so install it by issuing <code>pip3 install pyserial</code><br/>
  
The upload should last about 10-15 seconds and you'll see the progress as shown in the following figure:<br/>
+
When the upload is complete you'll see an output like in the following figure:<br/>
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing1.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing1.png">]</span><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/>
When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure:<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.
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing2.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing2.png">]</span><br/>
 
  
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/>
+
===Troubleshooting===
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing3.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing3.png">]</span>
+
* If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.<br/>
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing4.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-flashing4.png">]</span><br/>
+
* If you still have problems, try by manually specifying the serial port at the top of the file <code>program_manual_conf.bat</code> (Windows) or <code>program_manual_conf.sh</code> (Linux/Mac) and run this script instead of <code>program.bat/program.sh</code>.
 +
* If you receive an error like <code>./program.sh: line 27: gcc-arm-none-eabi-7-2017-q4-major/bin/arm-none-eabi-gdb: Permission denied</code>, try issuing <code>sudo chmod -R +x gcc-arm-none-eabi-7-2017-q4-major</code> (for Linux/Mac users) and then retry.
  
==Connecting to the Bluetooth==
+
==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:
 +
# onboard image processing
 +
# swarm algorithms
 +
# fully autonomous behaviors
 +
# ...
 +
For more information about programming the robot itself, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development Robot side development]
  
The default firmware in the ESP32, the module which provides Bluetooth and Wi-Fi connectivity, creates 3 Bluetooth channels using the RFcomm protocol:
+
=Radio module=
# Channel 1, GDB: port to connect with GDB if the programmer is in mode 1 or 3 (refer to chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_Programmer.27s_settings Configuring the Programmer's settings] for more information about these modes)
+
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/>
# Channel 2, UART: port to connect to the UART port of the main processor
+
<span class="plain links"><img width=400 src="https://projects.gctronic.com/epuck2/wiki_images/esp32-peripherals.png"></span>
# Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
 
  
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<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.
'''To make it visible, it is necessary to hold the USER button (also labeled "esp32" on the electronic board) while turning on the robot with the ON/OFF button.'''<br>
 
Then it will be discoverable and you will be able to pair with it.<br>
 
Note that a prompt could ask you to confirm that the number written on the screen is the same on the e-puck. just ignore this and accept. Otherwise if you are asked for a pin insert 0000.
 
  
===Windows 7===
+
==Factory firmware==
When you pair your computer with the e-puck2, 3 COM ports will be automatically created.
+
The radio module of the robot is initially programmed with a firmware that supports Bluetooth communication.<br/>
To see which COM port corresponds to which channel you need to open the properties of the paired e-puck2 robot from <code>Bluetooth devices</code>. Then the ports and related channels are listed in the <code>Services</code> tab, as shown in the following figure:<br/>
+
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)].
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win7.png <img width=300 src="http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win7.png">]</span>
 
  
===Windows 10===
+
==WiFi firmware==
When you pair your computer with the e-puck2, 6 COM ports will be automatically created. The three ports you will use have <code>Outgoing</code> direction and are named <code>e_puck2_xxxxx-GDB</code>, <code>e_puck2_xxxxx-UART</code>, <code>e_puck2_xxxxx-SPI</code>. <code>xxxxx</code> is the ID number of your e-puck2.<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 [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi PC side development: WiFi].
To see which COM port corresponds to which channel you need to:
 
# open the Bluetooth devices manager
 
# pair with the robot
 
# click on <code>More Bluetooth options</code>
 
# the ports and related channels are listed in the <code>COM Ports</code> tab, as shown in the following figure:<br/>
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png <img height=300 src="http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png">]</span>
 
  
===Linux===
+
==BLE firmware==
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <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 [https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development Mobile phone development].
<code>sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2</code><br/>
 
The MAC address is visible from the Bluetooth manager. The parameter <code>2</code> indicates the channel, in this case a port for the <code>UART</code> channel is created. If you want to connect to another service you need to change this parameter accordingly (e.g. <code>1</code> for <code>GDB</code> and <code>3</code> for <code>SPI</code>). Now you can use <code>/dev/rfcomm0</code> to connect to the robot.
 
  
===Mac===
+
==Firmware update==
When you pair your computer with the e-puck2, 3 COM ports will be automatically created: <code>/dev/cu.e-puck2_xxxxx-GDB</code>, <code>/dev/cu.e-puck2_xxxxx-UART</code> and <code>/dev/cu.e-puck2_xxxxx-SPI</code>. xxxxx is the ID number of your e-puck2.
+
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/>
 +
1. Download the package containing the required tools and script to program the robot: [https://projects.gctronic.com/epuck2/e-puck2-prog-radio-windows_14.02.23.zip Windows], [https://projects.gctronic.com/epuck2/e-puck2-prog-radio-macos_14.02.23.zip Linux / Mac]<br/>
 +
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/>
 +
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/>
 +
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. Beware that the script requires the <code>pyserial</code> module, so install it by issuing <code>pip3 install pyserial</code><br/>
  
==Connecting to the WiFi==
+
The upload should last about 10-15 seconds and you'll see the progress as shown in the following figure:<br/>
At the moment the WiFi channel is used to transfer the image to the computer. A QQVGA color image is transferred.<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/>
A dedicated configuration is needed to use the WiFi, thus the robot and WiFi module firmwares need to be updated; moreover a PC application is provided to receive the camera image from the robot:
+
When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure:<br/>
# [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi_acfe134.elf main processor firmware] (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Flashing_the_main_microcontroller Flashing the main microcontroller]to update the firmware); put the selector in position 15
+
<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/>
# [http://projects.gctronic.com/epuck2/esp32-firmware-wifi-dba6816.zip WiFi module firmware] (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Flashing_the_radio_module Flashing the radio module] to update the firmware)
 
# PC application: [http://projects.gctronic.com/epuck2/esp32-wifi-pc.zip Windows executable]
 
  
The LED2 is used to indicate the state of the WiFi connection:
+
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. Try also by power cycle the robot various times during the ''Connecting'' phase.<br/>
* red indicates that the robot is in ''access point mode'' (waiting for configuration)
+
<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>
* green indicates that the robot is connected to a network and has received an IP address
+
<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/>
* blue (toggling) indicates that the robot is transferring the image to the computer
 
  
===Network configuration===
+
If you still have problems, try by manually specifying the serial port at the top of the file <code>program_manual_conf.bat</code> (Windows) or <code>program_manual_conf.sh</code> (Linux/Mac) and run this script instead of <code>program.bat/program.sh</code>.
If there is no WiFi configuration saved in flash, then the robot will be in ''access point mode'' in order to let the user connect to it and setup a WiFi connection. The LED2 is red.  
 
  
The access point SSID will be <code>e-puck2_0XXXX</code> where <code>XXXX</code> is the id of the robot; the password to connect to the access point is <code>e-puck2robot</code>.<br/>
+
==Development==
You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address <code>192.168.1.1</code>. The available networks are scanned automatically and listed in the browser page as shown in ''figure 1''. Choose the WiFi signal you want the robot to establish a conection with from the web generated list, and enter the related password; if the password is correct you'll get a message saying that the connection is established as shown in ''figure 2''. After pressing <code>OK</code> you will be redirected to the main page showing the network to which you're connected and the others available nearby as shown in ''figure 3''. If you press on the connected network, then you can see your IP address as shown in ''figure 4''; take note of the address since it will be needed later.<br/>
+
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 [https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development Radio module development].
  
<span class="plainlinks">
+
=Programmer=
<table>
+
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/>
<tr>
+
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.
<td align="center">[1]</td>
 
<td align="center">[2]</td>
 
<td align="center">[3]</td>
 
<td align="center">[4]</td>
 
</tr>
 
<tr>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png">]</td>
 
</tr>
 
</table>
 
</span><br/>
 
Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically.<br/>
 
Remember that you need to power cycle the robot at least once for the new configuration to be active.<br/>
 
  
Once the connection is established, the LED2 will be green.<br/>
+
==Factory firmware==
 +
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)].
  
In order to reset the current configuration you need to press the user button for 2 seconds (the LED2 red will turn on), then you need to power cycle the robot to enter ''access point mode''.
+
==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.
  
===Receiving the image===
+
::<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/>
Run the pc application and insert the IP address of the robot. Click on <code>Connect</code> to start receiving the image. The LED2 blue will toggle.<br/>
+
::''Location of the pin holes to put the programmer into DFU''
  
Often the IP address assigned to the robot will remain the same when connecting to the same network, so if you took note of the IP address in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Network_configuration Network configuration] probably you're ready to go. <br/>
+
The programmer will be recognized as <code>STM Device in DFU Mode</code> device.
Otherwise you need to connect the robot to the computer with the USB cable and open the port labeled <code>Serial Monitor</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]). Then power cycle the robot and the IP address will be shown in the terminal (together with others informations), as illustrated in the following figure:<br/>
 
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup5.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup5.png">]</span>
 
  
==Configuring the PATH variable==
+
'''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>
The PATH variable is a environment variable used to store a list of the paths to the folders containing the executables we can run in a terminal with Windows, Mac and Linux.
+
Follow the same procedure as explained in section [https://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 want to use the arm-none-eabi toolchain provided inside the Eclipse_e-puck2 package, you have to add it to the PATH variable to be able to call it inside a terminal window.
+
'''Note for users having robots id >= 5400''': the procedure is slightly different, please [https://www.gctronic.com/contact.php contact us] if you really need to update the programmer's firmware.
  
Setting the PATH variable for Windows :
+
===Linux/Mac===
<pre>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</pre>
+
In order to update the programmer firmware you need an utility called <code>dfu-util</code>, it should be already installed from section [https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates].<br/>
Setting the PATH variable for Linux :
+
To uplaod the firmware, issue the following command: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D programmer-firmware.bin</code>
<pre>export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</pre>
 
Setting the PATH variable for Mac :
 
<pre>export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</pre>
 
  
What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the PATH variable.
+
===Windows===
 
+
Start the <code>DfuSe</code> application (previously installed from section [https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates]). The programmer in DFU mode will be automatically detected as shown in figure 1. Then you need to open the compiled firmware by clicking on <code>choose</code> and then locating the file with <code>dfu</code> extension,  as shown in figure 2. Now click on the <code>upgrade</code> button, a warning message will be shown, confirm the action by clicking on <code>yes</code> as shown in figure 3. If all is ok you'll be prompted with a message saying that the upgrade was successfull as shown in figure 4.<br/>
Note : The arm-none-eabi version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
 
 
 
=Software=
 
==PC interface==
 
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/monitor.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/monitor_small.png">]<br/>
 
An interface running on a computer and connecting to the e-puck2 either through Bluetooth (selector position 3) or via USB (selector position 8) based on the advanced sercom protocol was developed; from this interface it's possible to have information about all the sensors, receive camera images and control the leds and motors. The source code is available from the repository [https://github.com/e-puck2/monitor https://github.com/e-puck2/monitor].
 
Available executables:
 
* [http://projects.gctronic.com/epuck2/monitor_win.zip Windows executable]: tested on Windows 7 and Windows 10
 
* [http://projects.gctronic.com/epuck2/monitor_mac.zip Max OS X executable]
 
 
 
On Linux remember to apply the configuration explained in the chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Serial_Port Installation for Linux - Serial Port] in order to access the serial port.
 
 
 
==Main microcontroller firmware==
 
The robot is initially programmed with a firmware that includes many demos that could be started based on the selector position:
 
* Selector position 0: Aseba
 
* Selector position 1: Shell
 
* Selector position 2: Read proximity sensors
 
* Selector position 3: Asercom protocol v2 (BT)
 
* Selector positoin 4: Read IMU raw sensors values
 
* Selector position 5: Distance sensor reading
 
* Selector position 6: ESP32 UART communication test
 
* Selector position 7: ...
 
* Selector position 8: Asercom protocol v2 (USB)
 
* Selector position 9: Asercom protocol (BT)
 
* Selector position 10: This position is used to work with the gumstix extension.
 
* 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: ...
 
* Selector position 15: ...
 
The source code is available in the git repo [https://github.com/e-puck2/e-puck2_main-processor https://github.com/e-puck2/e-puck2_main-processor].<br/>
 
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_main-processor_23.04.18_3988f7c.elf e-puck2-firmware].
 
===Flashing the main microcontroller===
 
Refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Flashing_the_main_microcontroller Flashing the main microcontroller].
 
===WiFi support===
 
At the moment there is a separate firmware if the user want to use the WiFi; this firmware was specifically developed to transmit the camera image to the computer.<br/>
 
In the future the WiFi support will be integrated in the standard firmware.<br/>
 
The source code can be downloaded with the command <code>git clone -b wifi --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
 
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi_acfe134.elf e-puck2-firmware_wifi].
 
 
 
==Library==
 
The library contains all the functions needed to interact with the robot's sensors and actuators; the project includes also the basic standard firmware that shows how to use these functions.<br/>
 
A snapshot of the library can be donwloaded from [http://projects.gctronic.com/epuck2/e-puck2_main-processor_snapshot_16.02.18_13fa922.zip e-puck2_main-processor_snapshot_16.02.18.zip].<br/>
 
Otherwise the latest version can be downloaded with the command: <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
 
If you don't have <code>git</code>, you can issue the command: <code>sudo apt-get install git</code>.
 
 
 
==Programmer firmware==
 
This firmware is based on [https://github.com/blacksphere/blackmagic/wiki Black Magic Probe programmer/debugger].<br/>
 
The source code can be downloaded with the command <code>git clone --recursive -b e-puck-2.0_E https://github.com/e-puck2/e-puck2-programmer</code><br/>
 
In order to build the firmware you need to issue the following commands form the main repo directory:<br/>
 
<code>make clean</code><br/>
 
<code>make PROBE_HOST=e-puck/2.0</code><br/>
 
The result is a bin file named <code>blackmagic.bin</code> that you can find in the <code>src</code> directory.<br/>
 
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/programmer-firmware_09.04.18_252d604.bin programmer-firmware.bin]; it is also available in dfu format here [http://projects.gctronic.com/epuck2/programmer-firmware_09.04.18_252d604.dfu programmer-firmware.dfu].
 
 
 
===Flashing the programmer===
 
First of all to update the programmer's firmware you need to enter DFU mode (device firmware upgrade). To do it refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Using_the_DFU Using the DFU], in particular Note 2.<br/>
 
The programmer will be recognized as <code>STM Device in DFU Mode</code> device.
 
 
 
====Linux====
 
In order to update the programmer firmware you need an utility called <code>dfu-util</code>.<br/>
 
To install it issue the command <code>sudo apt-get install dfu-util</code>.<br/>
 
Then issue the following command to upload the firmware: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D programmer-firmware.bin</code>
 
 
 
====Windows====
 
For Windows users it is available an application called <code>DfuSe</code> released by STMicroelectronics. You can download it from [http://projects.gctronic.com/epuck2/en.stsw-stm32080_DfuSe_Demo_V3.0.5.zip DfuSe_V3.0.5.zip].<br/>
 
When the program is started, the programmer in DFU mode will be automatically detected as shown in figure 1. Then you need to open the compiled firmware by clicking on <code>choose</code> and then locating the file,  as shown in figure 2. Now click on the <code>upgrade</code> button, a warning message will be shown, confirm the action by clicking on <code>yes</code> as shown in figure 3. If all is ok you'll be prompted with a message saying that the upgrade was successfull as shown in figure 4.<br/>
 
 
<span class="plainlinks">
 
<span class="plainlinks">
 
<table>
 
<table>
Line 601: Line 425:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>[http://projects.gctronic.com/epuck2/wiki_images/dfu1.png <img width=250 src="http://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>[http://projects.gctronic.com/epuck2/wiki_images/dfu2.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/dfu2.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>[http://projects.gctronic.com/epuck2/wiki_images/dfu3.png <img width=250 src="http://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>[http://projects.gctronic.com/epuck2/wiki_images/dfu4.png <img width=250 src="http://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>
 
</tr>
 
</tr>
 
</table>
 
</table>
 
</span><br/>
 
</span><br/>
  
==Radio module firmware==
+
==Development==
The firmware support Bluetooth communication.<br/>
+
The programmer code shouldn't be modified, but if you know what you're doing then refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development Programmer development].
The source code can be downloaded with the command <code>git clone --recursive https://github.com/e-puck2/esp-idf.git</code><br/>
 
In order to build the firmware you need to install the toolchain, refer to [http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain]. Once installed you can issue the command <code>make flash</code> from the directory <code>Projects\ESP32_E-Puck_2</code> to build the firmware. For more information have a look at [http://esp-idf.readthedocs.io/en/latest/get-started/#build-and-flash http://esp-idf.readthedocs.io/en/latest/get-started/#build-and-flash].<br/>
 
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/esp32-firmware_26.01.18_37db240.zip esp32-firmware.zip].
 
 
 
===Flashing the radio module===
 
Refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Flashing_the_radio_module Flashing the radio module].
 
 
 
===WiFi support===
 
At the moment there is a separate firmware if the user want to use the WiFi; this firmware was specifically developed to transmit the camera image to the computer.<br/>
 
In the future the WiFi support will be integrated in the standard firmware.<br/>
 
The source code can be downloaded with the command <code>git clone -b wifi --recursive https://github.com/e-puck2/esp-idf.git</code><br/>
 
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/esp32-firmware-wifi-dba6816.zip esp32-firmware_wifi.zip].
 
 
 
=Advanced usage=
 
==Configuring the Programmer's settings==
 
The on-board programmer of the e-puck2 is based on the [https://github.com/blacksphere/blackmagic/wiki Blackmagic probe open source project] firmware. <br>
 
Some functionalities has been added on top of the original project to be able to control some functions of the robot, for example the power on or power off.
 
 
 
To access to the available commands of the programmer, it is needed to connect to the programmer with a GDB console. <br>
 
To do so, you have to type the following command in a terminal window with the com port used by the '''e-puck2 GDB Server'' port of your e-puck2 :
 
<pre>
 
arm-none-eabi-gdb
 
target extended-remote your_gdb_com_port
 
</pre>
 
 
 
Once connected to the programmer with GDB, you can type
 
<pre>monitor help</pre> or <pre>mon help</pre> to print the available commands of the programmer.
 
 
 
One command in particular is useful, which is mon select_mode. It is used to select in which mode the  '''e-puck2 Serial Monitor''' com port will work.<br>
 
mode 1 = the serial monitor is connected to the UART port of the main processor<br>
 
mode 2 = the serial monitor is connected to the UART of the ESP32<br>
 
mode 3 = the serial monitor works as a Aseba CAN to USB translator<br>
 
 
 
The choice made for the mode is the only setting that is stored in a flash zone of the programmer, which means the choice is remembered, even if the robot is completely turned off.
 
 
 
Note : in mode 1 and 3, GDB can be used over the bluetooth connection of the e-puck2. But is is much slower than with USB and it doesn't work with Windows due to GDB limitations on this OS.
 
 
 
By being connected with GDB, you can also use the standard GDB command to program and debug the main processor of the e-puck2.
 
 
 
==Using the DFU==
 
To put the e-puck2 into DFU, it is needed to turn it on while keeping pressed the "407 boot" button located under the electronic card on the left side of the robot.<br>
 
The robot will appear as "STM32 BOOTLOADER" in the USB devices.
 
 
 
Once in DFU, you can program it with [http://dfu-util.sourceforge.net dfu-util]  using the following command :
 
<pre>dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin</pre>
 
 
 
See the [http://dfu-util.sourceforge.net/dfu-util.1.html manual page] of dfu-util for further information on how to use it.
 
 
 
'''Note''': For windows, it is needed to install a libusbK driver for the DFU device. <br>
 
You can use the Zadig program located in the Eclipse_e-puck2\Tools\ (if you installed Eclipse_e-puck2 package) to install it. <br>
 
Follow the same procedure as explained above under the [[#Drivers | Installation drivers]] section using libusbK driver instead of USB Serial (CDC).
 
 
 
'''Note 2''': It is also possible to put the programmer in DFU by contacting two pinholes together while inserting the USB cable (no need to turn on the robot).<br>
 
It is used to update the firmware of the programmer.<br>
 
The two pin holes are located near the USB connector of the e-puck2, see the photo below.
 
 
 
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds_DFU_413.png <img width=200 src="http://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''
 

Latest revision as of 14:57, 10 January 2024

1 Hardware

1.1 Overview


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

1.2 Specifications

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

Feature e-puck version 1.3 e-puck version 2 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:

1.3 Documentation

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

1.4 Migrating from e-puck version 1.x to e-puck version 2

The e-puck version 2 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-puck version 1.x, isn't anymore needed in the e-puck version 2. The components available on the e-jumper are integrated directly in the robot board. On top of the e-puck version 2 you'll see a quite big free connector, this is used to attach the extensions board designed for the e-puck version 1.x that are fully compatible with the e-puck version 2; 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-puck version 1.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.

1.5 Extensions

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

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

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

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

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


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

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

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

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

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

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

2.6.1 Available executables

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

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

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

2.7.2 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

2.7.3 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

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

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

3.1 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 or transmitter, switch between them with button)
  • 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(A): 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(B): Simple obstacle avoidance + some animation
  • Selector position 12(C): Hardware test
  • Selector position 13(D): LEDs reflect orientation of the robot
  • Selector position 14(E): Compass
  • Selector position 15(F): WiFi mode

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

3.2 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 (26.04.23), 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. Beware that the script requires the pyserial module, so install it by issuing pip3 install pyserial

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.

3.2.1 Troubleshooting

  • If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.
  • If you still have problems, try by manually specifying the serial port at the top of the file program_manual_conf.bat (Windows) or program_manual_conf.sh (Linux/Mac) and run this script instead of program.bat/program.sh.
  • If you receive an error like ./program.sh: line 27: gcc-arm-none-eabi-7-2017-q4-major/bin/arm-none-eabi-gdb: Permission denied, try issuing sudo chmod -R +x gcc-arm-none-eabi-7-2017-q4-major (for Linux/Mac users) and then retry.

3.3 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

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

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

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

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

4.4 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. Beware that the script requires the pyserial module, so install it by issuing pip3 install pyserial

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. Try also by power cycle the robot various times during the Connecting phase.

If you still have problems, try by manually specifying the serial port at the top of the file program_manual_conf.bat (Windows) or program_manual_conf.sh (Linux/Mac) and run this script instead of program.bat/program.sh.

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

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

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

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

Note for users having robots id >= 5400: the procedure is slightly different, please contact us if you really need to update the programmer's firmware.

5.2.1 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

5.2.2 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]


5.3 Development

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