Difference between pages "e-puck2" and "e-puck2 PC side development"

From GCtronic wiki
(Difference between pages)
Jump to: navigation, search
(WiFi communication protocol)
 
(Multiple robots)
 
Line 1: Line 1:
=Hardware=
+
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
==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">[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/>
 
  
The following figures show the main components offered by the e-puck2 robot and where they are physically placed:<br/>
+
=Robot configuration=
<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/>
+
This section explains how to configure the robot based on the communication channel you will use for your developments, thus you need to read only one of the following sections, but it would be better if you spend a bit of time reading them all in order to have a full understanding of the available configurations.
  
==Specifications==
+
==USB==
The e-puck2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):
+
The main microcontroller is initially programmed with a firmware that support USB communication.<br/>
{| border="1"
 
|'''Feature'''
 
|'''e-puck1.3'''
 
|'''e-puck2'''
 
|'''Compatibility'''
 
|'''Additional'''
 
|-
 
|Size, weight
 
|70 mm diameter, 55 mm height, 150 g
 
|Same form factor: 70 mm diameter, 45 mm, 130 g
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|No e-jumper required
 
|-
 
|Battery, autonomy
 
|LiIPo rechargeable battery (external charger), 1800 mAh. <br/>About 3 hours autonomy. Recharging time about 2-3h.
 
|Same battery; USB charging, recharging time about 2.5h.
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|USB charging
 
|-
 
|Processor
 
|16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing
 
|32-bit STM32F407 @ 168 MHz (210 DMIPS), DSP and FPU, DMA
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|~10 times faster
 
|-
 
|Memory
 
|RAM: 8 KB; Flash: 144 KB
 
|RAM: 192 KB; Flash: 1024 KB
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|RAM: 24x more capable<br/>Flash:~7x more capable
 
|-
 
|Motors
 
|2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution
 
|Same motors
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Wheels
 
|Wheels diamater = 41 mm <br/>Distance between wheels = 53 mm
 
|Same wheels
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Speed
 
|Max: 1000 steps/s (about 12.9 cm/s)
 
|Max: 1200 steps/s (about 15.4 cm/s)
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|20% faster
 
|-
 
|Mechanical structure
 
|Transparent plastic body supporting PCBs, battery and motors
 
|Same mechanics
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Distance sensor
 
|8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm
 
|Same infra-red sensors <br/>Front real distance sensor, Time of fight (ToF), up to 2 meter.
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|ToF sensor
 
|-
 
|IMU
 
|3D accelerometer and 3D gyro
 
|3D accelerometer, 3D gyro, 3D magnetometer
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|3D magnetometer
 
|-
 
|Camera
 
|VGA color camera; typical use: 52x39 or 480x1
 
|Same camera; typical use: 160x120
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|Bigger images handling
 
|-
 
|Audio
 
|3 omni-directional microphones for sound localization<br/>speaker capable of playing WAV or tone sounds
 
|4 omni-directional microhpones (digital) for sound localization<br/>speaker capable of playing WAV or tone sounds
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
| +1 front microphone
 
|-
 
|LEDs
 
|8 red LEDs around the robot, green body light, 1 strong red LED in front
 
|4 red LEDs and 4 RGB LEDs around the robot, green light, 1 strong red LED in front
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|4x RGB LEDs
 
|-
 
|Communication
 
|RS232 and Bluetooth 2.0 for connection and programming
 
|USB Full-speed, Bluetooth 2.0, BLE, WiFi
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|WiFi, BLE
 
|-
 
|Storage
 
|Not available
 
|Micro SD slot
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|Micro SD
 
|-
 
|Remote Control
 
|Infra-red receiver for standard remote control commands
 
|Same receiver
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Switch / selector
 
|16 position rotating switch
 
|Same selector
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Extensions
 
|Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own
 
|All extension supported
 
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|
 
|-
 
|Programming
 
|Free C compiler and IDE, Webots simulator, external debugger
 
|Free C compiler and IDE, Webots simulator, onboard debugger (GDB)
 
|style="text-align:center;" | <img width=30 src="http://www.gctronic.com/doc/images/plus.png">
 
|Onboard debugger
 
|}
 
 
 
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/>
 
 
 
==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]
 
* '''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]
 
* '''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]
 
* '''Camera''': PixelPlus PO8030D CMOS image sensor, [http://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]
 
* '''Optical sensors''': Vishay Semiconductors Reflective Optical Sensor, [http://projects.gctronic.com/epuck2/doc/tcrt1000.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]
 
* '''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]
 
* '''Motors''': [http://www.e-puck.org/index.php?option=com_content&view=article&id=7&Itemid=9 details]
 
* '''Speaker''': Diameter 13mm, power 500mW, 8 Ohm, DS-1389 or PSR12N08AK or similar
 
* '''IR receiver''': TSOP36230
 
 
 
=Installation of the e-puck2 environment=
 
Some programs are needed to program the e-puck2.
 
 
 
#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'''.
 
#Drivers must also be installed for Windows older than Windows 10.
 
 
 
==Installation for Windows==
 
===Java 8 32bits===
 
This section can be ignored if Java version 8 32bits is already installed on your computer.<br>
 
To verify, you 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.
 
#Run the downloaded installer and follow its instructions to proceed with the installation of Java 32bits.
 
#Close the internet browser if it opened at the end of the installation.
 
 
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png">]</span><br/>
 
:''Java download page''
 
 
 
===Eclipse_e-puck2===
 
#Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Win32_11_apr_2018.zip Eclipse_e-puck2 package for windows].
 
#Unzip the downloaded file to the location you want (can take time). It is strongly recommended for better performance and less extraction time to use 7Zip. You can download it on http://www.7-zip.org.
 
#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 :'''
+
If the main microcontroller isn't programmed with the factory firmware or if you want to be sure to have the last firmware on the robot, you need to program it with the last factory firmware by referring to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update].<br/>
: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===
+
The radio module can be programmed with either the <code>Bluetooth</code> or the <code>WiFi</code> firmware, both are compatible with USB communication:
In order to let Eclipse (or any program ran by you) to access the serial ports, a little configuration is needed.
+
* Bluetooth: refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 +
* WiFi: download the [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)] and then refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
  
Type the following command in a terminal session. Once done, you need to log off to let the change take effect.
+
When you want to interact with the robot from the computer you need to place the selector in position 8 to work with USB. <br/>
  
<pre>sudo adduser $USER dialout</pre>
+
Section [http://www.gctronic.com/doc/index.php?title=e-puck2#PC_interface PC interface] gives step by step instructions on how to connect the robot with the computer via USB.<br/>
  
==Installation for Mac==
+
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2], refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB_2 Communication protocol: BT and USB] for detailed information about this protocol.<br/>
===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===
+
==Bluetooth==
This section can be ignored if Java is already installed on your computer.<br>
+
The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication.<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.  
+
If the main microcontroller and radio module aren't programmed with the factory firmware or if you want to be sure to have the last firmwares on the robot, you need to program them with the last factory firmwares:
::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
+
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
:2. Open the .dmg file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.
+
* for the radio module, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
  
:<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/>
+
When you want to interact with the robot from the computer you need to place the selector in position 3 if you want to work with Bluetooth. <br/>
:''Java download page''
 
  
===Eclipse_e-puck2===
+
Section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth] gives step by step instructions on how to accomplish your first Bluetooth connection with the robot.<br/>
: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===
+
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2], refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB Communication protocol: BT and USB] for detailed information about this protocol.<br/>
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 :
+
==WiFi==
 +
For working with the WiFi, the main microcontroller must be programmed with the factory firmware and the radio module must be programmed with a dedicated firmware (not the factory one):
 +
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
 +
* [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)], for information on how to update the firmware refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 +
Put the selector in position 15.<br/>
  
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
+
Section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi Connecting to the WiFi] gives step by step instructions on how to accomplish your first WiFi connection with the robot.<br/>
  
::<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/>
+
The communication protocol is described in detail in the section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi].<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.
+
=Connecting to the Bluetooth=
::<pre>sudo spctl --master-disable</pre>
 
: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.
+
The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer:
 
+
# 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_programmer_development#Configuring_the_Programmer.27s_settings Configuring the Programmer's settings] for more information about these modes)
'''Important things to avoid :'''
 
:1. The path to the Eclipse_e-puck2.app must contain zero space.
 
::Example :
 
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
 
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
 
:2. The file’s structure in the 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===
 
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/>
 
::''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 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.
 
 
 
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.
 
 
 
==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 with Eclipse_e-puck2 (GDB).
 
