e-puck2 and Others Extensions: Difference between pages

From GCtronic wiki
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
=Hardware=
=Range and bearing=
==Overview==
<span class="plainlinks">[http://www.gctronic.com/doc/images/randb-1-small.jpg <img height=150 src="http://www.gctronic.com/doc/images/randb-1.jpg">][http://www.gctronic.com/doc/images/randb-2-small.jpg <img height=150 src="http://www.gctronic.com/doc/images/randb-2.jpg">]</span><br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/e-puck2-overview.png <img width=500 src="http://www.gctronic.com/doc/images/e-puck2-overview_small.png">]</span>
The board allows situated agents to communicate locally, obtaining at the same time both the range and the bearing of the emitter without the need of any centralized control or any external reference. Therefore, the board allows the robots to have an embodied, decentralized and scalable communication system. The system relies on infrared communications with frequency modulation and is composed of two interconnected modules for data and power measurement.<br/>
<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/>


==Specifications==
The documentation and hardware files are available in the following links:
The e-puck2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table):
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Schematics.pdf Schematics (pdf)]
{| border="1"
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Assembling.pdf Assembling (pdf)]
|'''Feature'''
* [https://projects.gctronic.com/randb/eRandB_Ed.D_BillOfMaterials.xls Bill of Materials (xls)]
|'''e-puck1.3'''
* [https://projects.gctronic.com/randb/eRandB_Ed.D_PCB.pdf PCB (pdf)]
|'''e-puck2'''
* [https://projects.gctronic.com/randb/eRandB_Ed.D_HardwareSourceFiles.zip Hardware source files(zip)]
|'''Compatibility'''
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Fabrication.zip Fabrication: Gerber, pick and place, ... (zip)]
|'''Additional'''
* [https://projects.gctronic.com/randb/eRandB_manual.pdf e-RandB manual (pdf)]
|-  
* [https://projects.gctronic.com/randb/eRandB_firmware.zip e-RandB firmware (zip)]
|Size, weight
* [https://projects.gctronic.com/randb/eRandB_software.tgz e-puck software and examples (tgz)]
|70 mm diameter, 55 mm height, 150 g
 
|Same form factor: 70 mm diameter, 45 mm, 130 g
You can find more information about this board in the following links: [http://www.e-puck.org/index.php?option=com_content&view=article&id=35&Itemid=23 http://www.e-puck.org/index.php?option=com_content&view=article&id=35&Itemid=23].
|style="text-align:center;" | <img width=40 src="http://www.gctronic.com/doc/images/ok.png">
 
|No e-jumper required
The following table lists the I2C the registers map:
<blockquote>
{| border="1" cellpadding="10" cellspacing="0"
!Address !!Read !!Write
|-
|-
|Battery, autonomy
|0 || 1 if data available, 0 otherwise || -
|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
|1 || data MSB || -
|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
|2 || data LSB || -
|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
|3 || bearing MSB || -
|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
|4 || bearing LSB: <code>double((MSB<<8)+LSB)*0.0001</code> to get angle in degrees|| -
|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
|5 || range MSB || -
|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
|6 || range LSB || -
|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
|7 || max peak (adc reading) MSB || -
|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
|8 || max peak (adc reading) LSB || -
|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
|9 || sensor that received the data (between 0..11) || -
|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
|12 || - || Set transmission power (communication range): between 0 (max range) and 255 (min range)
|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
|13 || - || data LSB (prepare)
|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
|14 || - || data MSB (send <code>(MSB<<8)+LSB</code>)
|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
|16 || - || 0 store light conditions (calibration)
|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
|17 || - || 1=onboard calculation, 0=host calculation
|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
|}
|}
</blockquote>


This is the overall communication schema:<br/>
==Firmware source code==
<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/>
 
=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===
#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.
#Extract the downloaded file to the location you want (can take time).
#You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png">]</span><br/>
:''Eclipse_e-puck2 folder obtained after extraction''
 
Note : The icon of the Eclipse_e-puck2 executable will appear after the first launch of the program.
 
'''Important things to avoid :'''
:1. You cannot create a Link to the Eclipse_e-puck2 executable because otherwise the program will think its location is where the Link is and it will not find the resource located in the Eclipse_e-puck2 folder.
:2. The path to the Eclipse_e-puck2 folder must contain zero space.
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
:3. The file’s structure in the Eclipse_e-puck2 folder must remain the same. It means no file inside this folder must be moved to another place.
 
===Serial Port===
In order to let Eclipse (or any program ran by you) to access the serial ports, a little configuration is needed.
 
Type the following command in a terminal session. Once done, you need to log off to let the change take effect.
 
<pre>sudo adduser $USER dialout</pre>
 
==Installation for Mac==
===Command Line Tools ===
To compile on Mac with Eclipse_e-puck2, it is necessary to have the Command Line Tools installed. It is a bundle of many commonly used tools.<br>
You can install it by typing the following command in a terminal window. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.
<pre>xcode-select --install</pre>
 
===Java 8===
This section can be ignored if Java is already installed on your computer.<br>
To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac.
<pre>/usr/libexec/java_home -V</pre>
You need to have <code>Java SE 8</code> listed to be able to run Eclipse_e-puck2.
 
:1. Go to the [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java download page] and download the <code>Mac OS X Java 8 SE Development Kit</code>. It is the .dmg file without the Demos and Samples.
::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
:2. Open the .dmg file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png">]</span><br/>
:''Java download page''
 
===Eclipse_e-puck2===
:1. Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_11_apr_2018.dmg Eclipse_e-puck2 package for Mac].
:2. Open the .dmg file downloaded and DragAndDrop the Eclipse_e-puck2.app into the Applications folder
::Note : You can place the Eclipse_e-puck2.app anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in Applications.
:3. You can create an Alias to Eclipse_e-puck2.app and place it anywhere if you want.
 
===First launch and Gatekeeper===
It’s very likely that Gatekeeper (one of the protections of Mac OS) will prevent you to launch Eclipse_e-puck2.app because it isn’t signed from a known developer.<br>
If you can’t run the program because of a warning of the system, press <code>OK</code> and try to launch it by right clicking on it and choosing <code>open</code> in the contextual menu (may be slow to open the first time).<br>
If <code>Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.</code> or if <code>"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.</code> appears after executing the app the first time, it is needed to disable temporarily Gatekeeper.
 
To do so :
 
:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
 
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png">]</span><br/>
::''Security settings of Mac OS''
 
::If you are on Mac OS Sierra or greater (greater or equal to Mac OS 10.12), you must type the following command on the terminal to make the option above appear.
::<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.
 
'''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 :
 
#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.
#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==
===Project template===
[https://github.com/e-puck2/e-puck2_main-processor.git e-puck2_main-processor] is a demo project containing all the libraries written for the e-puck2. <br>
It shows how to use them and can be interfaced with [[#PC interface | e-puck2 monitor]].<br>
But this 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>
 
Then all you need to do is to edit the makefile to set the name of your project, the path to the e-puck2_main-processor folder, the .c files to include and the folder(s) to the .h files to include.<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]]).
#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.
#Compile the project and if it succeeded, go to '''Project->C/C++ Index->Rebuild''' to rebuild the index. (We need to have compiled at least one time in order to let Eclipse find all the paths to the files used.)
 
You should now be able to use the project with Eclipse.
 
==Flashing the main microcontroller==
In order to update the firmware of the main microcontroller (STM32F407) you can either use Eclipse (as explained here...) 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/>
 
If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry.
 
==Flashing the WiFi 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. This script was modified to work with the e-puck2 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 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 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
 
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<br>
'''To make it visible, it is necessary to hold the USER button (also labeled "esp32" on the electronic board) while turning on the robot with the ON/OFF button.'''<br>
Then it will be discoverable and you will be able to pair with it.<br>
Note that a prompt could ask you to confirm that the number written on the screen is the same on the e-puck. just ignore this and accept. Otherwise if you are asked for a pin insert 0000.
 
===Windows 7===
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/>
<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===
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:
# open the Bluetooth devices manager
# pair with the robot
# click on <code>More Bluetooth options</code>
# the ports and related channels are listed in the <code>COM Ports</code> tab, as shown in the following figure:<br/>
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png <img height=300 src="http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png">]</span>
 
===Linux===
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/>
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===
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==
At the moment the WiFi channel is used to transfer the image to the computer. A QQVGA color image is transfered.<br/>
A dedicated configuration is needed to use the WiFi:
# [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi.elf main microcontroller 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
# [http://projects.gctronic.com/epuck2/esp32-firmware-wifi.zip WiFi module firmware] (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Flashing_the_WiFi_module Flashing the WiFi module] to update the firmware)
# PC application: [http://projects.gctronic.com/epuck2/esp32-wifi-pc.zip Windows executable]
 
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 AP SSID will be <code>e-puck2_0XXXX</code> where <code>XXXX</code> is the id of the robot; no password needed to connect to the AP.<br/>
Then from the device that is connected to the robot (e.g. a phone), open a browser and insert the address <code>192.168.1.1</code>. In this page will be visualized the available networks that we can connect to as shown in the following figure. Select one from the list.<br/>
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png">]</span><br/>
 
 
The LED2 is used to indicate the state of the WiFi connection.
 
==Configuring the PATH variable==
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.
 
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.


Setting the PATH variable for Windows :
<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.
==e-puck 1==
A simple [https://projects.gctronic.com/randb/test-eRandB.zip MPLAB project] was created to let start using these modules. With the selector it's possible to choose whether the robot is an emitter (selector in position 0) or a receiver (selector in position 1). The receiver will send the information (data, bearing, distance, sensor) through Bluetooth.


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.
==e-puck 2==
The e-puck2 standard firmware contains a demo example to use the range and bearing extension. When the selector is in position 4 then the robot is the receiver, when in position 5 then the robot is the transmitter. The receiver will print (you need to connect the USB cable and open the USB serial port) the data received, the bearing, the distance and the sensor id; while the transmitter will send continously <code>0xAAFF</code>.<br/>
You can download the pre-built firmware from [https://projects.gctronic.com/epuck2/e-puck2_main-processor_randb.elf e-puck2_main-processor_randb.elf]; the source code is available form the repo [https://github.com/e-puck2/e-puck2_main-processor https://github.com/e-puck2/e-puck2_main-processor].<br/>
Beware that the only communication channel available between the robot and the range and bearing extension is the I2C bus, the UART channel is not available with e-puck 2.


=Software=
=Ground sensors=
==PC interface==
<span class="plainlinks">[http://www.gctronic.com/doc/images/E-puck-groundsensors.jpg <img width=200 src="http://www.gctronic.com/doc/images/E-puck-groundsensors.jpg">]</span>
<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.
The factory firmware of both the e-puck1 and e-puck2 supports the ground sensors extension: for e-puck1 refer to the section [https://www.gctronic.com/doc/index.php?title=E-Puck#Standard_firmware Standard firmware], for e-puck2 refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware Factory firmware].


==Standard firmware==
Once the robot is programmed with its factory firmware, you can get the values from the ground sensors through Bluetooth by putting the selector in position 3 and issueing the command <code>m</code> that will return 5 values, the first 3 values are related to the ground sensors (left, center, right), the last 2 values are related to the cliff extension (if available).<br/>
The robot is initially programmed with a firmware that includes many demos that could be started based on the selector position:
For more information about the Bluetooth connection refer to section [https://www.gctronic.com/doc/index.php?title=E-Puck#Getting_started Getting started] (e-puck1) or [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth] (e-puck2).<br/>
* Selector position 0: Aseba
For more information about the Bluetooth protocol refer to section [https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol Advanced sercom protocol].
* Selector position 1: Shell
* Selector position 2: Read proximity sensors
* Selector position 3: Asercom protocol v2 (BT)
* Selector positoin 4: Read IMU raw sensors values
* Selector position 5: Distance sensor reading
* Selector position 6: ESP32 UART communication test
* Selector position 7: ...
* Selector position 8: Asercom protocol v2 (USB)
* Selector position 9: Asercom protocol (BT)
* Selector position 10: This position is used to work with the gumstix extension.  
* Selector position 11: Simple obstacle avoidance + some animation
* Selector position 12: Hardware test
* Selector position 13: LEDs reflect orientation of the robot
* Selector position 14: ...
* Selector position 15: ...
The full code is available in the git repo [https://github.com/e-puck2/e-puck2_main-processor https://github.com/e-puck2/e-puck2_main-processor].<br/>
The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_main-processor_16.02.18_13fa922.elf e-puck2 firmware].


==Library==
If you couple the e-puck extension for Gumstix Overo with the ground sensor refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Ground_sensor http://www.gctronic.com/doc/index.php/Overo_Extension#Ground_sensor] to have an example on how to read the sensor values.
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.zip].<br/>
The latest version can be downloaded with the command: <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code>


=Advanced usage=
You can find more information about the ground sensors extension module in the following link [http://www.e-puck.org/index.php?option=com_content&view=article&id=17&Itemid=18 http://www.e-puck.org/index.php?option=com_content&view=article&id=17&Itemid=18].<br/>
==Flashing the programmer==
==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>
==Assembly for e-puck2==
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 :
<span class="plainlinks"><table><tr><td align="center">[1]</td><td align="center">[2]</td><td align="center">[3.1]</td><td align="center">[3.2]</td><td align="center">[3.3]</td><td align="center">[3.4]</td></tr><tr><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-2_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.2.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.3.jpeg <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.3_small.jpeg">][https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.4.jpeg <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.4_small.jpeg">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.5.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.5.png">]</td></tr><tr><td align="center">[4]</td><td align="center">[5.1]</td><td align="center">[5.2]</td><td align="center">[5.3]</td><td align="center">[5.4]</td><td align="center">[6]</td></tr><tr><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-4.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-4_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.2_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.3.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.3_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.4.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.4_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-6.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-6_small.png">]</td></tr></table></span>
<pre>
# Unscrew the 3 spacers and remove the battery.
arm-none-eabi-gdb
# Remove the top side from the case body gently.
target extended-remote your_gdb_com_port
# Detach the plastic camera adapter from the camera with the help of pliers; be careful to not stress the camera flex cable. Then you need to cut off the two protruding pieces (see 3.2) on the back of the plastic adapter; for this operation you can use nippers (see 3.3). Take the adapter (now is flat on the back as shown in 3.4) and insert it as before.
</pre>
# Plug the ground module into its connector on the e-puck2; make the cable pass through the battery contact.
# First push the ground module within its slot in the body case, then slide in also the top side of the robot paying attention to the motors wires position: the back battery contact must remain between the body and motors wires and make sure the wires aren't stuck in the springs. Both the ground cable and camera flex cable must bend forming an "S" shape.
# Push the top all way down, then remount the spacers and plug in the battery. You're done.


Once connected to the programmer with GDB, you can type
=Cliff sensor=
<pre>monitor help</pre> or <pre>mon help</pre> to print the available commands of the programmer.
The cliff module extends the capability of the groundsensor with two additional sensors placed in front of the wheels. One possible application is that the e-puck can now detect the end of a table and react accordingly. Moreover this module can be coupled with the automatic charger for the e-puck, that could let the robot autonomously charge itself when needed. The two spring contacts adapt only to the cliff module.


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>
==Assembly==
mode 1 = the serial monitor is connected to the UART port of the main processor<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.1]</td><td align="center">[4.2]</td></tr><tr><td>[http://www.gctronic.com/doc/images/cliff-mounting-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-2-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-3.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-3-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-4-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-4-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-4-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-4-2-small.jpg">]</td></tr><tr><td align="center">[5.1]</td><td align="center">[5.2]</td><td align="center">[6]</td><td align="center">[7]</td><td align="center">[8]</td></tr><tr><td>[http://www.gctronic.com/doc/images/cliff-mounting-5-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-5-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-5-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-5-2-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-6.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-6-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-7.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-7-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-8.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-8-small.jpg">]</td></tr></table></span>
mode 2 = the serial monitor is connected to the UART of the ESP32<br>
# Unscrew the 3 screws, unmount the e-jumper (top piece where there is the speaker) and unscrew the 3 spacers
mode 3 = the serial monitor works as a Aseba CAN to USB translator<br>
# Remove the pcb from the case body gently
# Detach the two parts, cliff and ground pcb
# Plug the ground module into its connector on the e-puck
# Attach the cliff module to the ground module being careful to leave the battery contact in the middle
# Push the ground module within its slot in the body case, the cliff module will remain external
# Once both the modules are aligned, push them down
# The modules will remain really close to the case bottom; once the modules are fitted remount the spacers, the e-jumper and the screws


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.
==Electrical schema==
The circuit diagram of the e-puck cliff extension is available to the community on the following link [https://projects.gctronic.com/cliff-sensor/CliffSensorV1.0.pdf electrical schema].  


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.
==Software==
===e-puck firmware===
Refers to the section [http://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware E-Puck Standard firmware] for the firmware that need to be uploaded to the robot.
Essentially the standard ''asercom'' demo (selector 3) released with the e-puck robot is extended in order to request and visualize 5 sensors values instead of 3 when issueing the ''m'' command; the sequence is: ground left, ground center, ground right, cliff right, cliff left. In order to enable the cliff sensors you need to ''define CLIFF_SENSORS'' in the ''asercom.c'' file in order to build the code parts related to this module.


By being connected with GDB, you can also use the standard GDB command to program and debug the main processor of the e-puck2.
===e-puck demos===
To demonstrate the capabilities of the cliff sensors module here is an MPLAB project [https://projects.gctronic.com/cliff-sensor/Demo-cliff-autocharge.zip Demo-cliff-autocharge.zip] that contains two demos:
* selector 0: in this demo the robot is eventually piloted to the charger station autonomously after moving around for some time aovoiding obstacles; the demo is shown in the [http://www.gctronic.com/doc/index.php/Others_Extensions#Videos video section].<br/>
* selector 1: this is a cliff avoidance demo in which the robot is moved forward until it detects the end of the table and tries to avoid it moving back and rotating; the demo is shown in the [http://www.gctronic.com/doc/index.php/Others_Extensions#Videos video section].


==Using the DFU==
===Extension firmware===
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 ground sensor fimrware developed at EPFL (can be downloaded at the [http://www.e-puck.org http://www.e-puck.org] site from [http://www.e-puck.org/index.php?option=com_phocadownload&view=category&id=9:ground-sensors&Itemid=38 this page]) was extended to interact with the additional two sensors. The source code can be downloaded from [https://projects.gctronic.com/cliff-sensor/pic18_floor_sensor_c18-cliff.zip cliff-firmware]; it is an MPLAB project and the MPLAB C Compiler for PIC18 MCUs is needed to build the project.<br/>
The robot will appear as "STM32 BOOTLOADER" in the USB devices.
The communication between the e-puck and the module is handled through I2C (address 0xC0) and the following registers are defined:
* 0x00: reflected light, left IR sensor - high byte
* 0x01: reflected light, left IR sensor - low byte
* 0x02: reflected light, center IR sensor - high byte
* 0x03: reflected light, center IR sensor - low byte
* 0x04: reflected light, right IR sensor - high byte
* 0x05: reflected light, right IR sensor - low byte
* 0x06: ambient light, left IR sensor - high byte
* 0x07: ambient light, left IR sensor - low byte
* 0x08: ambient light, center IR sensor - high byte
* 0x09: ambient light, center IR sensor - low byte
* 0x0A: ambient light, right IR sensor - high byte
* 0x0B: ambient light, right IR sensor - low byte
* 0x0C: software revision number
* 0x0D: reflected light, right cliff sensor - high byte
* 0x0E: reflected light, right cliff sensor - low byte
* 0x0F: reflected light, left cliff sensor - high byte
* 0x10: reflected light, left cliff sensor - low byte
* 0x11: ambient light, right cliff sensor - high byte
* 0x12: ambient light, right cliff sensor - low byte
* 0x13: ambient light, left cliff sensor - high byte
* 0x14: ambient light, left cliff sensor - low byte


Once in DFU, you can program it with [http://dfu-util.sourceforge.net dfu-util]  using the following command :
===e-puck2 demos===
<pre>dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin</pre>
The same demo developed for the e-puck1 that let the robot autonomously reach the charging station and charge itself is available also for the e-puck2. You can find the source code in the following repository [https://github.com/e-puck2/e-puck2_cliff_autocharge https://github.com/e-puck2/e-puck2_cliff_autocharge].


See the [http://dfu-util.sourceforge.net/dfu-util.1.html manual page] of dfu-util for further information on how to use it.
==Images==
Robot equipped with the cliff sensor: <br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff+charger.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff+charger.jpg">]</span> <br/>


Note : For windows, it is needed to install a libusbK driver for the DFU device. <br>
The robot can be easily moved to the charging station as shown in the following figure: <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>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff-charging.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff-charging.jpg">]</span> <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 turning ON the robot.<br>
The following figure shows the two additional sensors (near the wheels) mounted on the cliff module and the three frontal sensors of the ground module: <br/>
It is used to update the firmware of the programmer.<br>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff-zoom.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff-zoom.jpg">]</span> <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/>
==Videos==
::''Location of the pin holes to put the programmer into DFU''
{{#ev:youtube|7iFmLBng3qg}}
{{#ev:youtube|NYOcb1QoUTM}}

Revision as of 09:00, 17 December 2021

Range and bearing


The board allows situated agents to communicate locally, obtaining at the same time both the range and the bearing of the emitter without the need of any centralized control or any external reference. Therefore, the board allows the robots to have an embodied, decentralized and scalable communication system. The system relies on infrared communications with frequency modulation and is composed of two interconnected modules for data and power measurement.

The documentation and hardware files are available in the following links:

You can find more information about this board in the following links: http://www.e-puck.org/index.php?option=com_content&view=article&id=35&Itemid=23.

The following table lists the I2C the registers map:

Address Read Write
0 1 if data available, 0 otherwise -
1 data MSB -
2 data LSB -
3 bearing MSB -
4 bearing LSB: double((MSB<<8)+LSB)*0.0001 to get angle in degrees -
5 range MSB -
6 range LSB -
7 max peak (adc reading) MSB -
8 max peak (adc reading) LSB -
9 sensor that received the data (between 0..11) -
12 - Set transmission power (communication range): between 0 (max range) and 255 (min range)
13 - data LSB (prepare)
14 - data MSB (send (MSB<<8)+LSB)
16 - 0 store light conditions (calibration)
17 - 1=onboard calculation, 0=host calculation

Firmware source code

e-puck 1

A simple MPLAB project was created to let start using these modules. With the selector it's possible to choose whether the robot is an emitter (selector in position 0) or a receiver (selector in position 1). The receiver will send the information (data, bearing, distance, sensor) through Bluetooth.

e-puck 2

The e-puck2 standard firmware contains a demo example to use the range and bearing extension. When the selector is in position 4 then the robot is the receiver, when in position 5 then the robot is the transmitter. The receiver will print (you need to connect the USB cable and open the USB serial port) the data received, the bearing, the distance and the sensor id; while the transmitter will send continously 0xAAFF.
You can download the pre-built firmware from e-puck2_main-processor_randb.elf; the source code is available form the repo https://github.com/e-puck2/e-puck2_main-processor.
Beware that the only communication channel available between the robot and the range and bearing extension is the I2C bus, the UART channel is not available with e-puck 2.

Ground sensors

The factory firmware of both the e-puck1 and e-puck2 supports the ground sensors extension: for e-puck1 refer to the section Standard firmware, for e-puck2 refer to section Factory firmware.

Once the robot is programmed with its factory firmware, you can get the values from the ground sensors through Bluetooth by putting the selector in position 3 and issueing the command m that will return 5 values, the first 3 values are related to the ground sensors (left, center, right), the last 2 values are related to the cliff extension (if available).
For more information about the Bluetooth connection refer to section Getting started (e-puck1) or Connecting to the Bluetooth (e-puck2).
For more information about the Bluetooth protocol refer to section Advanced sercom protocol.

If you couple the e-puck extension for Gumstix Overo with the ground sensor refer to the section http://www.gctronic.com/doc/index.php/Overo_Extension#Ground_sensor to have an example on how to read the sensor values.

You can find more information about the ground sensors extension module in the following link http://www.e-puck.org/index.php?option=com_content&view=article&id=17&Itemid=18.

Assembly for e-puck2

[1][2][3.1][3.2][3.3][3.4]
[4][5.1][5.2][5.3][5.4][6]
  1. Unscrew the 3 spacers and remove the battery.
  2. Remove the top side from the case body gently.
  3. Detach the plastic camera adapter from the camera with the help of pliers; be careful to not stress the camera flex cable. Then you need to cut off the two protruding pieces (see 3.2) on the back of the plastic adapter; for this operation you can use nippers (see 3.3). Take the adapter (now is flat on the back as shown in 3.4) and insert it as before.
  4. Plug the ground module into its connector on the e-puck2; make the cable pass through the battery contact.
  5. First push the ground module within its slot in the body case, then slide in also the top side of the robot paying attention to the motors wires position: the back battery contact must remain between the body and motors wires and make sure the wires aren't stuck in the springs. Both the ground cable and camera flex cable must bend forming an "S" shape.
  6. Push the top all way down, then remount the spacers and plug in the battery. You're done.

Cliff sensor

The cliff module extends the capability of the groundsensor with two additional sensors placed in front of the wheels. One possible application is that the e-puck can now detect the end of a table and react accordingly. Moreover this module can be coupled with the automatic charger for the e-puck, that could let the robot autonomously charge itself when needed. The two spring contacts adapt only to the cliff module.

Assembly

[1][2][3][4.1][4.2]
[5.1][5.2][6][7][8]
  1. Unscrew the 3 screws, unmount the e-jumper (top piece where there is the speaker) and unscrew the 3 spacers
  2. Remove the pcb from the case body gently
  3. Detach the two parts, cliff and ground pcb
  4. Plug the ground module into its connector on the e-puck
  5. Attach the cliff module to the ground module being careful to leave the battery contact in the middle
  6. Push the ground module within its slot in the body case, the cliff module will remain external
  7. Once both the modules are aligned, push them down
  8. The modules will remain really close to the case bottom; once the modules are fitted remount the spacers, the e-jumper and the screws

Electrical schema

The circuit diagram of the e-puck cliff extension is available to the community on the following link electrical schema.

Software

e-puck firmware

Refers to the section E-Puck Standard firmware for the firmware that need to be uploaded to the robot. Essentially the standard asercom demo (selector 3) released with the e-puck robot is extended in order to request and visualize 5 sensors values instead of 3 when issueing the m command; the sequence is: ground left, ground center, ground right, cliff right, cliff left. In order to enable the cliff sensors you need to define CLIFF_SENSORS in the asercom.c file in order to build the code parts related to this module.

e-puck demos

To demonstrate the capabilities of the cliff sensors module here is an MPLAB project Demo-cliff-autocharge.zip that contains two demos:

  • selector 0: in this demo the robot is eventually piloted to the charger station autonomously after moving around for some time aovoiding obstacles; the demo is shown in the video section.
  • selector 1: this is a cliff avoidance demo in which the robot is moved forward until it detects the end of the table and tries to avoid it moving back and rotating; the demo is shown in the video section.

Extension firmware

The ground sensor fimrware developed at EPFL (can be downloaded at the http://www.e-puck.org site from this page) was extended to interact with the additional two sensors. The source code can be downloaded from cliff-firmware; it is an MPLAB project and the MPLAB C Compiler for PIC18 MCUs is needed to build the project.
The communication between the e-puck and the module is handled through I2C (address 0xC0) and the following registers are defined:

  • 0x00: reflected light, left IR sensor - high byte
  • 0x01: reflected light, left IR sensor - low byte
  • 0x02: reflected light, center IR sensor - high byte
  • 0x03: reflected light, center IR sensor - low byte
  • 0x04: reflected light, right IR sensor - high byte
  • 0x05: reflected light, right IR sensor - low byte
  • 0x06: ambient light, left IR sensor - high byte
  • 0x07: ambient light, left IR sensor - low byte
  • 0x08: ambient light, center IR sensor - high byte
  • 0x09: ambient light, center IR sensor - low byte
  • 0x0A: ambient light, right IR sensor - high byte
  • 0x0B: ambient light, right IR sensor - low byte
  • 0x0C: software revision number
  • 0x0D: reflected light, right cliff sensor - high byte
  • 0x0E: reflected light, right cliff sensor - low byte
  • 0x0F: reflected light, left cliff sensor - high byte
  • 0x10: reflected light, left cliff sensor - low byte
  • 0x11: ambient light, right cliff sensor - high byte
  • 0x12: ambient light, right cliff sensor - low byte
  • 0x13: ambient light, left cliff sensor - high byte
  • 0x14: ambient light, left cliff sensor - low byte

e-puck2 demos

The same demo developed for the e-puck1 that let the robot autonomously reach the charging station and charge itself is available also for the e-puck2. You can find the source code in the following repository https://github.com/e-puck2/e-puck2_cliff_autocharge.

Images

Robot equipped with the cliff sensor:

The robot can be easily moved to the charging station as shown in the following figure:

The following figure shows the two additional sensors (near the wheels) mounted on the cliff module and the three frontal sensors of the ground module:

Videos

Load video
YouTube
Load video
YouTube
Retrieved from "http://www.gctronic.com/doc/index.php?title=e-puck2&oldid=2183"