e-puck2 PC side development and Others Extensions: 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/>
=Range and bearing=
<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/>
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/>


=Robot configuration=
The documentation and hardware files are available in the following links:
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.
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Schematics.pdf Schematics (pdf)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Assembling.pdf Assembling (pdf)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_BillOfMaterials.xls Bill of Materials (xls)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_PCB.pdf PCB (pdf)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_HardwareSourceFiles.zip Hardware source files(zip)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Fabrication.zip Fabrication: Gerber, pick and place, ... (zip)]
* [https://projects.gctronic.com/randb/eRandB_manual.pdf e-RandB manual (pdf)]
* [https://projects.gctronic.com/randb/eRandB_firmware.zip e-RandB firmware (zip)]
* [https://projects.gctronic.com/randb/eRandB_software.tgz e-puck software and examples (tgz)]


==USB==
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].
The main microcontroller is initially programmed with a firmware that support USB communication.<br/>


If the main microcontroller isn't programmed with the factory firmware or if you want to be sure to have the last firmware on the robot, you need to program it with the last factory firmware by referring to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update].<br/>
The following table lists the I2C the registers map:
 
<blockquote>
The radio module can be programmed with either the <code>Bluetooth</code> or the <code>WiFi</code> firmware, both are compatible with USB communication:
* Bluetooth: refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
* WiFi: download the [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)] and then refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 
When you want to interact with the robot from the computer you need to place the selector in position 8 to work with USB. <br/>
 
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/>
 
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called <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/>
 
==Bluetooth==
The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication.<br/>
 
If the main microcontroller and radio module aren't programmed with the factory firmware or if you want to be sure to have the last firmwares on the robot, you need to program them with the last factory firmwares:
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
* for the radio module, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 
When you want to interact with the robot from the computer you need to place the selector in position 3 if you want to work with Bluetooth. <br/>
 
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/>
 
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called <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/>
 
==WiFi==
For working with the WiFi, the main microcontroller must be programmed with the factory firmware and the radio module must be programmed with a dedicated firmware (not the factory one):
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
* [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)], for information on how to update the firmware refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
Put the selector in position 15.<br/>
 
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/>
 
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/>
 
=Connecting to the Bluetooth=
 
The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer:
# 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)
 
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.
 
==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.
 
==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/>
 
Alternatively you can also use a simple terminal program (e.g. <code>realterm</code> in Windows) instead of the PC application, then you can issue manually the commands to receive sensors data or for setting the actuators (once connected, type <code>h + ENTER</code> for a list of availables commands).
 