* '''e-puck2 Serial Monitor'''. A serial monitor. [[#see dedicated chapter(not yet ready)]]
 
 
 
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.
 
===Windows===
 
#Open the Device Manager
 
#Under '''Ports (COM & LPT)''' you can see the virtual ports connected to your computer.
 
#Do a '''Right-click -> properties''' on the COM port you want to identify.
 
#Go under the '''details''' tab and select '''Bus reported device description''' in the properties list.
 
#The name of the port should be written in the text box below.
 
#Once you found the desired device, you can simply look at its port number '''(COMX)'''.
 
 
 
===Linux===
 
:1. Open a terminal window (ctrl+alt+t) and enter the following command.
 
:<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'''.
 
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===
 
:1. Open a terminal window and enter the following command.
 
:<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, 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.
 
 
 
==Configuring the Debugger's settings==
 
Eclipse_e-puck2 contains everything needed to compile, program and debug the e-puck2.<br>
 
The only settings to configure with a new project are located under the '''Debug Configurations''' tab of Eclipse (you can also find it on '''Run->Debug Configurations''').
 
:<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/>
 
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 apply the next configuration.
 
#Under the '''Startup''' tab, you need to replace the path to the serial port written on the first line of the text box by the one used by the GDB Server of your e-puck. [[#Finding the USB serial ports used | See how to find it]].
 
:* For Windows, it will be '''\\.\COMX''', X being the port number.
 
:* For Linux, it will be '''/dev/ttyACMX''', X being the port number
 
:* For Mac, it will be '''/dev/cu.usbmodemXXXXX''', XXXXX being the port number.
 
:* You can also type '''${COM_PORT}''' instead of the com port in order to use the variable COM_PORT for the debug configuration.<br>To change the value of this variable, go to the '''main''' tab again, click on the '''Variables...''' button and click on the '''Edit Variables...''' button. The opened window will let you edit the value of the variable.<br>Using the variable COM_PORT instead of the real com port in a debug configuration is useful if you have multiple debug configurations for example. If for one reason you need to change the com port to use, then you can simply edit the variable COM_PORT instead of editing the com port for each debug configuration
 
 
 
If you want to debug another project, you can change the settings of the '''Generic Blackmagic Probe''' preset or copy it into another preset and configure this one in order to have one preset by project.
 
Now you should be able to use the debugger with Eclipse.
 
 
 
==Creating a project==
 
===Basic standard project===
 
[https://github.com/e-puck2/e-puck2_main-processor.git e-puck2_main-processor] is the basic standard project containing all the libraries written for the e-puck2. Refer to the [http://www.gctronic.com/doc/index.php?title=e-puck2#Library Library] section to download the complete version.<br>
 
The basic standard project shows how to use the libraries and can be interfaced with [[#PC interface | e-puck2 monitor]].<br/>
 
This project can be added to Eclipse_e-puck2 by following the next steps:<br>
 
# 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===
 
The basic standard project can also be used as a library to build your own project on top of it.<br>
 
 
 
To accomplish that, you have to copy the folder '''Project_template''', contained in the e-puck2_main-processor project, where you want to place your project.<br>
 
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 desired .h files from other folders.<br>
 
All the .h files located next to the makefile are automatically included in the compilation. But if you need to place them into folders, you have to specify these folders in the makefile.
 
This makefile uses the main makefile of the e-puck2_main-processor project. This means you can add custom commands to the makefile but it should not interfere with the main makefile.
 
 
 
The result of the compilation will appear in a build folder in your project folder.
 
 
 
===Adding to Eclipse_epuck2===
 
#To add the project into Eclipse, you need to select '''File->New->Makefile Project with Existing Code'''.
 
#Next choose your project folder and set a project name. Choose '''None''' for the the toolchain.
 
#Click on the '''Finish''' button and the project is added to Eclipse.
 
#Rename the file '''Debug_project_template.launch''' contained in the project folder by the name you want for the debug configuration of your project.
 
#Go to '''Run->Debug Configurations...''' and select on the left your new debug configuration and set the project to debug and the path to the compiled file of the project ([[#Configuring the Debugger's settings |as explained in the chapter before]]). If there is nothing apering when you press '''Search Project...''' then you must enter the '''.elf''' file name by hand, which can be found in your project folder under a folder named '''build'''.
 
#Go to  '''Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers''' and Check '''CDT Cross GCC Built-in Compiler Settings'''.<br> Then in the textbox below, write '''arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"'''.
 
#Create a linked folder inside your project that links to the e-puck2_main-processor library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
 
##Go to '''File->New->Folder'''.
 
##Check '''Advanced >>''' on the bottom.
 
##Choose '''Link to alternate location (Linked Folder)'''.
 
##Type '''PROJECT_LOC''' and then add to this path the path to the e-puck2_main-processor folder. For example '''PROJECT_LOC/../e-puck2_main-processor''' if the library is located as the same level as your project folder.
 
#Before you compile, make sure the robot is turned on, and in addition make sure that the Makefile, has a capital M in the front.
 
#After you compile the project and if it succeeded, select the project root folder and go to '''Project->C/C++ Index->Rebuild''' to rebuild the index. (We need to have compiled at least one time in order to let Eclipse find all the paths to the files used.)
 
 
 
You should now be able to use the project with Eclipse.
 
 
 
==Flashing the main microcontroller==
 
In order to update the firmware of the main microcontroller (STM32F407) you can either use Eclipse (as explained in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_Debugger.27s_settings Configuring the Debugger settings]) or you can do it manually as explained in this section. The onboard programmer run a gdb server, so we can use gdb commands to upload a new firmware.<br/>
 
1. download the gdb init file [http://projects.gctronic.com/epuck2/mygdbinit mygdbinit] and place it in the same folder of the compiled firmware. This file has the following content:
 
<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
 
<pre>Windows: arm-none-eabi-gdb.exe --interpreter=mi -x mygdbinit firmware.elf
 
Linux/Mac: arm-none-eabi-gdb --interpreter=mi -x mygdbinit firmware.elf</pre>
 
In this command you need to change the name of the firmware with the one you have.<br/>
 
Moreover if the <code>PATH</code> variable is not set (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Configuring_the_PATH_variable Configuring the PATH variable]) you need to insert the absolute path to the debugger that you can find in the Eclipse package (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Installation_of_the_e-puck2_environment Installation of the e-puck2 environment]) inside the directory <code>Tools\gcc-arm-none-eabi-XXX\bin</code>.
 
 
 
When the upload is complete you'll see an output like in the following figure:<br/>
 
<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 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.
 
 
 
If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.
 
 
 
==Flashing the radio module==
 
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:
 
* Windows: [http://projects.gctronic.com/epuck2/esptool.exe esptool.exe]; Python not required on the system.
 
* 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.
 
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:
 
* Windows:
 
<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>
 
Alternatively you can download the following batch file [http://projects.gctronic.com/epuck2/esp32-flashing.bat esp32-flashing.bat]
 
*Linux/Mac:
 
<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>
 
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]).
 
 
 
The upload should last about 10-15 seconds and you'll see the progress as shown 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/>
 
When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure:<br/>
 
<span class="plain links">[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/>
 
<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>
 
<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/>
 
 
 
==Connecting to the Bluetooth==
 
 
 
The default firmware in the ESP32, the module which provides Bluetooth and Wi-Fi connectivity, creates 3 Bluetooth channels using the RFcomm protocol:
 
# 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)
 
 
# Channel 2, UART: port to connect to the UART port of the main processor
 
# Channel 2, UART: port to connect to the UART port of the main processor
 
# Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
 
# Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
Line 437: Line 51:
 
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<br>
 
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<br>
 
'''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>
 
'''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>
 +
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-bt-pair.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-bt-pair-small.png">]</span><br/>
 
Then it will be discoverable and you will be able to pair with it.<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.
 
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===
+
==Windows 7==
 
When you pair your computer with the e-puck2, 3 COM ports will be automatically created.
 
When you pair your computer with the e-puck2, 3 COM ports will be automatically created.
 
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/>
 
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/>
 
<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>
 
<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===
+
==Windows 10==
 
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/>
 
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/>
 
To see which COM port corresponds to which channel you need to:
 
To see which COM port corresponds to which channel you need to:
Line 454: Line 69:
 
:<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>
 
:<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===
+
==Linux==
 
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <br/>
 
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <br/>
 
<code>sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2</code><br/>
 
<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.
 
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===
+
==Mac==
 
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.
 
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.
  
==Connecting to the WiFi==
+
==Testing the Bluetooth connection==
At the moment the WiFi channel is used to transfer the image to the computer (a QQVGA color image is transferred) together with the sensors values (magnetometer, selector and tv remote not supported at the moment). The robot is also able to receive commands from the computer (only motors and red LEDs are supported at the moment).<br/>
+
You need to download the PC application provided in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Available_executables PC interface: available executables].<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 data from the robot and send commands to it:
+
In the connection textfield you need to enter the UART channel port, for example:
# [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi_97d247f.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. If you are interested to the source code, refer to chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_support_2 Main microcontroller - WiFi support].
+
* Windows 7: <code>COM258</code>
# [http://projects.gctronic.com/epuck2/esp32-firmware-wifi-d4ff7b4.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). If you are interested to the source code, refer to chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_support_3 Radio module - WiFi support].
+
* Windows 10: <code>e_puck2_xxxxx-UART</code>
# PC application: [http://projects.gctronic.com/epuck2/monitor-wifi_e9cf9f9.zip Monitor WiFi]. If you are interested to the source code, refer to chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_support PC interface - WiFi support].
+
* Linux: <code>/dev/rfcomm0</code>
 +
