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

From GCtronic wiki
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
=Installation of the e-puck2 environment=
<code>Eclipse_e-puck2</code> is a distribution of Eclipse IDE for C/C++ Developers specially modified to edit and compile e-puck2's projects out of the box. It doesn't require to be installed and everything needed is located in the package given. The only dependency needed to be able to run Eclipse is '''Java'''.


==Installation for Windows==
=Robot configuration=
===Java 8 32bits===
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.
This section can be ignored if Java version >= 8 32bits is already installed on your computer.<br>
==Bluetooth and USB==
To verify you already installed Java, you can open <code>Programs and Features</code> from the <code>control panel</code> and search for a <code>Java 8 Update xxx</code> install. If this entry isn't present, then you need to install it:
The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth and USB communication.<br/>


#Go to the [https://www.java.com/en/download/manual.jsp Java download page] and download the <code>Windows offline</code> pacakge. This is the 32bits version of Java.
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:
#Run the downloaded installer and follow its instructions to proceed with the installation of Java 32bits.
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
#Close the internet browser if it opened at the end of the installation.
* 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_windows.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_windows.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, or in position 8 if you want to work with USB. <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/>
#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 <code>Eclipse_e-puck2.exe</code> 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/>
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/>
:''Eclipse_e-puck2 folder obtained after extraction''


'''Important things to avoid :'''
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 communication channels use the same protocol called <code>advanced sercom v2</code>, 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/>
:1. The path to the <code>Eclipse_e-puck2</code> 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 <code>Eclipse_e-puck2</code> folder into <code>Program Files (x86)</code>. Otherwise the compilation when using Eclipse will not work.
:3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.


===Configuring the PATH variable===
==WiFi==
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
For working with the WiFi, the main microcontroller and radio module must be programmed with dedicated firmwares (not the standard ones):
* [http://projects.gctronic.com/epuck2/e-puck2_main-processor_wifi_afaa618.elf main microcontroller wifi firmware], for information on how to update the firmware 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-7bf44de.zip radio module wifi firmware], 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/>


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
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/>


<code>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</code>
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/>


What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
=Connecting to the Bluetooth=


If you want to set the <code>PATH</code> variable permanently, then go to <code>Control panel</code> => <code>System</code> => <code>Advanced system settings</code> => <code>Environment variables</code>. A list of variables defined for the user is shown, double click on the <code>PATH</code> variable (from the user variables list) and add at the end <code>;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin</code>, then click <code>OK</code> three times.
The standard 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)
# 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)


Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
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>
::<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>
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.


==Installation for Linux==
==Windows 7==
===Java 8===
When you pair your computer with the e-puck2, 3 COM ports will be automatically created.
This section can be ignored if Java is already installed on your computer.<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/>
To verify whether it is installed or not you can type the following command into a terminal window: <code>update-java-alternatives -l</code>. If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
<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>
You need to have <code>Java 1.8.xxxx</code> listed to be able to run <code>Eclipse_e-puck2</code>.


Type the following commands in a terminal session to install Java SDK:
==Windows 10==
<pre>sudo add-apt-repository ppa:openjdk-r/ppa
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/>
sudo apt-get update
To see which COM port corresponds to which channel you need to:
sudo apt-get install openjdk-8-jre </pre>
# 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>


===Eclipse_e-puck2===
==Linux==
#Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <br/>
#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 <code>i686</code> (32bit) or <code>x86_64</code> (64 bit). 
<code>sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2</code><br/>
#Extract the downloaded file to the location you want (can take time): <code>tar -zxvf package_name.tar.gz</code>
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.
#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/>
==Mac==
:''Eclipse_e-puck2 folder obtained after extraction''
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.


Note : The icon of the <code>Eclipse_e-puck2</code> executable will appear after the first launch of the program.
==Testing the Bluetooth connection==
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/>
In the connection textfield you need to enter the UART channel port, for example:
* Windows 7: <code>COM258</code>
* Windows 10: <code>e_puck2_xxxxx-UART</code>
* 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/>


'''Important things to avoid :'''
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).
:1. You cannot create a Link to the <code>Eclipse_e-puck2</code> executable because otherwise the program will think its location is where the Link is and it will not find the resources located in the <code>Eclipse_e-puck2</code> folder.
:2. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.  
::Example :
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
:3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.