==Python examples==
Here are some basic Python example that show how to get data from the robot through Bluetooth using the commands available with the <code>advanced sercom v2</code>:
* [http://projects.gctronic.com/epuck2/printhelp.py printhelp.py]: print the list of commands available in the <code>advanced sercom v2</code>
* [http://projects.gctronic.com/epuck2/getprox.py getprox.py]: print the values of the proximity sensors
In both examples you need to set the correct Bluetooth serial port related to the robot.
 
===Connecting to multiple robots===
Here is a simple python script [http://projects.gctronic.com/epuck2/multi-robot.py multi-robot.py] that open a connection with 2 robots and exchange data with them using the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol]. This example can be extended to connect to more than 2 robots.
 
==C++ remote library==
A remote library implemented in C++ is available to control the e-puck2 robot via a Bluetooth connection from the computer.<br/>
You can download the library with the command <code>git clone https://github.com/e-puck2/e-puck2_cpp_remote_library</code>.<br/>
A simple example showing how to use the library is also available; you can download it with the command <code>git clone https://github.com/e-puck2/e-puck2_cpp_remote_example</code>.<br/>
When building the example, make sure that both the library and the example are in the same directory, that is you must end up with the following directory tree:<br>
: e-puck2_projects
::|_ e-puck2_cpp_remote_library
::|_ e-puck2_cpp_remote_example
The complete API reference is available in the following link []
 
=Connecting to the WiFi=
The WiFi channel is used to communicate with robot faster than with Bluetooth. At the moment a QQVGA (160x120) color image is transferred to the computer together with the sensors values at about 10 Hz; of course the robot is also able to receive commands from the computer.<br/>
In order to communicate with the robot through WiFi, first you need to configure the network parameters on the robot by connecting directly to it, since the robot is initially configured in access point mode, as explained in the following section. Once the configuration is saved on the robot, it will then connect automatically to the network and you can connect to it.
 
The LED2 is used to indicate the state of the WiFi connection:
* 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/>
 
==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 <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/>
 
<span class="plainlinks">
<table>
<tr>
<td align="center">[1]</td>
<td align="center">[2]</td>
<td align="center">[3]</td>
<td align="center">[4]</td>
</tr>
<tr>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png">]</td>
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png">]</td>
</tr>
</table>
</span><br/>
Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically.<br/>
Remember that you need to power cycle the robot at least once for the new configuration to be active.<br/>
 
Once the connection is established, the LED2 will be green.<br/>
 
In order to reset the current configuration you need to press the user button for 2 seconds (the LED2 red will turn on), then you need to power cycle the robot to enter ''access point mode''.
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset-small.png">]</span><br/>
 
==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 [http://www.gctronic.com/doc/index.php?title=e-puck2#Network_configuration Network configuration] you're ready to go to the next section. <br/>
 
Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to the port labeled <code>Serial Monitor</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]). Then power cycle the robot and the IP address will be shown in the terminal (together with others informations), as illustrated in the following figure:<br/>
<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>
 
==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:
* [http://projects.gctronic.com/epuck2/monitor_wifi_27dddd4.zip Windows executable - WiFi]
* Mac (not available yet)
* [http://projects.gctronic.com/epuck2/monitor_wifi_linux64bit_27dddd4.tar.gz Ubuntu 14.04 (or later) - 64 bit]
 
If you 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/>
 
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/>
 
==Web server==
When the robot is in ''access point mode'' you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface.<br/>
You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address <code>192.168.1.1/monitor.html</code>.
 
=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 [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"
{| border="1" cellpadding="10" cellspacing="0"
!Command
!Address !!Read !!Write
!Description
|-
!Return value / set value
|0 || 1 if data available, 0 otherwise || -
|-
|1 || data MSB || -
|-
|2 || data LSB || -
|-
|3 || bearing MSB || -
|-
|4 || bearing LSB: <code>double((MSB<<8)+LSB)*0.0001</code> to get angle in degrees|| -
|-
|5 || range MSB || -
|-
|6 || range LSB || -
|-
|7 || max peak (adc reading) MSB || -
|-
|-
|<code>0x08</code>
|8 || max peak (adc reading) LSB || -
|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>
|9 || sensor that received the data (between 0..11) || -
|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>
|12 || - || Set transmission power (communication range): between 0 (max range) and 255 (min range)
|Set RGB LEDs, values from 0 (off) to 100 (completely on)
|<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>
|13 || - || data LSB (prepare)
|Get button state: 0 = not pressed, 1 = pressed
|<code>[STATE]</code>
|-
|-
|<code>0x0C</code>
|14 || - || data MSB (send <code>(MSB<<8)+LSB</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>
|16 || - || 0 store light conditions (calibration)
|Get distance from ToF sensor (millimeters)
|-
|<code>[DIST_LSB][DIST_MSB]</code>
|17 || - || 1=onboard calculation, 0=host calculation
|-
|-
|<code>0x0E</code>
|Get SD state: 0 = micro sd not connected, 1 = micro sd connected
|<code>[STATE]</code>
|}
|}
</blockquote>


==WiFi==
==Firmware source code==
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>
 
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 [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol] and are compatible with e-puck1.x:
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
:*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>
 
:*Inclination: between 0.0 and 90.0 degrees (when tilted in any direction)<table><tr><td align="center">0.0 deg</td><td align="center">90.0 deg</td></tr><tr><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination0.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination90.png"></td></tr></table>
:*Gyro: raw axes values, between -32768 and 32767, range is +-250dps
:*Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
:*Temp: temperature given in Celsius degrees
:*IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
:*IR ambient: between 0 (strong light) and 4095 (dark)
:*ToF distance: distance given in millimeters
:*Mic volume: between 0 and 4095
:*Motors steps: 1000 steps per wheel revolution
:*Battery:
:*uSD state: 1 if the micro sd is present and can be read/write, 0 otherwise
:*TV remote data: RC5 protocol
:*Selector position: between 0 and 15
:*Ground proximity: between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white)
:*Ground ambient: between 0 (strong light) and 1023 (dark)
:*Button state: 1 button pressed, 0 button released
* 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested
The following IDs are used to send data from the computer to the robot:
* 0x80 = commands packet; packet size (without id) = 20 bytes:
 
:<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/>
 
:*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
:** 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:<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
 
=Webots=
TBD
 
=ROS=
This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema:<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck-ros-schema.png <img width=450 src="http://www.gctronic.com/doc/images/epuck-ros-schema-small.png">]</span>
''<font size="2">Click to enlarge</font>''<br/>
 
First of all you need to install and configure ROS, refer to [http://wiki.ros.org/Distributions http://wiki.ros.org/Distributions] for more informations. <font style="color:red"> This tutorial is based on ROS Kinetic</font>.
 
Starting from the work done with the e-puck1 (see [https://www.gctronic.com/doc/index.php?title=E-Puck#ROS E-Puck ROS]), we updated the code in order to support the e-puck2 robot.
 
==Initial configuration==
The following steps need to be done only once, after installing ROS:
:1. If not already done, create a catkin workspace, refer to [http://wiki.ros.org/catkin/Tutorials/create_a_workspace http://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands: 
<pre>  mkdir -p ~/catkin_ws/src
  cd ~/catkin_ws/src
  catkin_init_workspace
  cd ~/catkin_ws/
  catkin_make
  source devel/setup.bash </pre>
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
:3. Move to <code>~/catkin_ws/src</code> and clone the ROS e-puck2 driver repo:
:* if you are working with Python: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>
:* if you are working with cpp: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>
:4. Install the dependencies:
:* ROS:
:** [http://wiki.ros.org/gmapping gmapping (SLAM)] package: <code>sudo apt-get install ros-kinetic-gmapping</code>
:* Python:
:** The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies:
:*** install the Python setup tools: <code>sudo apt-get install python-setuptools</code>
:*** install the Python image library: <code>sudo apt-get install python-imaging</code>
:*** install pybluez: <code>sudo pip install pybluez</code>
:**** install pybluez dependencies: <code>sudo apt-get install libbluetooth-dev</code>
:* cpp:
:** install the library used to communicate with Bluetooth: <code>sudo apt-get install libbluetooth-dev</code>
:5. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
:6. Program the e-puck2 robot with the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware factory firmware] and put the selector in position 3
 
==Running the Python ROS node==
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>. <br/>
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
Moreover make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): <code>chmod +x ./src/epuck_driver/scripts/epuck2_driver.py</code>. <br/>
 
Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related MAC address.
 
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.


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


If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
==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.


The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
==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.


The following graph shows all the topics published by the e-puck2 driver node and the <code>rviz</code> interface: <br/>
=Ground sensors=
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_small.png">]</span>
<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>
''<font size="2">Click to enlarge</font>''
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz_small.png">]</span>
''<font size="2">Click to enlarge</font>''<br/>


==Running the cpp ROS node==
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].
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>. <br/>
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>


Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
Once the robot is 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/>
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related MAC address.
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/>
For more information about the Bluetooth protocol refer to section [https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol Advanced sercom protocol].


First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
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.


Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [http://wiki.ros.org/roslaunch roslaunch]).<br/>
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/>
Open a terminal and issue the following command: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'</code>.<br/>
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.


If all is going well the robot will be ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
==Assembly for 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>
# Unscrew the 3 spacers and remove the battery.
# Remove the top side from the case body gently.
# 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.
# 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.


The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
=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.


==Move the robot==
==Assembly==
You have some options to move the robot.<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>
# Unscrew the 3 screws, unmount the e-jumper (top piece where there is the speaker) and unscrew the 3 spacers
# 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 first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right.<br/>
==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].  


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


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


==Control the RGB LEDs==
===Extension firmware===
The general command to change the RGB LEDs colors is the following:<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/>
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"</code><br/>
The communication between the e-puck and the module is handled through I2C (address 0xC0) and the following registers are defined:
The values range is from 0 (off) to 100 (completely on). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the RGB LEDs.<br/>
* 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


For instance to set all the RGB LEDs to red, issue the following command:<br/>
===e-puck2 demos===
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"</code><br/>
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].


To turn off all the RGB LEDs issue the following command:<br/>
==Images==
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [0,0,0, 0,0,0, 0,0,0, 0,0,0]}"</code>
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/>


==Control the LEDs==
The robot can be easily moved to the charging station as shown in the following figure: <br/>
The general command to change the LEDs state is the following:<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/>
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7, body LED, front LED]}"</code><br/>
The values are: 0 (off), 1 (on) and 2 (toggle). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the LEDs.<br/>


For instance to turn on LED1, LED5, body LED and front LED, issue the following command:<br/>
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/>
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1,0,1,0,1,1]}"</code><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/>


To toggle the state of all the LEDs issue the following command:<br/>
==Videos==
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [2,2,2,2,2,2]}"</code>
{{#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_PC_side_development&oldid=2183"