* Mac: <code>/dev/cu.e-puck2_xxxxx-UART</code>
 +
and then click <code>Connect</code>. <br/>
 +
You should start receiving sensors data and you can send commands to the robot.<br/>
 +
 
 +
Alternatively you can also use a simple terminal program (e.g. <code>realterm</code> in Windows) instead of the PC application, then you can issue manually the commands to receive sensors data or for setting the actuators (once connected, type <code>h + ENTER</code> for a list of availables commands).
 +
 
 +
==Python examples==
 +
Here are some basic Python examples that show how to get data from the robot through Bluetooth using the commands available with the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2]:
 +
* [http://projects.gctronic.com/epuck2/printhelp.py printhelp.py]: print the list of commands available in the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2]
 +
* [http://projects.gctronic.com/epuck2/getprox.py getprox.py]: print the values of the proximity sensors
 +
* [http://projects.gctronic.com/epuck2/complete.py complete.py]: set all the actuators and get all the sensors data printing their values on the screen
 +
* [http://projects.gctronic.com/epuck2/getimage.py getimage.py]: request an image and save it to disk
 +
In all the examples you need to set the correct Bluetooth serial port related to the robot.
 +
 
 +
===Connecting to multiple robots===
 +
Here is a simple Python script [http://projects.gctronic.com/epuck2/multi-robot.py multi-robot.py] that open a connection with 2 robots and exchange data with them using the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol]. This example can be extended to connect to more than 2 robots.
 +
 
 +
==C++ remote library==
 +
A remote control library implemented in C++ is available to control the e-puck2 robot via a Bluetooth connection from the computer.<br/>
 +
The remote control library is multiplatform and uses only standard C++ libraries.<br/>
 +
You can download the library with the command <code>git clone https://github.com/e-puck2/e-puck2_cpp_remote_library</code>.<br/>
 +
A simple example showing how to use the library is also available; you can download it with the command <code>git clone https://github.com/e-puck2/e-puck2_cpp_remote_example</code>.<br/>
 +
Before building the example you need to build the library. Then when building the example, make sure that both the library and the example are in the same directory, that is you must end up with the following directory tree:<br>
 +
: e-puck2_projects
 +
::|_ e-puck2_cpp_remote_library
 +
::|_ e-puck2_cpp_remote_example
 +
The complete API reference is available in the following link [http://projects.gctronic.com/epuck2/e-puck2_cpp_remote_library_api_reference_rev3ac41e3.pdf e-puck2_cpp_remote_library_api_reference.pdf].
 +
 
 +
=Connecting to the WiFi=
 +
The WiFi channel is used to communicate with robot faster than with Bluetooth. At the moment a QQVGA (160x120) color image is transferred to the computer together with the sensors values at about 10 Hz; of course the robot is also able to receive commands from the computer.<br/>
 +
In order to communicate with the robot through WiFi, first you need to configure the network parameters on the robot by connecting directly to it, since the robot is initially configured in access point mode, as explained in the following section. Once the configuration is saved on the robot, it will then connect automatically to the network and you can connect to it.
  
 
The LED2 is used to indicate the state of the WiFi connection:
 
The LED2 is used to indicate the state of the WiFi connection:
Line 473: Line 119:
 
* green indicates that the robot is connected to a network and has received an IP address
 
* green indicates that the robot is connected to a network and has received an IP address
 
* blue (toggling) indicates that the robot is transferring the image to the computer
 
* blue (toggling) indicates that the robot is transferring the image to the computer
 +
* off when the robot cannot connect to the saved configuration
 +
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-led.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-led-small.png">]</span><br/>
  
===Network configuration===
+
==Network configuration==
 
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.  
 
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/>
 
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/>
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/>
+
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''; <b>take note of the address since it will be needed later</b>.<br/>
  
 
<span class="plainlinks">
 
<span class="plainlinks">
Line 502: Line 150:
  
 
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''.
 
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''.
 +
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset-small.png">]</span><br/>
  
===Receiving the image===
+
==Finding the IP address==
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/>
+
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] you're ready to go to the next section. <br/>
  
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/>
+
Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to 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/>
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>
 
<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==
+
==Testing the WiFi connection==
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.
+
A dedicated WiFi version of the PC application was developed to communicate with the robot through TCP protocol. You can download the executable from one of the following links:
 +
* [http://projects.gctronic.com/epuck2/monitor_wifi_27dddd4.zip Windows executable - WiFi]
 +
* Mac (not available yet)
 +
* [http://projects.gctronic.com/epuck2/monitor_wifi_linux64bit_27dddd4.tar.gz Ubuntu 14.04 (or later) - 64 bit]
  
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.
+
If you are interested to the source code, you can download it with the command <code>git clone -b wifi --recursive https://github.com/e-puck2/monitor.git</code><br/>
  
Setting the PATH variable for Windows :
+
Run the PC application, insert the IP address of the robot in the connection textfield and then click on the <code>Connect</code> button. You should start receiving sensors data and you can send commands to the robot. The LED2 blue will toggle.<br/>
<pre>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</pre>
 
Setting the PATH variable for Linux :
 
<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.
+
==Web server==
 +
When the robot is in ''access point mode'' you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface.<br/>
 +
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/monitor.html</code>.
  
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.
+
==Python examples==
 +
===Connecting to multiple robots===
 +
A simple Python 3 script was developed as a starting point to open a connection with multiple robots and exchange data with them using the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 WiFi communication protocol]. The demo was tested with 10 robots but can be easily extended to connect to more robots.<br/>
 +
You can download the script with the command <code>git clone https://github.com/e-puck2/e-puck2_python_wifi_multi.git</code>. The code was tested to work with Python 3.x.
  
=Software=
+
=Communication protocol=
==PC interface==
+
This section is the hardest part to understand. It outlines all the details about the communication protocols that you'll need to implement in order to communicate with the robot form the computer. So spend a bit of time reading and re-reading this section in order to grasp completely all the details.
<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.
+
==Bluetooth and USB==
 
+
The communication protocol is based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol], used with the e-puck1.x robot. The <code>advanced sercom v2</code> includes all the commands available in the <code>advanced sercom</code> protocol and add some additional commands to handle the new features of the e-puck2 robot. In particular here are the new commands:
===WiFi support===
+
{| border="1" cellpadding="10" cellspacing="0"
A dedicated WiFi version of the monitor application was developed to communicate with the robot through TCP protocol.<br/>
+
!Command
For more information about the communication protocol, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_communication_protocol WiFi communication protocol].<br/>
+
!Description
The source code can be downloaded with the command <code>git clone -b wifi --recursive https://github.com/e-puck2/monitor.git</code><br/>
+
!Return value / set value
A Windows executable is available here [http://projects.gctronic.com/epuck2/monitor-wifi_e9cf9f9.zip Monitor WiFi for Windows].
+
|-
 
+
|<code>0x08</code>
==Main microcontroller firmware==
+
|Get all sensors
The robot is initially programmed with a firmware that includes many demos that could be started based on the selector position:
+
|<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span>
* Selector position 0: Aseba
+
see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi] for the content description
* Selector position 1: Shell
+
|-
* Selector position 2: Read proximity sensors
+
|<code>0x09</code>
* Selector position 3: Asercom protocol v2 (BT)
+
|Set all actuators
* Selector positoin 4: Range and bearing extension (receiver)
+
|<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot-bt.jpg <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot-bt.jpg">]</span>
* Selector position 5: Range and bearing extension (transmitter)
+
see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi] for the content description
* Selector position 6: ESP32 UART communication test
+
|-
* Selector position 7: ...
+
|<code>0x0A</code>
* Selector position 8: Asercom protocol v2 (USB)
+
|Set RGB LEDs, values from 0 (off) to 100 (completely on)
* Selector position 9: Asercom protocol (BT)
+
|<code>[LED2_red][LED2_green][LED2_blue][LED4_red][LED4_green][LED4_blue][LED6_red][LED6_green][LED6_blue][LED8_red][LED8_green][LED8_blue]</code>
* Selector position 10: This position is used to work with the gumstix extension.
+
|-
* Selector position 11: Simple obstacle avoidance + some animation
+
|<code>0x0B</code>
* Selector position 12: Hardware test
+
|Get button state: 0 = not pressed, 1 = pressed
* Selector position 13: LEDs reflect orientation of the robot
+
|<code>[STATE]</code>
* Selector position 14: Read magnetometer sensor
+
|-
* Selector position 15: ...
+
|<code>0x0C</code>
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/>
+
|Get all 4 microphones volumes
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_main-processor_23.04.18_3988f7c.elf e-puck2-firmware].
+
|<code>[MIC0_LSB][MIC0_MSB][MIC1_LSB][MIC1_MSB][MIC2_LSB][MIC2_MSB][MIC3_LSB][MIC3_MSB]</code>
===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].
+
|<code>0x0D</code>
===WiFi support===
+
|Get distance from ToF sensor (millimeters)
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 and sensors to the computer and receive commands from the computer (only motors and red LEDs are supported at the moment).<br/>
+
|<code>[DIST_LSB][DIST_MSB]</code>
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/>
+
|<code>0x0E</code>
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi_97d247f.elf e-puck2-firmware_wifi].
+
|Get SD state: 0 = micro sd not connected, 1 = micro sd connected
 
+
|<code>[STATE]</code>
==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==
+
==WiFi==
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">
 
<table>
 
<tr>
 
<td align="center">[1]</td>
 
<td align="center">[2]</td>
 
<td align="center">[3]</td>
 
<td align="center">[4]</td>
 
</tr>
 
<tr>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/dfu1.png <img width=250 src="http://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>[http://projects.gctronic.com/epuck2/wiki_images/dfu3.png <img width=250 src="http://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>
 
</tr>
 
</table>
 
</span><br/>
 
 
 
==Radio module firmware==
 
The firmware support Bluetooth communication.<br/>
 
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 and sensors to the computer and receive commands from the computer (only motors and red LEDs are supported at the moment).<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-d4ff7b4.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''
 
 
 
==WiFi communication protocol==
 
 
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>
 
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>
  
Line 681: Line 224:
 
* 0x00 = reserved
 
* 0x00 = reserved
 
* 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565
 
* 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565
* 0x02 = sensors packet; packet size (without id) = 104 bytes; the format of the returned values are based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol asercom protocol]:
+
* 0x02 = sensors packet; packet size (without id) = 104 bytes; the format of the returned values are based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol] and are compatible with e-puck1.x:
  
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
 