===Configuring the PATH variable===
=Connecting to the WiFi=
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
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 12 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.


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
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
::<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/>


<code>export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
==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.


What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
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''; <b>take note of the address since it will be needed later</b>.<br/>


If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.profile</code> file by issuing the command:<br>  
<span class="plainlinks">
<code>echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile</code><br>
<table>
Close and reopen the terminal before using your newly set environment variable.
<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/esp32-wifi-setup1.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png">]</td>
</tr>
</table>
</span><br/>
Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically.<br/>
Remember that you need to power cycle the robot at least once for the new configuration to be active.<br/>


Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
Once the connection is established, the LED2 will be green.<br/>


==Installation for Mac==
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''.
===Command Line Tools ===
::<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/>
To compile on Mac with <code>Eclipse_e-puck2</code>, it is necessary to have the <code>Command Line Tools</code> installed. It is a bundle of many commonly used tools.<br>
You can install it by typing the following command in a terminal window: <code>xcode-select --install</code>. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.


===Java 8===
==Finding the IP address==
This section can be ignored if Java is already installed on your computer.<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/>
To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac: <code>/usr/libexec/java_home -V</code><br>
You need to have <code>Java SE 8</code> listed to be able to run <code>Eclipse_e-puck2</code>.


: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 <code>.dmg</code> file without the Demos and Samples.
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/>
::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
<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>
:2. Open the <code>.dmg</code> 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/>
==Testing the WiFi connection==
:''Java download page''
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)
* Linux (not available yet)


===Eclipse_e-puck2===
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/>
: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 <code>.dmg</code> file downloaded (confirm opening if a warning message appear) and ''drag and drop'' the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder
::Note: you can place the <code>Eclipse_e-puck2.app</code> anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in <code>Applications</code>.
:3. You can create an Alias to <code>Eclipse_e-puck2.app</code> and place it anywhere if you want.


===First launch and Gatekeeper===
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/>
It’s very likely that <code>Gatekeeper</code> (one of the protections of Mac OS) will prevent you to launch <code>Eclipse_e-puck2.app</code> because it isn’t signed from a known developer.<br>
If you can’t run the program because of a warning of the system, press <code>OK</code> and try to launch it by right clicking on it and choosing <code>open</code> in the contextual menu (may be slow to open the first time).<br>
If <code>Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.</code> or if <code>"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.</code> appears after executing the app the first time, it is needed to disable temporarily <code>Gatekeeper</code>.


To do so :
=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.


:1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
==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:
{| border="1" cellpadding="10" cellspacing="0"
!Command
!Description
!Return value / set value
|-
|<code>0x08</code>
|Get all sensors
|see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi]
|-
|<code>0x09</code>
|Set all actuators
|see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi]
|-
|<code>0x0A</code>
|Set RGB LEDs
|<code>[LED2_red][LED2_blue][LED2_green][LED4_red][LED4_blue][LED4_green][LED6_red][LED6_blue][LED6_green][LED8_red][LED8_blue][LED8_green]</code>
|-
|<code>0x0B</code>
|Get button state: 0 = not pressed, 1 = pressed
|<code>[STATE]</code>
|-
|<code>0x0C</code>
|Get all 4 microphones volumes
|<code>[MIC0_LSB][MIC0_MSB][MIC1_LSB][MIC1_MSB][MIC2_LSB][MIC2_MSB][MIC3_LSB][MIC3_MSB]</code>
|-
|<code>0x0D</code>
|Get distance from ToF sensor (millimeters)
|<code>[DIST_LSB][DIST_MSB]</code>
|-
|<code>0x0E</code>
|Get SD state: 0 = micro sd not connected, 1 = micro sd connected
|<code>[STATE]</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/>
==WiFi==
::''Security settings of Mac OS''
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>


::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.
Each packet is identified by an ID (1 byte). The following IDs are used to send data from the robot to the computer:
::<code>sudo spctl --master-disable</code>
* 0x00 = reserved
:2. Now you can try to run the application and it should work.
* 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565
:3. If Eclipse opened successfully, it is time to reactivate <code>Gatekeeper</code>. Simply set back the setting of <code>Gatekeeper</code>.
* 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:
::For the ones who needed to type a command to disable <code>Gatekeeper</code>, here is the command to reactivate it.
::<code>sudo spctl --master-enable</code>