:*Acc: raw axes values, between -1500 and 1500, resolution is +-2g
 
:*Acc: raw axes values, between -1500 and 1500, resolution is +-2g
 
:*Acceleration: acceleration magnitude <img width=70 src="http://projects.gctronic.com/epuck2/wiki_images/3dvector-magnitude.png">, between 0.0 and about 2600.0 (~3.46 g)
 
:*Acceleration: acceleration magnitude <img width=70 src="http://projects.gctronic.com/epuck2/wiki_images/3dvector-magnitude.png">, between 0.0 and about 2600.0 (~3.46 g)
:*Orientation: between 0.0 and 360.0 degrees <table>
+
:*Orientation: between 0.0 and 360.0 degrees <table><tr><td align="center">0.0 deg</td><td align="center">90.0 deg</td><td align="center">180 deg</td><td align="center">270 deg</td></tr><tr><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation0.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation90.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation180.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation270.png"></td></tr></table>
<tr>
 
<td align="center">0.0 deg</td>
 
<td align="center">90.0 deg</td>
 
<td align="center">180 deg</td>
 
<td align="center">270 deg</td>
 
</tr>
 
<tr>
 
<td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation0.png"></td>
 
<td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation90.png"></td>
 
<td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation180.png"></td>
 
<td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation270.png"></td>
 
</tr>
 
</table>
 
  
:*Inclination:
+
:*Inclination: between 0.0 and 90.0 degrees (when tilted in any direction)<table><tr><td align="center">0.0 deg</td><td align="center">90.0 deg</td></tr><tr><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination0.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination90.png"></td></tr></table>
:*Gyro:
+
:*Gyro: raw axes values, between -32768 and 32767, range is +-250dps
:*Magnetometer:
+
:*Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
:*Temp:
+
:*Temp: temperature given in Celsius degrees
:*IR proximity:
+
:*IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
:*IR ambient:
+
:*IR ambient: between 0 (strong light) and 4095 (dark)
:*ToF distance:
+
:*ToF distance: distance given in millimeters
:*Mic volume:
+
:*Mic volume: between 0 and 4095
:*Motors steps:
+
:*Motors steps: 1000 steps per wheel revolution
 
:*Battery:
 
:*Battery:
:*uSD state:
+
:*uSD state: 1 if the micro sd is present and can be read/write, 0 otherwise
:*TV remote data:
+
:*TV remote data: RC5 protocol
:*Selector position:
+
:*Selector position: between 0 and 15
:*Ground proximity:
+
:*Ground proximity: between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white)
:*Ground ambient:
+
:*Ground ambient: between 0 (strong light) and 1023 (dark)
:*Button state:
+
:*Button state: 1 button pressed, 0 button released
 
* 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested
 
* 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested
 
The following IDs are used to send data from the computer to the robot:
 
The following IDs are used to send data from the computer to the robot:
Line 731: Line 261:
 
:** bit2: 0=set motors speed; 1=set motors steps (position)
 
:** bit2: 0=set motors speed; 1=set motors steps (position)
 
:*left and right: when bit2 of <code>settings</code> field is <code>0</code>, then this is the desired motors speed (-1000..1000); when <code>1</code> then this is the value that will be set as motors position (steps)
 
:*left and right: when bit2 of <code>settings</code> field is <code>0</code>, then this is the desired motors speed (-1000..1000); when <code>1</code> then this is the value that will be set as motors position (steps)
:*LEDs: 0=off; 1=on; 2=toggle
+
:*LEDs: 0=off; 1=on
 
:** bit0: 0=LED1 off; 1=LED1 on
 
:** bit0: 0=LED1 off; 1=LED1 on
 
:** bit1: 0=LED3 off; 1=LED3 on
 
:** bit1: 0=LED3 off; 1=LED3 on
Line 769: Line 299:
 
3) read the ID (1 byte) and the QQVGA color image pakcet (38400 bytes)<br/>
 
3) read the ID (1 byte) and the QQVGA color image pakcet (38400 bytes)<br/>
 
4) go to step 3
 
4) go to step 3
 +
 +
=Webots=
 +
TBD
 +
 +
=ROS=
 +
This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth or WiFi to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema:<br/>
 +
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck2-ros-schema.png <img width=450 src="http://www.gctronic.com/doc/images/epuck2-ros-schema-small.png">]</span>
 +
''<font size="2">Click to enlarge</font>''<br/>
 +
 +
First of all you need to install and configure ROS, refer to [http://wiki.ros.org/Distributions http://wiki.ros.org/Distributions] for more informations. <font style="color:red"> This tutorial is based on ROS Kinetic</font>. The same instructions are working with ROS Noetic, beware to use <code>noetic</code> instead of <code>kinetic</code> when installing the packages.
 +
 +
Starting from the work done with the e-puck1 (see [https://www.gctronic.com/doc/index.php?title=E-Puck#ROS E-Puck ROS]), we updated the code in order to support the e-puck2 robot.
 +
 +
==Initial configuration==
 +
The following steps need to be done only once, after installing ROS:
 +
:1. If not already done, create a catkin workspace, refer to [http://wiki.ros.org/catkin/Tutorials/create_a_workspace http://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands: 
 +
<pre>  mkdir -p ~/catkin_ws/src
 +
  cd ~/catkin_ws/src
 +
  catkin_init_workspace
 +
  cd ~/catkin_ws/
 +
  catkin_make
 +
  source devel/setup.bash </pre>
 +
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
 +
:3. Move to <code>~/catkin_ws/src</code> and clone the ROS e-puck2 driver repo:
 +
:* if you are working with Python (only Bluetooth communication supported at the moment): <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>
 +
:* if you are working with cpp:
 +
:** Bluetooth communication: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>
 +
:** WiFi communication: <code>git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp</code>
 +
:4. Install the dependencies:
 +
:* ROS:
 +
:** [http://wiki.ros.org/gmapping gmapping (SLAM)] package: <code>sudo apt-get install ros-kinetic-gmapping</code>
 +
:** [http://wiki.ros.org/rviz_imu_plugin Rviz IMU plugin] package: <code>sudo apt-get install ros-kinetic-rviz-imu-plugin</code>
 +
:* Python:
 +
:** The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies:
 +
:*** install the Python setup tools: <code>sudo apt-get install python-setuptools</code>
 +
:*** install the Python image library: <code>sudo apt-get install python-imaging</code>
 +
:*** install pybluez version 0.22: <code>sudo pip install pybluez==0.22</code>
 +
:**** install pybluez dependencies: <code>sudo apt-get install libbluetooth-dev</code>
 +
:*** install OpenCV: <code>sudo apt-get install python3-opencv</code>
 +
:* cpp:
 +
:** install the library used to communicate with Bluetooth: <code>sudo apt-get install libbluetooth-dev</code>
 +
:** install OpenCV: <code>sudo apt-get install libopencv-dev</code>
 +
:*** if you are working with OpenCV 4, then you need to change the header include from <code>#include <opencv/cv.h></code> to <code>#include <opencv2/opencv.hpp></code>
 +
:5. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
 +
:6. Program the e-puck2 robot with the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware factory firmware] and put the selector in position 3 for Bluetooth communication or in position 15 for WiFi Communication
 +
:7. Program the radio module with the correct firmware:
 +
:* Bluetooth communication: use the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_2 factory firmware]
 +
:* WiFi communication: use the [https://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_firmware WiFi firmware]
 +
 +
==Running the Python ROS node==
 +
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>. <br/>
 +
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
 +
Moreover make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): <code>chmod +x ./src/epuck_driver/scripts/epuck2_driver.py</code>. <br/>
 +
 +
Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
 +
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related MAC address.
 +
 +
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
 +
 +
Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [http://wiki.ros.org/roslaunch roslaunch]).<br/>
 +
Open a terminal and issue the following command: <code>roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'</code>.<br/>
 +
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
 +
 +
If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
 +
 +
The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
 +
 +
The following figures show all the topics published by the e-puck2 driver node (left) and the <code>rviz</code> interface (right): <br/>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_small.png">]</span>
 +
''<font size="2">Click to enlarge</font>''
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz_small.png">]</span>
 +
''<font size="2">Click to enlarge</font>''<br/>
 +
 +
==Running the cpp ROS node==
 +
There is a small difference at the moment between the Bluetooth and WiFi versions of the ROS node: the WiFi ROS node supports also the publication of the magnetometer data.
 +
===Bluetooth===
 +
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>. <br/>
 +
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
 +
 +
Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
 +
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related MAC address.
 +
 +
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
 +
 +
Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [http://wiki.ros.org/roslaunch roslaunch]).<br/>
 +
Open a terminal and issue the following command: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'</code>.<br/>
 +
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
 +
 +
If all is going well the robot will be ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
 +
 +
The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
 +
===WiFi===
 +
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp</code>. <br/>
 +
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
 +
 +
Before actually starting the e-puck2 node you need to connect the e-puck2 robot to your WiFi network, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi Connecting to the WiFi].<br/>
 +
 +
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
 +
 +
Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [http://wiki.ros.org/roslaunch roslaunch]).<br/>
 +
Open a terminal and issue the following command: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20'</code>.<br/>
 +
<tt>192.168.1.20</tt> is the e-puck2 IP address that need to be changed accordingly to your robot.
 +
 +
If all is going well the robot will be ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
 +
 +
The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
 +
 +
The refresh rate of the topics is about 11 Hz when the camera image is enabled (see [http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camon.pdf e-puck2_topics_wifi_refresh_camon.pdf]) and about 50 Hz when the camera image is disabled (see [http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camoff.pdf e-puck2_topics_wifi_refresh_camoff.pdf]). The same graphs can be created using the command <code>rosrun tf view_frames</code>.
 +
 +
The following figure shows all the topics published by the e-puck2 WiFi ROS node. The same graph can be created using the command <code>rqt_graph</code>. <br/>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi.png">]</span>
 +
''<font size="2">Click to enlarge</font>''
 +
 +
==Move the robot==
 +
You have some options to move the robot.<br/>
 +
 +
The first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right.<br/>
 +
 +
The second method to move the robot is using the <code>ros-kinetic-turtlebot-teleop</code> ROS package. If not already done, you can install this package by issueing <code>sudo apt-get install ros-kinetic-turtlebot-teleop</code>.<br/>
 +
There is a lunch file in the e-puck2 ROS driver that configures this package in order to be used with the e-puck2 robot. To start the launch file, issue the following command <code>roslaunch epuck_driver epuck2_teleop.launch</code>, then follow the instructions printed on the terminal to move the robot.<br/>
 +
 +
The third method is by directly publishing on the <code>/mobile_base/cmd_vel</code> topic, for instance by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'</code> the robot will rotate on the spot, instead by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code> the robot will move straight forward.<br/>
 +
Beware that there shouldn't be any other node publishing on the <code>/mobile_base/cmd_vel</code> topic, otherwise your commands will be overwritten.
 +
 +
==Control the RGB LEDs==
 +
The general command to change the RGB LEDs colors is the following:<br/>
 +
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"</code><br/>
 +
The values range is from 0 (off) to 100 (completely on). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the RGB LEDs.<br/>
 +
 +
For instance to set all the RGB LEDs to red, issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"</code><br/>
 +
 +
To turn off all the RGB LEDs issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [0,0,0, 0,0,0, 0,0,0, 0,0,0]}"</code>
 +
 +
==Control the LEDs==
 +
The general command to change the LEDs state is the following:<br/>
 +
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7, body LED, front LED]}"</code><br/>
 +
The values are: 0 (off), 1 (on) and 2 (toggle). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the LEDs.<br/>
 +
 +
For instance to turn on LED1, LED5, body LED and front LED, issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1,0,1,0,1,1]}"</code><br/>
 +
 +
To toggle the state of all the LEDs issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [2,2,2,2,2,2]}"</code>
 +
 +
==Visualize the camera image==
 +
By default the camera is disabled to avoid communication delays. In order to enable it and visualize the image through ROS you need to pass an additional parameter <code>cam_en</code> to the launch script as follows:<br/>
 +
* Python: <code>roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'</code>
 +
* cpp:
 +
** Bluetooth: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'</code>
 +
** WiFi: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20' cam_en:='true'</code>
 +
 +
Then with the Python ROS node you need to open another terminal and issue the command <code>rosrun image_view image_view image:=/camera</code> that will open a window with the e-puck2 camera image.<br/>
 +
With the cpp ROS node the image is visualized directly in the Rviz window (on the right).<br/>
 +
 +
When using the Bluetooth ROS node, by default the image is greyscale and its size is 160x2, but you can change the image parameters in the launch script.<br/>
 +
Instead when using the WiFi node, the image is RGB565 and its size is fixed to 160x120 (you can't change it).
 +
==Multiple robots==
 +
There is a lunch script file designed to run up to 4 robots simultaneously, you can find it in <code>~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck2.launch</code>. Here is an example to run 2 robots:<br/>
 +
<code>roslaunch epuck_driver_cpp multi_epuck2.launch robot_addr0:='192.168.1.21' robot_addr1:='192.168.1.23'</code><br/>
 +
After issueing the command, rviz will be opened showing the values of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm.
 +
 +
==Troubleshooting==
 +
===Robot state publisher===
 +
If you get an error similar to the following when you start a node with roslaunch:
 +
<pre>
 +
ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)
 +
</pre>
 +
Then you need to change the launch file from:
 +
<pre>
 +
<node name="robot_state_publisher" pkg="robot_state_publisher" type="state_publisher" />
 +
</pre>
 +
To:
 +
<pre>
 +
<node name="robot_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
 +
</pre>
 +