This procedure is only needed the first time. After that <code>Gatekeeper</code> will remember your choice to let run this application and will not bother you anymore, as long as you use this application. If you re-download it, you will have to redo the procedure for <code>Gatekeeper</code>.
:<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
:*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><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>


'''Important things to avoid :'''
:*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>
:1. The path to the <code>Eclipse_e-puck2.app</code> must contain zero space.  
:*Gyro: raw axes values, between -32768 and 32767, range is +-250dps
::Example :
:*Magnetometer: raw axes values, between -32760 and 32760, range is +-4912 uT (magnetic flux density expressed in micro Tesla)
::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
:*Temp: temperature given in Celsius degrees
::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
:*IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
:2. The file’s structure in the <code>Eclipse_e-puck2.app</code> must remain the same. It means no file inside this app must be moved to another place.
:*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:


===Configuring the PATH variable===
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot.jpg <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot.jpg">]</span><br/>
The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.


If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
:*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 <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
:** 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


<code>export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
For example to receive the camera image (stream) the following steps need to be followed:<br/>
1) connect to the robot through TCP<br/>
2) send the command packet:
:{| border="1"
|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)<br/>
4) go to step 3


If you put the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder then the exact command would be:
=Webots=
TBD


<code>export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
=ROS=
 
TBD
What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
 
If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.bash_profile</code> file by issuing the command:<br>
<code>echo 'export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.bash_profile</code><br>
Close and reopen the terminal before using your newly set environment variable.
 
Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
 
=Get the source code=
The code of the e-puck2 is open source and is available as a git repository. To download the source code you need to install git on your system:
* Windows: downlaod git from [https://gitforwindows.org/ https://gitforwindows.org/] and follow the installation instructions (default configuration is ok)
* Linux: issue the command <code>sudo apt-get install git</code>
* Mac: issue the command <code>brew install git</code>
 
The source code can downloaded with the command:  <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.
 
This repository contains the main microcontroller factory firmware together with the e-puck2 library. This library includes all the functions needed to interact with the robot's sensors and actuators; the factory firmware shows how to use these functions.<br/>
 
A snapshot of the repository 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/>
 
=Creating a project=
==Main microcontroller factory firmware project==
If you want to modify the code of the factory firmware running on the main microcontroller, or if you want to have a look at the implementation details, then you can add this project in Eclipse by following the next steps:<br/>
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
# Next click on the <code>Browse</code> button and choose the project folder of the git repository downloaded previously (should be named <code>e-puck2_main-processor</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
# Click on the <code>Finish</code> button and the project is added to Eclipse.
# Build the project by selecting one directory of the project from the left panel and then <code>Project->Build Project</code>.
 
==Project template==
The main microcontroller factory firmware 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 <code>Project_template</code>, contained in the <code>e-puck2_main-processor</code> project, and place it in the same directory of the <code>e-puck2_main-processor</code> project; you can of course rename the folder to the name you want (e.g. <code>myproject</code>). You must end up with the following directory tree:<br>
* e-puck2
** e-puck2_main-processor
** myproject
 
Then you can add this project in Eclipse by following the next steps:
# Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
# Next click on the <code>Browse</code> button and choose the project folder of your project (e.g. <code>myproject</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
# Click on the <code>Finish</code> button and the project is added to Eclipse.
# Select the project root folder and go to  <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
# Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
##Select the project root folder and go to <code>File->New->Folder</code>.
##Check <code>Advanced >></code> on the bottom.
##Choose <code>Link to alternate location (Linked Folder)</code>.
##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
# Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
# After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
 
Now you can write your own program. If you want to add source files (<code>.c</code>) to the project you need to add them also in the <code>makefile</code>, in the <code>CSRC</code> definition. All the headers files (<code>.h</code>) located next to the <code>makefile</code> are automatically included in the compilation, but if you need to place them into folders, you have to specify these folders in the <code>makefile</code>, in the <code>INCDIR</code> definition. The same is needed for any desired <code>.h</code> files from other external folders.<br/>
In the <code>makefile</code> you can also set the name of your project.<br/>
This <code>makefile</code> uses the main makefile of the <code>e-puck2_main-processor</code> project. This means you can add custom commands to the <code>makefile</code> but it should not interfere with the main makefile.
 
=Configuring the Debugger's settings=
<code>Eclipse_e-puck2</code> 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 <code>Debug Configurations</code> tab of Eclipse (you can also find it on <code>Run->Debug Configurations</code>).
:<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 <code>Generic Blackmagic Probe</code> preset on the left panel. Then you need to configure two things :
 
# In the <code>main</code> tab, select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse should have indexed the binaries and you can list the project and the compiled files using respectively the <code>Browse...</code> and <code>Search Project...</code> buttons.<br/> If there is nothing apering when you press <code>Search Project...</code> then you must enter the <code>.elf</code> file name by hand, which can be found in your project <code>build</code> folder (e.g. <code>build/e-puck2_main-processor.elf</code>).
# In the <code>Startup</code> tab, you need to replace the serial port name written on the first line of the text box by the one used by the GDB Server of your robot. [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used See how to find it].
:* For Windows, it will be <code>\\.\COMX</code>, <code>X</code> being the port number.
:* For Linux, it will be <code>/dev/ttyACMX</code>, <code>X</code> being the port number
:* For Mac, it will be <code>/dev/cu.usbmodemXXXXX</code>, <code>XXXXX</code> being the port number.
:* You can also type <code>${COM_PORT}</code> instead of the com port in order to use the variable <code>COM_PORT</code> for the debug configuration.<br>To change the value of this variable, go to the <code>main</code> tab again, click on the <code>Variables...</code> button and click on the <code>Edit Variables...</code> button. The opened window will let you edit the value of the variable.<br>Using the variable <code>COM_PORT</code> instead of the real com port in a debug configuration is useful if for example you have multiple debug configurations. If for some reason you need to change the serial port to use, then you can simply edit the variable <code>COM_PORT</code> instead of editing the serial port for each debug configuration.
 
If you want to debug another project, you can duplicate this settings and change the relevant parts (project name and path to compiled file) in order to have one launch configuration for each project.<br/>
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug.jpg <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug-small.jpg">]</span><br/>
 
Now you should be able to use the debugger with Eclipse.
 
=Running a debugging session=
Once the debugger is configured, you can start a debugging session. When starting a session, the robot is programmed with the current developed program, thus starting a debugging session means also updating the main microcontroller firmware. This is in fact the way to update the firwmare via Eclipse; to do it manually refer to the section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update].
 