This is due to the fact that <code>state_publisher</code> was a deprecated alias for the node named <code>robot_state_publisher</code> (see [https://github.com/ros/robot_state_publisher/pull/87 https://github.com/ros/robot_state_publisher/pull/87]).
 +
 +
=Tracking=
 +
Some experiments are done with the [https://en.wikibooks.org/wiki/SwisTrack SwisTrack software] in order to be able to track the e-puck2 robots through a color marker placed on top of the robots.
 +
 +
The requirements are the following:
 +
* e-puck robots equipped with a color marker attached on top of the robot; beware that there should be a white border of about 1 cm to avoid wrong detection (marker merging). The colors marker were printed with a laser printer.
 +
* USB webcam with a resolution of at least 640x480. In our tests we used the <code>Trust SpotLight Pro</code>.
 +
* Windows OS: the SwisTrack pre-compiled package was built to run in Windows. Moreover the controller example depends on Windows libraries.<br/>''Anyway it's important to notice that SwisTrack is multiplatform and that the controller code can be ported to Linux.
 +
* An arena with uniform light conditions to make the detection more robust.
 +
 +
==Controller example==
 +
In this example we exploit the ''SwisTrack'' blobs detection feature in order to detect the color markers on top of the robots and then track these blob with a ''Nearest Neighbour tracking'' algorithm.<br/>
 +
The ''SwisTrack'' application get an image from the USB camera, then applies some conversions and thresholding before applying the blobs detection and finally tracks these blobs. All the data, like the blob's positions, are published to the network (TCP). <br/>
 +
The controller is a separate application that receives the data from SwisTrack through the network and opens a Bluetooth connection with each robot in order to remote control them. In the example, the informations received are printed in the terminal while moving the robots around (obstacles avoidance).<br/>
 +
The following schema shows the connections schema:<br/>
 +
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/tracking-schema.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/tracking-schema.png">]</span><br/>
 +
 +
 +
Follow these steps to run the example:
 +
* program all the e-puck2 robots with the last factory firmware (see section [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Firmware update]) and put the selector in position 3
 +
* pair the robots with the computer, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth]
 +
* the controller example is based on the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#C.2B.2B_remote_library C++ remote library], so download it
 +
* download the controller example by issueing the following command: <code>git clone https://github.com/e-puck2/e-puck2_tracking_example</code>.<br/> When building the example, make sure that both the library and the example are in the same directory
 +
* download the pre-compiled [http://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip SwisTrack software] and extract it. The ''SwisTrack'' executable can be found in <code>SwisTrackEnvironment/SwisTrack - Release.exe</code>
 +
* prepare the arena: place the USB camera on the roof pointing towards the robots. Download the [http://projects.gctronic.com/epuck2/tracking/e-puck2-tracking-markers.pdf markers] and attach one of them on top of each robot.
 +
* download the [http://projects.gctronic.com/epuck2/tracking/swistrack-conf.zip configuration files package] for ''SwisTrack'' and extract it. Run the ''SwisTrack'' executable and open the configuration file called <code>epuck2.swistrack</code>. All the components to accomplish the tracking of '''2 robots''' should be loaded automatically.<br/> If needed you can tune the various components to improve the blobs detection in your environment or for tracking more robots.
 +
* Run the controller example: at the beginning you must enter the Bluetooth UART port numbers for the 2 robots. Then the robots will be moved slightly in order to identify which robot belong to which blob. Then the controller loop is started sending motion commands to the robots for doing obstacles avoidance and printing the data received from SwisTrack in the terminal.
 +
 +
The following image shows the example running:<br/>
 +
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/tracking-epuck2.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/tracking-epuck2_small.png">]</span><br/>

Revision as of 12:25, 18 November 2020

e-puck2 main wiki

1 Robot configuration

This section explains how to configure the robot based on the communication channel you will use for your developments, thus you need to read only one of the following sections, but it would be better if you spend a bit of time reading them all in order to have a full understanding of the available configurations.

1.1 USB

The main microcontroller is initially programmed with a firmware that support USB communication.

If the main microcontroller isn't programmed with the factory firmware or if you want to be sure to have the last firmware on the robot, you need to program it with the last factory firmware by referring to section main microcontroller firmware update.

The radio module can be programmed with either the Bluetooth or the WiFi firmware, both are compatible with USB communication:

When you want to interact with the robot from the computer you need to place the selector in position 8 to work with USB.

Section PC interface gives step by step instructions on how to connect the robot with the computer via USB.

Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called advanced sercom v2, refer to section Communication protocol: BT and USB for detailed information about this protocol.

1.2 Bluetooth

The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication.

If the main microcontroller and radio module aren't programmed with the factory firmware or if you want to be sure to have the last firmwares on the robot, you need to program them with the last factory firmwares:

When you want to interact with the robot from the computer you need to place the selector in position 3 if you want to work with Bluetooth.

Section Connecting to the Bluetooth gives step by step instructions on how to accomplish your first Bluetooth connection with the robot.

Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called advanced sercom v2, refer to section Communication protocol: BT and USB for detailed information about this protocol.

1.3 WiFi

For working with the WiFi, the main microcontroller must be programmed with the factory firmware and the radio module must be programmed with a dedicated firmware (not the factory one):

Put the selector in position 15.

Section Connecting to the WiFi gives step by step instructions on how to accomplish your first WiFi connection with the robot.

The communication protocol is described in detail in the section Communication protocol: WiFi.

2 Connecting to the Bluetooth

The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer:

  1. Channel 1, GDB: port to connect with GDB if the programmer is in mode 1 or 3 (refer to chapter Configuring the Programmer's settings for more information about these modes)
  2. Channel 2, UART: port to connect to the UART port of the main processor
  3. 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.
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.


Then it will be discoverable and you will be able to pair with it.
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.

2.1 Windows 7

When you pair your computer with the e-puck2, 3 COM ports will be automatically created. To see which COM port corresponds to which channel you need to open the properties of the paired e-puck2 robot from Bluetooth devices. Then the ports and related channels are listed in the Services tab, as shown in the following figure:

2.2 Windows 10

When you pair your computer with the e-puck2, 6 COM ports will be automatically created. The three ports you will use have Outgoing direction and are named e_puck2_xxxxx-GDB, e_puck2_xxxxx-UART, e_puck2_xxxxx-SPI. xxxxx is the ID number of your e-puck2.
To see which COM port corresponds to which channel you need to:

  1. open the Bluetooth devices manager
  2. pair with the robot
  3. click on More Bluetooth options
  4. the ports and related channels are listed in the COM Ports tab, as shown in the following figure:

2.3 Linux

Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command:
sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2
The MAC address is visible from the Bluetooth manager. The parameter 2 indicates the channel, in this case a port for the UART channel is created. If you want to connect to another service you need to change this parameter accordingly (e.g. 1 for GDB and 3 for SPI). Now you can use /dev/rfcomm0 to connect to the robot.

2.4 Mac

When you pair your computer with the e-puck2, 3 COM ports will be automatically created: /dev/cu.e-puck2_xxxxx-GDB, /dev/cu.e-puck2_xxxxx-UART and /dev/cu.e-puck2_xxxxx-SPI. xxxxx is the ID number of your e-puck2.

2.5 Testing the Bluetooth connection

You need to download the PC application provided in section PC interface: available executables.
In the connection textfield you need to enter the UART channel port, for example:

  • Windows 7: COM258
  • Windows 10: e_puck2_xxxxx-UART
  • Linux: /dev/rfcomm0
  • Mac: /dev/cu.e-puck2_xxxxx-UART

and then click Connect.
You should start receiving sensors data and you can send commands to the robot.

Alternatively you can also use a simple terminal program (e.g. realterm in Windows) instead of the PC application, then you can issue manually the commands to receive sensors data or for setting the actuators (once connected, type h + ENTER for a list of availables commands).

2.6 Python examples

Here are some basic Python examples that show how to get data from the robot through Bluetooth using the commands available with the advanced sercom v2:

In all the examples you need to set the correct Bluetooth serial port related to the robot.

2.6.1 Connecting to multiple robots

Here is a simple Python script multi-robot.py that open a connection with 2 robots and exchange data with them using the advanced sercom protocol. This example can be extended to connect to more than 2 robots.

2.7 C++ remote library

A remote control library implemented in C++ is available to control the e-puck2 robot via a Bluetooth connection from the computer.
The remote control library is multiplatform and uses only standard C++ libraries.
You can download the library with the command git clone https://github.com/e-puck2/e-puck2_cpp_remote_library.
A simple example showing how to use the library is also available; you can download it with the command git clone https://github.com/e-puck2/e-puck2_cpp_remote_example.
Before building the example you need to build the library. Then when building the example, make sure that both the library and the example are in the same directory, that is you must end up with the following directory tree:

e-puck2_projects
|_ e-puck2_cpp_remote_library
|_ e-puck2_cpp_remote_example

The complete API reference is available in the following link e-puck2_cpp_remote_library_api_reference.pdf.

3 Connecting to the WiFi

The WiFi channel is used to communicate with robot faster than with Bluetooth. At the moment a QQVGA (160x120) color image is transferred to the computer together with the sensors values at about 10 Hz; of course the robot is also able to receive commands from the computer.
In order to communicate with the robot through WiFi, first you need to configure the network parameters on the robot by connecting directly to it, since the robot is initially configured in access point mode, as explained in the following section. Once the configuration is saved on the robot, it will then connect automatically to the network and you can connect to it.

The LED2 is used to indicate the state of the WiFi connection:

  • red indicates that the robot is in access point mode (waiting for configuration)
  • green indicates that the robot is connected to a network and has received an IP address
  • blue (toggling) indicates that the robot is transferring the image to the computer
  • off when the robot cannot connect to the saved configuration

3.1 Network configuration

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 e-puck2_0XXXX where XXXX is the id of the robot; the password to connect to the access point is e-puck2robot.
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 192.168.1.1. 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 OK 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.

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


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.
Remember that you need to power cycle the robot at least once for the new configuration to be active.

Once the connection is established, the LED2 will be green.

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.


3.2 Finding the IP address

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 Network configuration you're ready to go to the next section.

Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to the port labeled Serial Monitor (see chapter 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:

3.3 Testing the WiFi connection

A dedicated WiFi version of the PC application was developed to communicate with the robot through TCP protocol. You can download the executable from one of the following links:

If you are interested to the source code, you can download it with the command git clone -b wifi --recursive https://github.com/e-puck2/monitor.git

Run the PC application, insert the IP address of the robot in the connection textfield and then click on the Connect button. You should start receiving sensors data and you can send commands to the robot. The LED2 blue will toggle.

3.4 Web server

When the robot is in access point mode you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface.
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 192.168.1.1/monitor.html.

3.5 Python examples

3.5.1 Connecting to multiple robots

A simple Python 3 script was developed as a starting point to open a connection with multiple robots and exchange data with them using the WiFi communication protocol. The demo was tested with 10 robots but can be easily extended to connect to more robots.
You can download the script with the command git clone https://github.com/e-puck2/e-puck2_python_wifi_multi.git. The code was tested to work with Python 3.x.

4 Communication protocol

This section is the hardest part to understand. It outlines all the details about the communication protocols that you'll need to implement in order to communicate with the robot form the computer. So spend a bit of time reading and re-reading this section in order to grasp completely all the details.

4.1 Bluetooth and USB

The communication protocol is based on the advanced sercom protocol, used with the e-puck1.x robot. The advanced sercom v2 includes all the commands available in the advanced sercom protocol and add some additional commands to handle the new features of the e-puck2 robot. In particular here are the new commands:

Command Description Return value / set value
0x08 Get all sensors

see section Communication protocol: WiFi for the content description

0x09 Set all actuators

see section Communication protocol: WiFi for the content description

0x0A Set RGB LEDs, values from 0 (off) to 100 (completely on) [LED2_red][LED2_green][LED2_blue][LED4_red][LED4_green][LED4_blue][LED6_red][LED6_green][LED6_blue][LED8_red][LED8_green][LED8_blue]
0x0B Get button state: 0 = not pressed, 1 = pressed [STATE]
0x0C Get all 4 microphones volumes [MIC0_LSB][MIC0_MSB][MIC1_LSB][MIC1_MSB][MIC2_LSB][MIC2_MSB][MIC3_LSB][MIC3_MSB]
0x0D Get distance from ToF sensor (millimeters) [DIST_LSB][DIST_MSB]
0x0E Get SD state: 0 = micro sd not connected, 1 = micro sd connected [STATE]

4.2 WiFi

The communication is based on TCP; the robot create a TCP server and wait for a connection.

Each packet is identified by an ID (1 byte). The following IDs are used to send data from the robot to the computer:

  • 0x00 = reserved
  • 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565
  • 0x02 = sensors packet; packet size (without id) = 104 bytes; the format of the returned values are based on the advanced sercom protocol and are compatible with e-puck1.x:

  • Acc: raw axes values, between -1500 and 1500, resolution is +-2g
  • Acceleration: acceleration magnitude , between 0.0 and about 2600.0 (~3.46 g)
  • Orientation: between 0.0 and 360.0 degrees
    0.0 deg90.0 deg180 deg270 deg
  • Inclination: between 0.0 and 90.0 degrees (when tilted in any direction)
    0.0 deg90.0 deg
  • Gyro: raw axes values, between -32768 and 32767, range is +-250dps
  • Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
  • Temp: temperature given in Celsius degrees
  • IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
  • IR ambient: between 0 (strong light) and 4095 (dark)
  • ToF distance: distance given in millimeters
  • Mic volume: between 0 and 4095
  • Motors steps: 1000 steps per wheel revolution
  • Battery:
  • uSD state: 1 if the micro sd is present and can be read/write, 0 otherwise
  • TV remote data: RC5 protocol
  • Selector position: between 0 and 15
  • Ground proximity: between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white)
  • Ground ambient: between 0 (strong light) and 1023 (dark)
  • Button state: 1 button pressed, 0 button released
  • 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested

The following IDs are used to send data from the computer to the robot:

  • 0x80 = commands packet; packet size (without id) = 20 bytes:

  • request:
    • bit0: 0=stop image stream; 1=start image stream
    • bit1: 0=stop sensors stream; 1=start sensors stream
  • settings:
    • bit0: 1=calibrate IR proximity sensors
    • bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet)
    • bit2: 0=set motors speed; 1=set motors steps (position)
  • left and right: when bit2 of settings field is 0, then this is the desired motors speed (-1000..1000); when 1 then this is the value that will be set as motors position (steps)
  • LEDs: 0=off; 1=on
    • bit0: 0=LED1 off; 1=LED1 on
    • bit1: 0=LED3 off; 1=LED3 on
    • bit2: 0=LED5 off; 1=LED5 on
    • bit3: 0=LED7 off; 1=LED7 on
    • bit4: 0=body LED off; 1=body LED on
    • bit5: 0=front LED off; 1=front LED on
  • RGB LEDs: for each LED, it is specified in sequence the value of red, green and blue (0...100)
  • sound id: 0x01=MARIO, 0x02=UNDERWOLRD, 0x04=STARWARS, 0x08=4KHz, 0x10=10KHz, 0x20=stop sound

For example to receive the camera image (stream) the following steps need to be followed:
1) connect to the robot through TCP
2) send the command packet:

0x80 0x01 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00

3) read the ID (1 byte) and the QQVGA color image pakcet (38400 bytes)
4) go to step 3

5 Webots

TBD

6 ROS

This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth or WiFi to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema:
Click to enlarge

First of all you need to install and configure ROS, refer to http://wiki.ros.org/Distributions for more informations. This tutorial is based on ROS Kinetic. The same instructions are working with ROS Noetic, beware to use noetic instead of kinetic when installing the packages.

Starting from the work done with the e-puck1 (see E-Puck ROS), we updated the code in order to support the e-puck2 robot.

6.1 Initial configuration

The following steps need to be done only once, after installing ROS:

1. If not already done, create a catkin workspace, refer to http://wiki.ros.org/catkin/Tutorials/create_a_workspace. Basically you need to issue the following commands:
  mkdir -p ~/catkin_ws/src
  cd ~/catkin_ws/src
  catkin_init_workspace
  cd ~/catkin_ws/
  catkin_make
  source devel/setup.bash 
2. You will need to add the line source ~/catkin_ws/devel/setup.bash to your .bashrc in order to automatically have access to the ROS commands when the system is started
3. Move to ~/catkin_ws/src and clone the ROS e-puck2 driver repo:
4. Install the dependencies:
  • ROS:
  • Python:
    • The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies:
      • install the Python setup tools: sudo apt-get install python-setuptools
      • install the Python image library: sudo apt-get install python-imaging
      • install pybluez version 0.22: sudo pip install pybluez==0.22
        • install pybluez dependencies: sudo apt-get install libbluetooth-dev
      • install OpenCV: sudo apt-get install python3-opencv
  • cpp:
    • install the library used to communicate with Bluetooth: sudo apt-get install libbluetooth-dev
    • install OpenCV: sudo apt-get install libopencv-dev
      • if you are working with OpenCV 4, then you need to change the header include from #include <opencv/cv.h> to #include <opencv2/opencv.hpp>
5. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command catkin_make, there shouldn't be errors
6. Program the e-puck2 robot with the factory firmware and put the selector in position 3 for Bluetooth communication or in position 15 for WiFi Communication
7. Program the radio module with the correct firmware:

6.2 Running the Python ROS node

First of all get the last version of the ROS e-puck2 driver from github. Move to ~/catkin_ws/src and issue: git clone -b e-puck2 https://github.com/gctronic/epuck_driver.
Then build the driver by opening a terminal and issueing the command catkin_make from within the catkin workspace directory (e.g. ~/catkin_ws).
Moreover make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): chmod +x ./src/epuck_driver/scripts/epuck2_driver.py.

Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section Connecting to the Bluetooth.
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to System Settings, Bluetooth and select the robot; once selected you'll see in the right side the related MAC address.

First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore.

Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on roslaunch).
Open a terminal and issue the following command: roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'.
B4:E6:2D:EB:9C:4F is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.

If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data and rviz will be opened showing the informations gathered from the topics published by the e-puck2 driver node.

The launch script is configured also to run the gmapping (SLAM) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.

The following figures show all the topics published by the e-puck2 driver node (left) and the rviz interface (right):
Click to enlarge Click to enlarge

6.3 Running the cpp ROS node

There is a small difference at the moment between the Bluetooth and WiFi versions of the ROS node: the WiFi ROS node supports also the publication of the magnetometer data.

6.3.1 Bluetooth

First of all get the last version of the ROS e-puck2 driver from github. Move to ~/catkin_ws/src and issue: git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp.
Then build the driver by opening a terminal and issueing the command catkin_make from within the catkin workspace directory (e.g. ~/catkin_ws).

Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section Connecting to the Bluetooth.
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to System Settings, Bluetooth and select the robot; once selected you'll see in the right side the related MAC address.

First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore.

Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on roslaunch).
Open a terminal and issue the following command: roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'.
B4:E6:2D:EB:9C:4F is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.

If all is going well the robot will be ready to exchange data and rviz will be opened showing the informations gathered from the topics published by the e-puck2 driver node.

The launch script is configured also to run the gmapping (SLAM) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.