To start a session follow the next steps:
# Connect the robot to the computer and turn it on
# From Eclipse, launch the debug configuration previously set: from the menu <code>Run->Debug configurations...</code>, select the configuration and click on the <code>Debug</code> button.<br>Alternatively you can directly select your configuration from the debugger drop-down menu.<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png <img width=350 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png">]</span><br/>
# When the debugging session is started, Eclipse will change the view to the <code>Debug perspective</code>. Right-click on the main process and select <code>Restart</code> to restart the program from the beginning<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3-small.png">]</span>
# Click on the <code>Resume</code> button on top of the window to start your program. Now you can suspend and resume whenever you want, then when you want to modify your code again you click on the <code>Terminate</code> button and click on the <code>C/C++ perspective</code> button.<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4-small.png">]</span>
 
==Adding breakpoints==
 
==Watch variables==
 
==Analyze microcontroller registers content==

Revision as of 11:55, 8 August 2018

e-puck2 main wiki

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.

Bluetooth and USB

The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth and USB 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, or in position 8 if you want to work with USB.

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

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 communication channels use the same protocol called advanced sercom v2, refer to section Communication protocol: BT and USB for detailed information about this protocol.

WiFi

For working with the WiFi, the main microcontroller and radio module must be programmed with dedicated firmwares (not the standard ones):

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.

Connecting to the Bluetooth

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

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:

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:

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.

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.

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

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

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.


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:

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.

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.

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
0x09 Set all actuators see section Communication protocol: WiFi
0x0A Set RGB LEDs [LED2_red][LED2_blue][LED2_green][LED4_red][LED4_blue][LED4_green][LED6_red][LED6_blue][LED6_green][LED8_red][LED8_blue][LED8_green]
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]

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, between -32760 and 32760, range is +-4912 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; 2=toggle
    • 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

Webots

TBD

ROS

TBD

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