6.3.2 WiFi

First of all get the last version of the ROS e-puck2 driver from github. Move to ~/catkin_ws/src and issue: git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp.
Then build the driver by opening a terminal and issueing the command catkin_make from within the catkin workspace directory (e.g. ~/catkin_ws).

Before actually starting the e-puck2 node you need to connect the e-puck2 robot to your WiFi network, refer to section Connecting to the WiFi.

First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore.

Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on roslaunch).
Open a terminal and issue the following command: roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20'.
192.168.1.20 is the e-puck2 IP address that need to be changed accordingly to your robot.

If all is going well the robot will be ready to exchange data and rviz will be opened showing the informations gathered from the topics published by the e-puck2 driver node.

The launch script is configured also to run the gmapping (SLAM) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.

The refresh rate of the topics is about 11 Hz when the camera image is enabled (see e-puck2_topics_wifi_refresh_camon.pdf) and about 50 Hz when the camera image is disabled (see e-puck2_topics_wifi_refresh_camoff.pdf). The same graphs can be created using the command rosrun tf view_frames.

The following figure shows all the topics published by the e-puck2 WiFi ROS node. The same graph can be created using the command rqt_graph.
Click to enlarge

6.4 Move the robot

You have some options to move the robot.

The first one is to use the rviz interface: in the bottom left side of the interface there is a Teleop panel containing an interactive square meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right.

The second method to move the robot is using the ros-kinetic-turtlebot-teleop ROS package. If not already done, you can install this package by issueing sudo apt-get install ros-kinetic-turtlebot-teleop.
There is a lunch file in the e-puck2 ROS driver that configures this package in order to be used with the e-puck2 robot. To start the launch file, issue the following command roslaunch epuck_driver epuck2_teleop.launch, then follow the instructions printed on the terminal to move the robot.

The third method is by directly publishing on the /mobile_base/cmd_vel topic, for instance by issueing the following command rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]' the robot will rotate on the spot, instead by issueing the following command rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]' the robot will move straight forward.
Beware that there shouldn't be any other node publishing on the /mobile_base/cmd_vel topic, otherwise your commands will be overwritten.

6.5 Control the RGB LEDs

The general command to change the RGB LEDs colors is the following:
rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"
The values range is from 0 (off) to 100 (completely on). Have a look at the e-puck2 overview to know the position of the RGB LEDs.

For instance to set all the RGB LEDs to red, issue the following command:
rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"

To turn off all the RGB LEDs issue the following command:
rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [0,0,0, 0,0,0, 0,0,0, 0,0,0]}"

6.6 Control the LEDs

The general command to change the LEDs state is the following:
rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7, body LED, front LED]}"
The values are: 0 (off), 1 (on) and 2 (toggle). Have a look at the e-puck2 overview to know the position of the LEDs.

For instance to turn on LED1, LED5, body LED and front LED, issue the following command:
rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1,0,1,0,1,1]}"

To toggle the state of all the LEDs issue the following command:
rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [2,2,2,2,2,2]}"

6.7 Visualize the camera image

By default the camera is disabled to avoid communication delays. In order to enable it and visualize the image through ROS you need to pass an additional parameter cam_en to the launch script as follows:

  • Python: roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'
  • cpp:
    • Bluetooth: roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'
    • WiFi: roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20' cam_en:='true'

Then with the Python ROS node you need to open another terminal and issue the command rosrun image_view image_view image:=/camera that will open a window with the e-puck2 camera image.
With the cpp ROS node the image is visualized directly in the Rviz window (on the right).

When using the Bluetooth ROS node, by default the image is greyscale and its size is 160x2, but you can change the image parameters in the launch script.
Instead when using the WiFi node, the image is RGB565 and its size is fixed to 160x120 (you can't change it).

6.8 Multiple robots

There is a lunch script file designed to run up to 4 robots simultaneously, you can find it in ~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck2.launch. Here is an example to run 2 robots:
roslaunch epuck_driver_cpp multi_epuck2.launch robot_addr0:='192.168.1.21' robot_addr1:='192.168.1.23'
After issueing the command, rviz will be opened showing the values of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm.

6.9 Troubleshooting

6.9.1 Robot state publisher

If you get an error similar to the following when you start a node with roslaunch:

ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)

Then you need to change the launch file from:

<node name="robot_state_publisher" pkg="robot_state_publisher" type="state_publisher" />

To:

<node name="robot_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />

This is due to the fact that state_publisher was a deprecated alias for the node named robot_state_publisher (see https://github.com/ros/robot_state_publisher/pull/87).

7 Tracking

Some experiments are done with the SwisTrack software in order to be able to track the e-puck2 robots through a color marker placed on top of the robots.

The requirements are the following:

  • e-puck robots equipped with a color marker attached on top of the robot; beware that there should be a white border of about 1 cm to avoid wrong detection (marker merging). The colors marker were printed with a laser printer.
  • USB webcam with a resolution of at least 640x480. In our tests we used the Trust SpotLight Pro.
  • Windows OS: the SwisTrack pre-compiled package was built to run in Windows. Moreover the controller example depends on Windows libraries.
    Anyway it's important to notice that SwisTrack is multiplatform and that the controller code can be ported to Linux.
  • An arena with uniform light conditions to make the detection more robust.

7.1 Controller example

In this example we exploit the SwisTrack blobs detection feature in order to detect the color markers on top of the robots and then track these blob with a Nearest Neighbour tracking algorithm.
The SwisTrack application get an image from the USB camera, then applies some conversions and thresholding before applying the blobs detection and finally tracks these blobs. All the data, like the blob's positions, are published to the network (TCP).
The controller is a separate application that receives the data from SwisTrack through the network and opens a Bluetooth connection with each robot in order to remote control them. In the example, the informations received are printed in the terminal while moving the robots around (obstacles avoidance).
The following schema shows the connections schema:


Follow these steps to run the example:

  • program all the e-puck2 robots with the last factory firmware (see section Firmware update) and put the selector in position 3
  • pair the robots with the computer, refer to section Connecting to the Bluetooth
  • the controller example is based on the C++ remote library, so download it
  • download the controller example by issueing the following command: git clone https://github.com/e-puck2/e-puck2_tracking_example.
    When building the example, make sure that both the library and the example are in the same directory
  • download the pre-compiled SwisTrack software and extract it. The SwisTrack executable can be found in SwisTrackEnvironment/SwisTrack - Release.exe
  • prepare the arena: place the USB camera on the roof pointing towards the robots. Download the markers and attach one of them on top of each robot.
  • download the configuration files package for SwisTrack and extract it. Run the SwisTrack executable and open the configuration file called epuck2.swistrack. All the components to accomplish the tracking of 2 robots should be loaded automatically.
    If needed you can tune the various components to improve the blobs detection in your environment or for tracking more robots.
  • Run the controller example: at the beginning you must enter the Bluetooth UART port numbers for the 2 robots. Then the robots will be moved slightly in order to identify which robot belong to which blob. Then the controller loop is started sending motion commands to the robots for doing obstacles avoidance and printing the data received from SwisTrack in the terminal.

The following image shows the example running: