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

From GCtronic wiki
(Difference between pages)
Jump to: navigation, search
(Firmware)
 
(Multiple robots)
 
Line 1: Line 1:
This is a mini how-to of the e-puck extension board for the Gumstix Overo COM.
+
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
  
=Minimal getting started=
+
=Robot configuration=
{| style="color:black; background-color:#ffffcc;" cellspacing="0" border="1"
+
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.
|
 
# upload the [http://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware standard firmware] to the e-puck robot and put selector in position 10
 
# connect the USB cable: mini-USB to the extension module and the other side to the PC
 
# execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
 
# switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
 
# login with user=root, password=root
 
|}
 
  
<font style="color:red"> Anyway you're encouraged to read all the documentation since you'll find more detailed explanations. </font>
+
==USB==
 +
The main microcontroller is initially programmed with a firmware that support USB communication.<br/>
  
=Introduction=
+
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/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Ext+robot1.jpg <img width=200 src="http://www.gctronic.com/doc/images/Ext+robot1.jpg">]</span> <br/>
 
This introductory section explains the minimal procedures needed to work with the Gumstix Overo computer-on-module (COM) mounted on the e-puck extension board and gives a general overview of the available demos and scripts shipped with the micro sd. You can also refer to [http://projects.gctronic.com/Gumstix/extension-instructions.pdf extension-instructions] that is a document containing the most important information in order to start working with the extension. The extension is mostly an interface between the e-puck robot and the Gumstix Overo COM.  
 
  
Gumstix Overo COM: [http://www.gumstix.com product information] and [http://www.gumstix.org programming information],
+
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]
  
==Full package==
+
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/>
The full package content is:
 
* e-puck extension with Gumstix Overo COM and micro sd card already inserted
 
* USB adapter for the micro sd
 
* A to mini-B USB cable
 
* USB wifi dongle
 
* external power adapter
 
* USB host adapter
 
The standard COM mounted on the e-puck extension is the Gumstix Overo EarthSTORM COM. Some extensions were delivered with the Gumstix Overo SandSTORM COM, don't worry, the main difference between the two COMs is that the SandSTORM has no flash memory, but the flash isn't necessary since the system is booted from the micro sd.
 
  
==Requirements==
+
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/>
In order to connect to the extension through the mini USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise visit the following site and download the drivers for your architecture (32 or 64 bits) [http://www.ftdichip.com/Drivers/VCP.htm FTDI drivers].
 
  
==General procedure==
+
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2], refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB_2 Communication protocol: BT and USB] for detailed information about this protocol.<br/>
The e-puck extension board for the Gumstix Overo COM comes with a pre-configured system ready to run without any additional configuration. The whole system is installed on a micro sd and is composed of:
 
* U-Boot (bootloader customized for the hardware)
 
<!--* OMAP35x Linux PSP [https://www-a.ti.com/downloads/sds_support/targetcontent/psp/omap35x/index.html https://www-a.ti.com/downloads/sds_support/targetcontent/psp/omap35x/index.html] (linux kernel) -->
 
* OMAP35x Linux TI-PSP [http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary] (linux kernel)
 
* some demos and useful scripts in the /home/root directory
 
It's important to note that the flash isn't reprogrammed, so it will contain the factory system.
 
  
In order to access the system from a PC (console mode), the following steps must be performed:
+
==Bluetooth==
# connect the USB cable: mini-USB to the extension module and the other side to the PC
+
The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication.<br/>
# execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
 
# switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
 
# login with user=root, password=root
 
  
==Wireless setup==
+
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:
Before proceding with the following configurations be sure that the WiFi dongle is well recognized, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#WiFi_dongle WiFi_dongle].
+
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
===Wireless configuration using a script===
+
* for the radio module, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
The script ''setupWifi'' placed under /home/root/scripts is used to configure easily the wireless network (managed mode) and need to be adapted to your specific situation. The script is shown below:
 
<pre>
 
#!/bin/bash
 
ifconfig wlan0 up
 
iwconfig wlan0 essid SSID key HEX_KEY
 
iwconfig wlan0 ap MAC_ADDRESS
 
iwconfig wlan0 rate 54M
 
ifconfig wlan0 LOCAL_IP netmask SUBNET_MASK
 
route add default gw GATEWAY_IP
 
</pre>
 
To know the available wifi networks and related information such as mac address of the access point, you can issue the command ''iwlist scanning wlan0''.
 
  
On some platforms, udev may rename the network interface ''wlan0.'' In this event, the 'setupWifi' script will return several errors, some of which will say "No Such Device." To identify your network interfaces, use the commands ''ifconfig'' or ''iwconfig.'' These will provide a listing of your devices, and their current states. Identify the appropriate interface (typically ''wlan#'' where "#" is a number) and replace ''wlan0'' in the above script with this.
+
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/>
  
If you're using dhcp, you can instead adapt the script ''setupWifiDhcp'' found under /home/root/scripts:
+
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/>
<pre>
 
#!/bin/bash
 
ifconfig wlan0 up
 
iwconfig wlan0 essid SSID key HEX_KEY
 
iwconfig wlan0 ap MAC_ADDRESS
 
iwconfig wlan0 rate 54M
 
dhclient wlan0
 
</pre>
 
  
The parameters that must be customized are shown in capitals; after that you can execute the script typing ''./setupWifi'' (or ''./setupWifiDhcp'') and after a while a message should be displayed indicating that the wireless is ready. You can test the network configuration using ''ping''.
+
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2], refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB Communication protocol: BT and USB] for detailed information about this protocol.<br/>
  
It may be necessary to create a directory if you get the error "can't create /var/lib/dhcp/dhclient.leases: No such file or directory." Use the ''mkdir'' command
+
==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/>
  
<pre>
+
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/>
mkdir /var/lib/dhcp
 
</pre>
 
  
Usually, when the Wifi dongle is connected to the AP, a message is written in the message buffer of the kernel. The following bash code snippet can be used to make sure that the connection is well established when the program returns:
+
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/>
<pre>
 
#!/bin/bash
 
echo Wait until the Wifi is connected to the AP
 
while true
 
do
 
  #the text "link becomes ready" can vary according the Wifi dongle
 
  a=$(dmesg | grep wlan0 | grep "link becomes ready")
 
  if [ -n "$a" ]
 
  then
 
    echo Wifi enabled!
 
    exit
 
  fi
 
  sleep 1
 
done
 
</pre>
 
  
In order for the ''setupWifi'' or ''setupWifiDhcp'' scripts to be run during boot, copy the appropriate script into the ''init.d'' directory with the other start/stop scripts.
+
=Connecting to the Bluetooth=
<pre>
 
cp -i ~/scripts/setupWifi /etc/init.d/setupWifi
 
</pre>
 
Then determine which run level the system is using with the command:
 
<pre>
 
runlevel
 
</pre>
 
This should return "N #" where # is the run level number. Create a link to your script in the ''init.d'' directory within the directory ''/etc/rc#.d'' Name the link ''S##setupWifi.'' The number ## (customarily 2 digits, which you choose) determines where in the startup sequence your script will be run. It is good advice to choose a number just smaller than the largest in the ''rc#.d'' directory, this way the script is not called before lower-level ones. The creation of this link can be done with the following command (where # and ## must be changed to their appropriate values).
 
<pre>
 
ln -i -s /etc/init.d/setupWifi /etc/rc#.d/S##setupWifi
 
</pre>
 
  
===Wireless configuration using a wpa_supplicant===
+
The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer:
Alternativerly, the Wifi connection can be set up by using both [http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant] and the native wifi setup. This has the advantage to be more robust against failure. In order to do that, the Wifi interface can be added to /etc/network/interfaces, this way:
+
# 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)
<pre>
+
# Channel 2, UART: port to connect to the UART port of the main processor
auto wlan0
+
# Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
iface wlan0 inet static
 
address 192.168.1.2
 
netmask 255.255.255.0
 
wpa-conf /path/to/wifi.conf #this should be replaced by the absolute location of wifi.conf
 
</pre>
 
  
And the related wifi.conf
+
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<br>
<pre>
+
'''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>
ctrl_interface=/var/run/wpa_supplicant
+
::<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/>
ctrl_interface_group=0
+
Then it will be discoverable and you will be able to pair with it.<br>
ap_scan=1
+
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.
network={
 
  ssid="myssid" #this should be replaced by your ssid
 
  scan_ssid=1
 
  key_mgmt=NONE
 
  wep_key0=1234567890 #this should be replaced by your WEP key
 
  wep_tx_keyidx=0
 
}
 
</pre>
 
  
In this example, static IPs and WEP encryption have been used. DHCP and other encryption can be obviously used by following the documentation both of the linux native network setup and of [http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant].
+
==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>
  
===Network performance===
+
==Windows 10==
To test the network performance you could use the ''iperf'' tool installed on the system. In the server side you must issue the following command (either for TCP or UDP testing), after which the server machine is listening for incoming data:
+
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/>
<pre>
+
To see which COM port corresponds to which channel you need to:
iperf -s      [TCP]
+
# open the Bluetooth devices manager
iperf -s -u  [UDP]
+
# pair with the robot
</pre>
+
# click on <code>More Bluetooth options</code>
In the client side you must type:
+
# the ports and related channels are listed in the <code>COM Ports</code> tab, as shown in the following figure:<br/>
<pre>
+
:<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>
iperf -c SERVER-IP                  [TCP]
 
iperf -c SERBER-IP -u -b 50000000    [UDP]
 
</pre>
 
Where ''SERVER-IP'' must be changed accordingly to the network configuration.
 
  
==Package manager==
+
==Linux==
If you have an internet connection up and running you can update and install easily new packages with ''opkg''. Some of the useful operations you could do are:
+
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <br/>
* update repositories: <code>opkg update</code>
+
<code>sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2</code><br/>
* update installed packages and kernel; pay attention that the camera driver is based on the provided kernel and upgrading it will prevent the use of the camera: <code>opkg upgrade</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.
* list of software currently installed on the machine: <code>opkg list_installed</code>
 
* install a new package (perl in the example): <code>opkg install perl</code>
 
* remove a pacakge (perl in the example): <code>opkg remove perl</code>
 
* list of all packages available to be installed: <code>opkg list</code>
 
  
===opkg update failed===
+
==Mac==
If you get errors on reaching the default repo sources you can try changing them by following these steps:
+
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.
# make a copy of the current repo: <code>mv /etc/opkg/base-feed.conf /dest-dir</code>
 
# add the new repo: <code>echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base' > /etc/opkg/base-feed.conf</code>
 
# opkg update
 
The procedure shows how to change the <code>base</code> repo, the same need to be done for all others repos.
 
  
==USB ports==
+
==Testing the Bluetooth connection==
The e-puck extension board for the Gumstix Overo COM comes with two USB interfaces called USB host and USB otg. If you try inserting devices that require more energy than the one permitted on the otg, the device will not be enabled automatically. In these cases you can use the three scripts ''usbup'', ''usbdown'' and ''usbenable'' to respectively power up, power down and enable the USB device; they're placed under /home/root/scripts. These scripts are intended for primary use with the USB otg port, even if they're suitable for both ports (otg and host).
+
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/>
* ''./usbup otg'' (or ''./usbup host''): power on the usb device
+
In the connection textfield you need to enter the UART channel port, for example:
* ''./usbdown otg'' (or ''./usbdown host''): power off the usb device
+
* Windows 7: <code>COM258</code>
* ''./usbenable otg'' (or ''./usbenable host''): activate the usb device (now is in the usb device list)
+
* 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/>
  
==Demos==
+
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).
A specific firmware must be charged on the e-puck to run the Gumstix Overo linked demos, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#E-puck_firmware E-puck firmware].
 
  
===Serial test on the Gumstix Overo COM===
+
==Python examples==
This small program read and write from a serial port (non-canonical mode). For more information on the usage refers to [http://docwiki.gumstix.org/index.php?title=Sample_code/C/Serial sertest] ([http://projects.gctronic.com/Gumstix/sertest.tar.gz sertest sources]). It's placed under /home/root/demos/gumstix-common, and it's called ''sertest''.
+
Here are some basic Python examples that show how to get data from the robot through Bluetooth using the commands available with the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2]:
 +
* [http://projects.gctronic.com/epuck2/printhelp.py printhelp.py]: print the list of commands available in the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB advanced sercom v2]
 +
* [http://projects.gctronic.com/epuck2/getprox.py getprox.py]: print the values of the proximity sensors
 +
* [http://projects.gctronic.com/epuck2/complete.py complete.py]: set all the actuators and get all the sensors data printing their values on the screen
 +
* [http://projects.gctronic.com/epuck2/getimage.py getimage.py]: request an image and save it to disk
 +
In all the examples you need to set the correct Bluetooth serial port related to the robot.
  
===Advanced sercom===
+
===Connecting to multiple robots===
Once the new firmware is running on the e-puck, the selector must be set in position 10 to run the advanced sercom for the Gumstix Overo. <br/>
+
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.
Now you can type (after being in /home/root/demos/gumstix-common) ''./sertest -p /dev/ttyS0 -b 230400'' (or simply ''./ser+ENTER'') to enter the e-puck menu in console mode; for a list of all available commands type ''h+ENTER''. After stopping the sertest program (CTRL+C), the display may not respond correctly; to reset the display run the script ''r'' by simply typing ''./r+ENTER''. Now the display should behave normally.<br/>
 
For more information about the advanced sercom refer to the page [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol Advanced sercom protocol].
 
  
===Images grabbing (camera driver)===
+
==C++ remote library==
<!-- A small utility called ''v4l2grab'' was used for grabbing JPEGs from V4L2 devices ([http://github.com/twam/v4l2grab http://github.com/twam/v4l2grab]). <br/>
+
A remote control library implemented in C++ is available to control the e-puck2 robot via a Bluetooth connection from the computer.<br/>
In order to get an image from the e-puck camera you need to follow these steps:
+
The remote control library is multiplatform and uses only standard C++ libraries.<br/>
# load the driver typing (after being in /home/root/demos) ''insmod po6030cam.ko po6030_format=1''; a message should be displayed indicating that the camera is successfully detected
+
You can download the library with the command <code>git clone https://github.com/e-puck2/e-puck2_cpp_remote_library</code>.<br/>
# run the program typing (after being in /home/root/demos) ''./v4l2grab -o image.jpg''
+
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/>
For more information on the options available refer to ''./v4l2grab -h''.
+
Before building the example you need to build the library. Then when building the example, make sure that both the library and the example are in the same directory, that is you must end up with the following directory tree:<br>
-->
+
: e-puck2_projects
A small application called ''v4l2grab'' ([http://projects.gctronic.com/Gumstix/v4l2grab-2buff-rev17-13.08.14.zip v4l2grab.zip]) based on [http://github.com/twam/v4l2grab http://github.com/twam/v4l2grab] was used for grabbing JPEGs from V4L2 devices. In order to get an image from the e-puck camera you need to run the program typing (after being in <code>/home/root/demos/gumstix-common/</code>) <code>./v4l2grab -o image.jpg</code>. The application communicates also with the robot through the serial line to know the camera orientation and rotates the image automatically in case the camera is rotated (refer to section [http://www.gctronic.com/doc/index.php/E-Puck#Camera e-puck camera] for more information on camera orientation).
+
::|_ e-puck2_cpp_remote_library
For more information on the options available refer to the help by typing<code>./v4l2grab -h</code>.
+
::|_ e-puck2_cpp_remote_example
 +
The complete API reference is available in the following link [http://projects.gctronic.com/epuck2/e-puck2_cpp_remote_library_api_reference_rev3ac41e3.pdf e-puck2_cpp_remote_library_api_reference.pdf].
  
===Images transfer (camera driver)===
+
=Connecting to the WiFi=
This demo is divided in two parts: one running on the e-puck extension board for the Gumstix Overo COM that continuously request images to the e-puck camera and transfers them over UDP, and the other running on a PC that acts as a server and is listening for the images visualizing them as soon as they are available. A network link must be established between the two in order to run this demo; for more information on how to configure the network refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Wireless_setup Wireless setup].
+
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.
  
First of all you need to start the server ([http://projects.gctronic.com/Gumstix/Receiver.zip Receiver QT project]). The application is a Qt project, so the compilation may be handled easily with [https://wiki.qt.io/Category:Tools::QtCreator Qt Creator]; alternatively [http://doc.qt.io/qt-5/qmake-manual.html qmake] can be used. The usage is very simple: the server listening port and the protocol (only UDP available at the moment) must be selected first, then click on the button ''Connect''; at this moment the application is waiting images.<br/>
+
The LED2 is used to indicate the state of the WiFi connection:
On the e-puck extension board side, you need to run the program typing (after being in /home/root/demos) ''./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0''. ''SERVER_IP'' is the address of the PC and ''SERVER_PORT'' should be the same as configured when the receiver was started. The ''f'' option indicates the format (in this case RGB) and ''t'' indicates the transfer mode (0=UDP, 1=TCP).
+
* 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
On the e-puck extension board side, you need to follow these steps:
+
* blue (toggling) indicates that the robot is transferring the image to the computer
# load the driver typing (after being in /home/root/demos) ''insmod po6030cam.ko po6030_format=0''; a message should be displayed indicating that the camera is successfully detected
+
* off when the robot cannot connect to the saved configuration
# run the program typing (after being in /home/root/demos) ''./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0''. ''SERVER_IP'' is the address of the PC and ''SERVER_PORT'' should be the same as configured when the receiver was started. The ''f'' option indicates the format (in this case RGB) and ''t'' indicates the transfer mode (0=UDP, 1=TCP but still not available).
+
::<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/>
-->
 
For more information on the options available refer to ''./v4l2grab-send -h''. <br/>
 
The sources for the sender, that is an extension of the ''v4l2grab'' application, could be found in the following link [http://projects.gctronic.com/Gumstix/v4l2grab-send.zip v4l2grab-send.zip]; in order to compile the application the ''Makefile'' must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to [http://focus.ti.com/docs/prod/folders/print/omap3503.html http://focus.ti.com/docs/prod/folders/print/omap3503.html]).
 
  
===Music player===
+
==Network configuration==
This isn't really a demo, it's only one of the possible way on how to listen something from the extension module. The system comes with a tool called [http://www.mplayerhq.hu/ mplayer] that supports many multimedia formats. You can use it to play for example an mp3 file in this way:
+
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.
<pre>
 
mplayer file.mp3
 
</pre>
 
You can then adjust the volume with either the ''alsamixer'' graphical tool (adjusting DAC2 control) or using the command line tool ''amixer''; the following command can be used for instance to set the volume to 80%:
 
<pre>
 
amixer set 'DAC2 Analog' 80%
 
</pre>
 
  
==File transfer==
+
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/>
===ssh===
+
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/>
The e-puck extension board for the Gumstix Overo COM supports ssh connections through dropbear (small SSH 2 server and client) that is installed on the system.<br/>
 
To exchange file between the module and the PC, the ''scp'' tool (secure copy) will be used; the general command is the following:
 
<pre>
 
scp user@ip:path-to-file file-name
 
</pre>
 
As an example of transfer a file from the PC to the extension, let the PC user be ''stefano'' and its IP be 192.168.1.10, then the command will be:
 
<pre>
 
scp stefano@192.168.1.10:/home/stefano/file-to-send prova
 
</pre>
 
The file ''file-to-send'' will be renamed in ''prova'' and placed in the current directory.
 
  
If you are working in Windows you can use [http://winscp.net WinSCP] to exchange data between the robot and the computer.
+
<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/>
  
===zmodem===
+
Once the connection is established, the LED2 will be green.<br/>
The following instructions to exchange data between the extension and the computer refer to ''minicom'' as the terminal.<br/>
 
If you want to receive a file, that is transfer a file from the PC to the e-puck extension board for the Gumstix Overo COM, you need to follow these steps:
 
# open a terminal window with minicom; now you access the linux system in console mode
 
# type ''lrz''
 
# press ''CTRL+A'' and then ''S''
 
# select ''zmodem'' and navigate to find the file you want to tranfer
 
# select the file with the ''SPACEBAR'' and then press ''ENTER'' to start the transfer
 
# when transfer is complete press ''ENTER'' once more to come back to the command line
 
For more information type ''lrz -h''.
 
  
If you want to send a file, that is transfer a file from the e-puck extension board to the PC, you need to follow these steps:
+
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''.
# open a terminal window with minicom; now you access the linux system in console 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/>
# type ''lsz file-name'', where ''file-name'' is the file you want to transfer
 
# when transfer is complete press ''ENTER'' to return to the command line
 
The file will be placed in the directory where minicom is started. For more information type ''lsz -h''.
 
  
==Extension LEDs==
+
==Finding the IP address==
The e-puck extension board for the Gumstix Overo COM comprises 8 new small leds that can be turned on/off easily from the file system in this way:
+
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/>
<pre>
 
echo 1 > /sys/class/gpio/gpio7x/value  [turn on]
 
echo 0 > /sys/class/gpio/gpio7x/value  [turn off]
 
</pre>
 
where x ranges from 0 to 7. For more information on gpio refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode GPIO - pins mode].
 
  
==File system image==
+
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/>
You can download the entire system running on the micro sd released with the e-puck extension board from the following links: [http://projects.gctronic.com/Gumstix/epuck-overo-e2fs-12.08.14.tar.gz file system] and [http://projects.gctronic.com/Gumstix/epuck-overo-fat-30.03.15.tar.gz FAT] (with camera driver 1.3). <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>
In order to prepare the micro sd you can use a script ([http://projects.gctronic.com/Gumstix/prepareMicroSD.sh prepareMicroSD.sh]), in which you need only to specify where to find the two previously downloaded files and run it (''./prepareMicroSD.sh /path/to/dev'') to have your micro sd ready to be used. Alternatively you can have a look the gumstix documentation on how to [https://www.gumstix.com/support/getting-started/create-bootable-microsd-card/ create a bootable microsd card].<br/>
 
<!--
 
<font style="color:red"> A new camera driver release (1.1) is available, refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#Camera_driver Camera driver] for information on how to update the system</font>. <br/>
 
-->
 
If you experience problems in booting from mmc enter u-boot and issue the following command:
 
<pre>
 
nand erase 240000 20000
 
reset
 
</pre>
 
Moreover if you need you can find pre-built images for the Gumstix Overo in the following link: [http://gumstix.org/download-prebuilt-images.html http://gumstix.org/download-prebuilt-images.html].
 
===Sources===
 
The complete kernel sources (comprising the camera driver) can be downloaded from the following link [http://projects.gctronic.com/Gumstix/gctronic-ti-psp-omap-2.6.32-12.08.14.zip gctronic-ti-psp-omap-2.6.32-12.08.14.zip] if you want to try to build it your own (anyway you don't need to do it because the released micro SD is ready to run with this system). The system is based on:
 
<!--* [http://www.sakoman.com/feeds/omap3/glibc/images/overo/201005041130/ sakoman's pre-built file system image]-->
 
* sakoman's pre-built file system image
 
* [http://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary ti-psp-2.6.32 kernel]
 
  
===Camera driver===
+
==Testing the WiFi connection==
The driver of the camera is open-source, you can download the code in the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Sources kernel source]. The driver is located in <code>/ti-psp-omap/drivers/media/video/po6030cam.c</code>; related ISP code is located in <code>/ti-psp-omap/drivers/media/video/isp</code>.
+
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:
====Release notes====
+
* [http://projects.gctronic.com/epuck2/monitor_wifi_27dddd4.zip Windows executable - WiFi]
:1.0
+
* Mac (not available yet)
* support for PO6030 camera (front e-puck camera or camera of omnicam module version 1)
+
* [http://projects.gctronic.com/epuck2/monitor_wifi_linux64bit_27dddd4.tar.gz Ubuntu 14.04 (or later) - 64 bit]
* support for RGB565 output format
 
* only 640x480 resolution images
 
:1.1
 
* added support for PO3030 camera
 
* added support for YUV422 output format
 
* brightness, contrast, saturation, auto-white balance, red gain, blue gain controls available
 
:1.2
 
* exposure control available
 
* support for 480x480 color and greyscale images
 
:1.3
 
* added support for PO8030 camera
 
  
====System update====
+
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/>
In order to update the system released in the micro sd with the new driver you need to download the kernel modules from [http://projects.gctronic.com/Gumstix/driver-update/1.3/linux-2.6.32.tar.gz linux-2.6.32.tar.gz] and the kernel image from
 
[http://projects.gctronic.com/Gumstix/driver-update/1.3/uImage uImage]. Then:
 
# insert the micro sd in the computer; two partitions will be recognized
 
# copy the kernel image (uImage) in the FAT partition
 
# extract the kernel modules in the second partition:
 
## cd path/to/partition
 
## sudo tar zxvf path/to/kernel-modules
 
# unmount the micro sd from the computer and insert it in the extension; at first boot type ''depmod -a'' and reboot
 
  
==Daemon==
+
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 can be useful to start a daemon at the end of the boot process in order to run your own program at the start up of the e-puck (when the console mode won't be accessible). This can be done by placing your program executable into ''/etc/init.d'' and then:
 
<pre>
 
cp /path/to/your/executable /usr/sbin/mainProgram
 
cd /etc/init.d
 
update-rc.d mainProgram defaults 99
 
</pre>
 
  
The daemon can be removed by removing these files:
+
==Web server==
<pre>
+
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/>
rm /etc/rc*/*mainProgram*
+
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>.
</pre>
 
  
Remember to give execution permission to the program by typing <code>chmod +x mainProgram</code>.
+
==Python examples==
 +
===Connecting to multiple robots===
 +
A simple Python 3 script was developed as a starting point to open a connection with multiple robots and exchange data with them using the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 WiFi communication protocol]. The demo was tested with 10 robots but can be easily extended to connect to more robots.<br/>
 +
You can download the script with the command <code>git clone https://github.com/e-puck2/e-puck2_python_wifi_multi.git</code>. The code was tested to work with Python 3.x.
  
=Hardware=
+
=Communication protocol=
The following figure shows the main components offered by the e-puck extension for the Gumstix Overo COM and their interconnection with the e-puck robot and the Gumstix Overo COM.<br/>
+
This section is the hardest part to understand. It outlines all the details about the communication protocols that you'll need to implement in order to communicate with the robot form the computer. So spend a bit of time reading and re-reading this section in order to grasp completely all the details.
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-schema.jpg <img width=600 src="http://www.gctronic.com/doc/images/Gumstix-schema.jpg">]</span> <br/>
 
In particular there are:
 
* a Gumstix Overo COMs: compatible with all Gumstix Overo COM models. The communication between the Gumstix Overo COM (OMAP 35xx) and the e-puck (dsPIC) is handled with a serial line at 230400 baud
 
* a mini-usb connector (console) used to enter the linux system through a terminal
 
* one usb otg and one usb host: these two connectors are really useful to connect whatever peripheral you need, like a WiFi dongle or simply a pen drive to extend the memory
 
* a speaker ([http://projects.gctronic.com/Gumstix/datasheet-speaker.pdf speaker specification]): with Linux running on the Gumstix Overo COM, it's really easy play any audio format you need or implement a speech synthesizer. If the user prefer to have the speaker on the extension linked to the e-puck processor, it can simply be done changing two small resistors
 
* 8 LEDs: have you ever seen a board without leds?! Anyway they are completely controllable through GPIO lines (gpio70-gpio77), for detailed information refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode GPIO - pins mode]
 
* an I2C connector (@5 V)
 
* a rotary selector: one could choose what program is running on the e-puck based on the selector position
 
* 2 long range infrared proximity sensors ([http://projects.gctronic.com/Gumstix/datasheet-long-range.pdf long range specification]) <!-- , up to 15-20 cm -->
 
* the PixelPlus PO6030 camera remains mounted on the robot, but you could receive image from it by using the OMAP ISP (Camera Interface Subsystem); this way we can receive up to 18 frames per second (VGA color images)
 
  
The following figure illustrates where the components are physically placed on the e-puck extension board for the Gumstix Overo COM. <br/>
+
==Bluetooth and USB==
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-schema2.jpg <img width=600 src="http://www.gctronic.com/doc/images/Gumstix-schema2.jpg">]</span> <br/>
+
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
 +
|<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>
 +
see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi] for the content description
 +
|-
 +
|<code>0x09</code>
 +
|Set all actuators
 +
|<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot-bt.jpg <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot-bt.jpg">]</span>
 +
see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi] for the content description
 +
|-
 +
|<code>0x0A</code>
 +
|Set RGB LEDs, values from 0 (off) to 100 (completely on)
 +
|<code>[LED2_red][LED2_green][LED2_blue][LED4_red][LED4_green][LED4_blue][LED6_red][LED6_green][LED6_blue][LED8_red][LED8_green][LED8_blue]</code>
 +
|-
 +
|<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>
 +
|}
  
==Electrical schema==
+
==WiFi==
The circuit diagram of the e-puck extension for Gumstix Overo COM is available to the community on the following link [http://projects.gctronic.com/Gumstix/GC_EXT5_V3.pdf electrical schema].
+
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>
  
==Long range proximity sensors==
+
Each packet is identified by an ID (1 byte). The following IDs are used to send data from the robot to the computer:
The following chart illustrates the long range proximity sensors response towards a white surface. These results should be considered indicative.<br/>
+
* 0x00 = reserved
<span class="plainlinks">[http://www.gctronic.com/doc/images/IR-characterization.jpg <img width=400 src="http://www.gctronic.com/doc/images/IR-characterization.jpg">]</span>
+
* 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:
  
A zoom in the bigger distances shows that the values returned from the sensors are still usable to react to obstacles.
+
:<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>
  
<chart width="600" height="300" legend_title="Legend" x_type="length" x_unit="cm" x_title="Distance" y_type="general" y_unit="ADC value" y_title="Prox">
+
:*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>
Prox;14;203
+
:*Gyro: raw axes values, between -32768 and 32767, range is +-250dps
Prox;16;154
+
:*Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
Prox;18;128
+
:*Temp: temperature given in Celsius degrees
Prox;20;105
+
:*IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
Prox;22;88
+
:*IR ambient: between 0 (strong light) and 4095 (dark)
Prox;24;78
+
:*ToF distance: distance given in millimeters
Prox;26;70
+
:*Mic volume: between 0 and 4095
</chart>
+
:*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:
  
==WiFi dongle==
+
:<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/>
===Zyxel===
 
The WiFi dongle shipped with the extension board for the Gumstix Overo COM is a ZyXEL NWD271N USB adapter, 802.11n compatible. It's based on an Atheros chipset, for more infromation about the linux driver visit the following site [http://linuxwireless.org/en/users/Drivers/ar9170 http://linuxwireless.org/en/users/Drivers/ar9170]. <br/>
 
The measured throughput with the e-puck extension and provided wifi dongle is '''20 Mb/s'''. <br/>
 
The consumption of the wifi dongle is 100 mA in standby and 300 mA when active.
 
<!--During prototyping another WiFi dongle was used, the Trendnet -->
 
  
===Edimax===
+
:*request:
A new WiFi dongle is shipped starting from January 2012, it is the Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu).
+
:** bit0: 0=stop image stream; 1=start image stream
The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it:
+
:** bit1: 0=stop sensors stream; 1=start sensors stream
# turn on the robot and login with <code>user=root, password=root</code>
+
:*settings:
# only needed if the wifi dongle is connected to the USB OTG: type <code>./scripts/gumstix-common/usbenable otg</code>. Don't worry about the warning <code>usb 1-1: new config #1 exceeds power limit by 400mA</code>
+
:** bit0: 1=calibrate IR proximity sensors
# type <code>insmod 8192cu.ko</code> (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created
+
:** bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet)
# type <code>ifconfig wlanX up</code> (where X is a number) to turn on the device; now the wifi can be configured and used normally
+
:** bit2: 0=set motors speed; 1=set motors steps (position)
The following figures show how the device is mounted on the extension: on the left the WiFi dongle is connected to the USB HOST connector (pay attention to the position on the connector), on the right the WiFi dongle is connected to the USB OTG (this is needed when using an [http://www.gctronic.com/doc/index.php/Omnivision_Module_V2 omnivsion extension]):<br/>
+
:*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)
<span class="plainlinks">[http://www.gctronic.com/doc/images/Gumstix-nano-wifi.jpg <img width=400 src="http://www.gctronic.com/doc/images/Gumstix-nano-wifi.jpg">]</span>
+
:*LEDs: 0=off; 1=on
<span class="plainlinks">[http://www.gctronic.com/doc/images/edimax-otg.jpg <img width=350 src="http://www.gctronic.com/doc/images/edimax-otg-small.jpg">]</span> <br/>
+
:** 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
  
==Consumption==
+
For example to receive the camera image (stream) the following steps need to be followed:<br/>
The consumption of the robot and extension is 300 mA; with the Zyxel wifi dongle inserted (standby) the consumption goes up to 400 mA; when the wifi dongle becomes active, the consumption reaches 700 mA. If the wifi isn't used it can be turned off completely using the usb scripts [http://www.gctronic.com/doc/index.php/Overo_Extension#USB_ports http://www.gctronic.com/doc/index.php/Overo_Extension#USB_ports].
+
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
  
Two different tests were performed to provide an estimation of the duration of the battery:
+
=Webots=
# e-puck and gumstix active (gumstix sends commands via serial to robot; movement every 3s lasting 1s at 30% of maximum speed): '''3h and 30 minutes'''
+
TBD
# e-puck, gumstix and wifi active (same as above, moreover wifi active all the time with continuous ping): '''1h and 25 minutes'''
 
  
==External power==
+
=ROS=
In the package you'll find also an external power adapter that will be useful during development of your applications. As power supply you could use the one of the e-puck battery charger. The following figure shows the power supply cable, the external power cable and the extension.<br/>
+
This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth or WiFi to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema:<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/External-power.jpg <img width=400 src="http://www.gctronic.com/doc/images/External-power.jpg">]</span> <br/>
+
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck2-ros-schema.png <img width=450 src="http://www.gctronic.com/doc/images/epuck2-ros-schema-small.png">]</span>
You need to simply attach the power supply in one side, and the other side of the external power cable on top of the extension (near the USB plug). Once the cable is connected a green led should turn on indicating that the extension is running. <br/>
+
''<font size="2">Click to enlarge</font>''<br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/External-power-attached.jpg <img width=400 src="http://www.gctronic.com/doc/images/External-power-attached.jpg">]</span> <br/>
 
The external power cable could also be plugged in when the extension is mounted on the e-puck, but '''<font style="color:red"> pay attention to not turn on the robot when the external cable supplies the energy, otherwise there could be serious damages of the devices and the battery</font>'''.
 
  
==3.3V and 5V source==
+
First of all you need to install and configure ROS, refer to [http://wiki.ros.org/Distributions http://wiki.ros.org/Distributions] for more informations. <font style="color:red"> This tutorial is based on ROS Kinetic</font>. The same instructions are working with ROS Noetic, beware to use <code>noetic</code> instead of <code>kinetic</code> when installing the packages.
The 3.3 V comes from the e-puck robot and the 5V comes from the gumstix extension. The gumstix extension can be used alone (without the robot attached to it) but some things are related to the 3.3 V thus without the robot connected they will not work; an example are the RGB leds of the omnivion module, that need the robot to be connected to the extension in order to be used.
 
  
=Software=
+
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.
==E-puck firmware==
 
<!-- The firmware that has to be uploaded on the e-puck when working with the extension for Gumstix Overo COM can be downloaded from [http://projects.gctronic.com/E-Puck/DemoGCtronic-gumstix/DemoGCtronic-gumstix.hex hex]; the related MPLAB project can also be downloaded from [http://projects.gctronic.com/E-Puck/DemoGCtronic-gumstix/DemoGCtronic-gumstix.zip MPLAB project]. -->
 
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 in this firmware a new version of the ''advanced sercom'' is included (selector position 10) in which the bluetooth communication is replaced by the serial line communication, running at 230400 between robot and gumstix. Moreover the I2C is disabled temporary from the dsPIC side (the dsPIC cannot communicate through I2C) in order to avoid conflicts. As a last note, the body led and front led aren't anymore usable with the extension due to the two extra long range proximity sensors and for power saving purposes the motors are configured to the minimum energy consumption during movement.<br/>
 
The values of the two extra proximity sensors can be retrieved with the command ''N'' in the ''advanced sercom'' (selector position 10); the last two values returned by the command refer to these proximity sensors (the others values refer to the proximity sensors mounted on the e-puck as usual).
 
  
===Project building===
+
==Initial configuration==
Refer to section [http://www.gctronic.com/doc/index.php/E-Puck#Project_building Project building] for information on how to build the project for the e-puck firmware.
+
The following steps need to be done only once, after installing ROS:
 +
:1. If not already done, create a catkin workspace, refer to [http://wiki.ros.org/catkin/Tutorials/create_a_workspace http://wiki.ros.org/catkin/Tutorials/create_a_workspace]. Basically you need to issue the following commands: 
 +
<pre>  mkdir -p ~/catkin_ws/src
 +
  cd ~/catkin_ws/src
 +
  catkin_init_workspace
 +
  cd ~/catkin_ws/
 +
  catkin_make
 +
  source devel/setup.bash </pre>
 +
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
 +
:3. Move to <code>~/catkin_ws/src</code> and clone the ROS e-puck2 driver repo:
 +
:* if you are working with Python (only Bluetooth communication supported at the moment): <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>
 +
:* if you are working with cpp:
 +
:** Bluetooth communication: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>
 +
:** WiFi communication: <code>git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp</code>
 +
:4. Install the dependencies:
 +
:* ROS:
 +
:** [http://wiki.ros.org/gmapping gmapping (SLAM)] package: <code>sudo apt-get install ros-kinetic-gmapping</code>
 +
:** [http://wiki.ros.org/rviz_imu_plugin Rviz IMU plugin] package: <code>sudo apt-get install ros-kinetic-rviz-imu-plugin</code>
 +
:* Python:
 +
:** The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies:
 +
:*** install the Python setup tools: <code>sudo apt-get install python-setuptools</code>
 +
:*** install the Python image library: <code>sudo apt-get install python-imaging</code>
 +
:*** install pybluez version 0.22: <code>sudo pip install pybluez==0.22</code>
 +
:**** install pybluez dependencies: <code>sudo apt-get install libbluetooth-dev</code>
 +
:*** install OpenCV: <code>sudo apt-get install python3-opencv</code>
 +
:* cpp:
 +
:** install the library used to communicate with Bluetooth: <code>sudo apt-get install libbluetooth-dev</code>
 +
:** install OpenCV: <code>sudo apt-get install libopencv-dev</code>
 +
:*** if you are working with OpenCV 4, then you need to change the header include from <code>#include <opencv/cv.h></code> to <code>#include <opencv2/opencv.hpp></code>
 +
:5. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
 +
:6. Program the e-puck2 robot with the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware factory firmware] and put the selector in position 3 for Bluetooth communication or in position 15 for WiFi Communication
 +
:7. Program the radio module with the correct firmware:
 +
:* Bluetooth communication: use the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_2 factory firmware]
 +
:* WiFi communication: use the [https://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_firmware WiFi firmware]
  
==Cross compilation==
+
==Running the Python ROS node==
If you want to develop some applications that will run on the gumstix you need to firstly download the toolchain.
+
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/>
  
If you're using Ubuntu you can simply type <code>sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi</code> to install the required toolchain (have a look at [http://www.gumstix.org/basic-cross-compilation.html http://www.gumstix.org/basic-cross-compilation.html] and [http://wiki.gumstix.org/index.php?title=Toolchain http://wiki.gumstix.org/index.php?title=Toolchain] for more information).
+
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.
  
Alternatively when you need to handle external dependencies is better using the toolchain integrated in OpenEmbedded (${OVEROTOP}/tmp/cross or ${OVEROTOP}/tmp/sysroots/i686-linux/usr/armv7a/bin/ with recent version) if you have it in your system. For more information refers to the [http://wiki.gumstix.org/index.php?title=Category:How_to_-_OpenEmbedded gumstix wiki].<br/>
+
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
  
For other linux systems you can find a toolchain in the following link [http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/ http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/] (30 days trial); this toolchain is useful for small programs:
+
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/>
# download the Lite Edition, you'll have a file named something like ''arm-2009q3-67-arm-none-linux-gnueabi.bin''
+
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/>
# open a terminal, go to the directory of the file, type ''chmod +x arm-2009q3-67-arm-none-linux-gnueabi.bin'', after execute the file ''./arm-2009q3-67-arm-none-linux-gnueabi.bin'' to start the installation
+
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
# follow the installation steps; you have to choose where to install the toolchain, this is the path you will specify in the makefile
 
  
Once a toolchain is installed in the system the process will be simply something like this:
+
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.
# develop your application as you do normally in your developing machine
 
# cross-compile in your developing machine using the tools previously downloaded
 
# copy the executable in the extension's micro SD and run it
 
You can download the [http://projects.gctronic.com/Gumstix/helloworld.zip hello world example] containing a makefile in which you have to specify the path to the toolchain you previously installed in order to build the program; you can use it for others programs.<br/>
 
Refer to section [http://www.gctronic.com/doc/index.php/Overo_Extension#Demos http://www.gctronic.com/doc/index.php/Overo_Extension#Demos] for some application examples.
 
  
Of course you can also install the compiler directly on the embedded system and build the applications from it, but the process will take longer due to limited computational power compared to a developing machine.
+
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.
  
===External dependencies===
+
The following figures show all the topics published by the e-puck2 driver node (left) and the <code>rviz</code> interface (right): <br/>
Some applications may require external libraries not contained within the standard toolchain package. For instance if your application depends on ''libjpeg'' then you need to tell the cross-compiler where to look to find this library (compiled for the target machine) otherwise your application will not be compiled. If you have OpenEmbedded installed in your system you could simply bitbake the external dependencies (in our example ''bitbake jpeg'') and then compile your application. Instead if you rely on the CodeSourcery toolchain you need to follow these steps:
+
<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>
# download the sources of the library
+
''<font size="2">Click to enlarge</font>''
# cross-compile the library
+
<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>
# install the library (and include files) in the right places
+
''<font size="2">Click to enlarge</font>''<br/>
# compile your application
 
  
==Ground sensor==
+
==Running the cpp ROS node==
It's possible to use contemporaneously both the e-puck extension for gumstix overo and the ground sensor; in this case the camera and the ground sensor will share the same I2C bus and like the camera, also the ground sensor will not be anymore reachable from the e-puck side, but only from the overo side. <br/>
+
There is a small difference at the moment between the Bluetooth and WiFi versions of the ROS node: the WiFi ROS node supports also the publication of the magnetometer data.
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo, thus we need to change the bus speed to 100 KHz in order to communicate with the ground sensor module; the simplest way is to set a kernel parameter in u-boot:
+
===Bluetooth===
# enter u-boot by pressing any key at boot start
+
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/>
# type the command <code>setenv i2cspeed 3,100</code>; this init the I2C bus 3 to 100 KHz
+
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/>
# type the command <code>setenv mmcargs setenv bootargs console=${console} i2c_bus=${i2cspeed} ${optargs} mpurate=${mpurate} vram=${vram} omapfb.mode=dvi:${dvimode} omapdss.def_disp=${defaultdisplay} root=${mmcroot} rootfstype=${mmcrootfstype} </code>; basically we pass an additional parameter to the kernel that is the <code>i2c_bus=${i2cspeed}</code>
 
# type the command <code>saveenv</code> to save the environment changes
 
# type <code>boot</code> to start booting
 
Pay attention that all the peripherals connected to the bus will now work at 100 KHz, thus also the e-puck camera and the LSM330 (accelerometer + gyroscope) present with e-puck HwRev 1.3.<br/>
 
If you want to set back the bus speed to 400 KHz you need to follow steps 2-4, by setting the <code>i2cspeed</code> u-boot environment variable with <code>setenv i2cspeed 3,400</code>.<br/>
 
Communicating with the ground sensor is as easy as open a device and reading from it; a source code example can be found in the following link [http://projects.gctronic.com/Gumstix/groundsensor.c http://projects.gctronic.com/Gumstix/groundsensor.c]. You will find this application example in the <code>/home/root/demos/gumstix-common</code> directory; start it by executing <code>./i2c_groundsensors</code> and the sensors values will be displayed in the terminal.<br/>
 
Make sure that you have installed the last system update otherwise you'll encounter some problems.<br/>
 
You can find more information about the I2C and gumstix in the following links:
 
* [https://wiki.gumstix.com/index.php/Category:How_to_-_i2c https://wiki.gumstix.com/index.php/Category:How_to_-_i2c]
 
<!--
 
===Examples===
 
====Images transfer (serial line)====
 
The application "transfer_images" running on the Gumstix Overo COM performs a request of a variable number of images to the e-puck and transfers them over either TCP or UDP to a server machine (a connection must be configured on both sides before running this program). For more information on the usage refers to the help (-h option). This demo works with the ''advanced sercom'' protocol, so the new e-puck firmware must be already charged and selector 10 must be chosen.<br/>
 
In order to compile the application the Makefile must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to [http://focus.ti.com/docs/prod/folders/print/omap3503.html http://focus.ti.com/docs/prod/folders/print/omap3503.html]).
 
[[image:ImageReceiver.jpeg|thumb|Image receiver application.]]
 
The application "ImageReceiver" running on the server machine is used to visualize the images received from the e-puck. <br/>
 
The usage is very simple: the server listening port and the protocol must be first selected and then the button "Connect" clicked; at this moment the application is waiting images.
 
The application is a Qt project, so the compilation may be handled easily with [http://www.qtsoftware.com/products/developer-tools Qt Creator]; alternatively [http://doc.trolltech.com/4.2/qmake-manual.html qmake] can be used.
 
  
It's worth to note that the server application must be started before sending images, thus the "ImageReceiver" application must be first executed on the PC side, and the "transfer_images" application must be then executed on the Gumstix Overo side.
+
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.
  
[http://www.gctronic.com/doc/images/Image_transfer.tar Download Transfer images (Linux)] <br/>
+
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
[http://www.gctronic.com/doc/images/Image_receiver.tar Download Image receiver (Linux)]
 
  
====Images grabbing (serial line)====
+
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/>
This application, running on the Overo COM, requests to the e-puck a customizable number of images that can be parametrized by size, zoom factor, type (gray-scale or color) and window position and save them as bmp; for more information on the usage refers to the help (-h option). This demo works with the ''advanced sercom'' protocol, so the new e-puck firmware must be already charged and selector 10 must be chosen.<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/>
In order to compile the application the Makefile must be modified specifying the path to the cross-compiler like with the "Images transfer" application.
+
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
  
[http://www.gctronic.com/doc/images/GrabCustomImages.tar Download Grab custom images (Linux)]
+
If all is going well the robot will be ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.
  
-->
+
The launch script is configured also to run the [http://wiki.ros.org/gmapping gmapping (SLAM)] node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points.
 +
===WiFi===
 +
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp</code>. <br/>
 +
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
  
==OpenCV==
+
Before actually starting the e-puck2 node you need to connect the e-puck2 robot to your WiFi network, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi Connecting to the WiFi].<br/>
The Open Computer Vision Library has more than 500 algorithms, documentation and sample code for real time computer vision; you can download it from [http://sourceforge.net/projects/opencvlibrary/ http://sourceforge.net/projects/opencvlibrary/], and find information about it from the official wiki [http://docs.opencv.org/index.html http://docs.opencv.org/index.html]. <br/>
 
The released system comes with OpenCV version 2.0.0 pre-installed and a demo that shows an example of what can be performed with this library. The demo let the robot follow a black filled circle placed in front of it; if the circle is moved right or left the robot turns consequently. The following figure shows an example of the circle detected by the robot:<br/>
 
<span class="plainlinks">[http://www.gctronic.com/doc/images/circle-detection.jpg <img width=200 src="http://www.gctronic.com/doc/images/circle-detection.jpg">]</span> <br/>
 
In order to start the demo follows these steps:
 
# turn on the robot with the gumstix extension and login as ''root'' with password ''root''
 
# go to the directory ''/home/root/demos/gumstix-common'' and execute ''./v4l2grab-opencv -o image.jpg''
 
# the demo should return the number of circles detected and save a resulting image showing the circles detected if any
 
Alternatively you can use the following script, that launches the demo and send it through serial (using zmodem) iteratively:
 
<pre>
 
#!/bin/bash
 
while true; do
 
./v4l2grab-opencv -o image.jpg -q 50
 
lsz img1.jpg
 
done
 
</pre>
 
 
 
The source code can be downloaded from the following link [http://projects.gctronic.com/Gumstix/v4l2grab-opencv-rev15.zip v4l2grab-opencv.zip].
 
 
 
<!--
 
====Opencv-linux 1.1pre1 version====
 
OpenCV can be easily installed on the Gumstix Overo COM, following these steps:
 
 
 
:1. [http://sourceforge.net/projects/opencvlibrary/ Donwload] OpenCV.
 
:2. Extract the content (tar -xzvf opencv-1.1pre1.tar.gz) of the file in a directory, let it be in "opencv".
 
:3. Open a terminal, and access the directory (cd path/to/opencv).
 
:4. Configure the environment in order to use the cross-compilation tools (if you installed OpenEmbedded, you can find these tools in /tmp/cross/bin/ within the OE main directory): <br/>
 
<pre>
 
export CC=/path_to_OE_home_dir/tmp/cross/bin/arm-angstrom-linux-gnueabi-gcc
 
export CXX=/path_to_OE_home_dir/tmp/cross/bin/arm-angstrom-linux-gnueabi-g++
 
</pre>
 
:5. Now configure OpenCV with the following command; in this configuration several packages are disabled (e.g. gtk) because useless when using console mode to work with the gumstix. Another important option is ''prefix'', which tell where the OpenCV library will be installed. For more information on the configuration refers to the help (--help).<br/>
 
<pre>
 
./configure --host=arm-linux --build=i686-linux --prefix=/install_dir_path/ --without-gthread --without-gtk --without-python --disable-apps
 
</pre>
 
:6. Type ''make'' and then ''make install''; the directory specified with the ''prefix'' options will contain the compiled library.
 
:7. Copy the content of this directory to the gumstix, for example in an external SD card.
 
:8. Before trying to execute an OpenCV based application, you must specify to the system where to find the OpenCV library; you can do this by typing the following command; alternatively it's possible to install directly the library in the /usr/lib directory in the system.
 
<pre>
 
export LD_LIBRARY_PATH=/path_to_OpenCV/lib
 
</pre>
 
 
 
A detailed tutorial on the OpenCV setup for Gumstix can be found in the following link [http://danielbaggio.blogspot.com/2009/01/compiling-opencv-for-gumstix.html Compiling OpenCV for Gumstix].
 
 
 
====Later versions (> 1.1)====
 
It's possible to have the OpenCV framework available on your system in two ways:
 
:1. if OpenEmbedded and bitbake are already configured in the system you can simply type ''bitbake opencv'' and then install the libraries on the micro-sd of the overo
 
:2. if you have internet access from the overo you can use the package manager by typing ''opkg install opencv'' (it takes a while to complete)
 
-->
 
 
 
<!--
 
Later versions of OpenCV (current is 2.0.0) rely on [http://www.cmake.org/ CMake], the cross-platform, open-source build system.You can install it in Ubuntu by typing ''sudo apt-get install cmake''; you can also install a nice front-end for CMake by typing ''sudo apt-get install cmake-gui''; in this way the configuration process of OpenCV becomes easier.<br>
 
Follow the steps afterwards to get the newer version of OpenCV compiled for the gumstix:
 
:1. [http://sourceforge.net/projects/opencvlibrary/ Donwload] OpenCV.
 
:2. Extract the content (tar -xzvf opencv-2.0.0.tar.gz) of the file in a directory, let it be in "opencv".
 
:3. Start the CMake interface, by typing in a terminal ''cmake-gui''.
 
:4. ...to be finished!
 
-->
 
 
 
==Accelerometer and gyroscope (e-puck HWRev 1.3)==
 
When the e-puck extension for gumstix overo is mounted on the e-puck hardware revision 1.3 the same I2C bus is shared by all the devices (camera, accelerometer, gyroscope) and the overo; since there is only one master (the overo) these devices will not be anymore reachable from the e-puck side. <br/>
 
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo and this is fine to work with the accelerometer and gyroscope. <br/>
 
Communicating with the accelerometer and gyroscope is as easy as open a device and reading from it; a source code example can be found in the following link [http://projects.gctronic.com/Gumstix/i2c_lsm330.c i2c_lsm330.c]. You will find this application example in the <code>/home/root/demos/gumstix-common</code> directory; start it by executing <code>./i2c_lsm330</code>, type <code>0</code> to get the accelerometer values or <code>1</code> to get the gyroscope values printed on the terminal.<br/>
 
The values of the accelerometer and gyroscope read from the gumstix through the I2C are 16 bits (1g = 16384); beware that regarding the accelerometer values there is a mismatch between the values read from the gumstix through I2C and the values read from the [{{fullurl:Advanced sercom protocol}} advanced sercom protocol] through Bluetooth, the latter are converted in the firmware to maintain compatibility with older e-puck hardware revisions.<br/>
 
The orientation of the accelerometer for the values read from the gumstix through the I2C is also different from the one used in the e-puck firmware; the orientation is shown below, the x axis points forward, the y axis points left and the z axis points upward:<br/>
 
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck-acc-directions1.3.png <img width=150 src="http://www.gctronic.com/doc/images/epuck-acc-directions1.3.png">]</span><br/>
 
===Python===
 
An example in python is available from the following link [http://projects.gctronic.com/Gumstix/i2c_lsm330.py i2c_lsm330.py]. In order to run the script, some additional dependencies need to be installed in the system, follow these steps:
 
# configure the network in order to have internet access
 
# update the package manager repos:
 
##<code>echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/base/' > /etc/opkg/base-feed.conf</code>
 
##<code>echo 'src/gz python http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/python/' > /etc/opkg/python-feed.conf</code>
 
# add <code>arch armv7a-vfp-neon 45</code> to the file <code>/etc/opkg/arch.conf</code>
 
# <code>opkg update</code>
 
# <code>opkg -force-overwrite install python-smbus</code>
 
# optionally you can also remove some warnings related to the update by running the following script [http://projects.gctronic.com/omnicam/remove-warnings.sh remove-warnings.sh]
 
Once the system is configured you can start the script by executing <code>python i2c_lsm330.py</code>, type <code>0</code> to get the accelerometer values or <code>1</code> to get the gyroscope values printed on the terminal.<br/>
 
  
==ROS==
+
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>.
We tested ROS on the gumstix extension with the Yocto system. Follow these steps to get ROS running on the e-puck extension:
 
:1. prepare a micro sd following the instructions from [http://gumstix.org/create-a-bootable-microsd-card.html http://gumstix.org/create-a-bootable-microsd-card.html]
 
:2. download the file system and fat from the following links: [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-FAT.tar.gz yocto-ros-3.5.7-FAT.tar.gz], [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-rootfs.tar.gz yocto-ros-3.5.7-rootfs.tar.gz]
 
:3. login with user=root and empty password
 
:4. issue the following commands to enable the WiFi dongle:
 
::<code>echo host > /sys/bus/platform/devices/musb-hdrc/mode</code>
 
::<code>echo -n 1 > /sys/bus/usb/devices/2-1/bConfigurationValue</code>
 
:5. follow the instructions from [https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#the-fun-part https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#the-fun-part] to run a demo
 
<!--
 
We tested ROS on the gumstix extension with the Yocto pre-built system. Follow these steps to get ROS running on the e-puck extension:
 
:1. download the Yocto pre-built image from [https://www.gumstix.com/software/software-downloads/ https://www.gumstix.com/software/software-downloads/] (Overo Series COMs)
 
:2. prepare a micro sd following the instructions from [http://gumstix.org/create-a-bootable-microsd-card.html http://gumstix.org/create-a-bootable-microsd-card.html]
 
:3. configure the network settings in order to get internet access (at the moment you need to plug the WiFi dongle on the USB host)
 
:4. follow the instructions from [https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#one-time-on-system-setup https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#one-time-on-system-setup] (skip step 1)
 
If you prefer you can directly download the file system and fat from the following links: [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-FAT.tar.gz yocto-ros-3.5.7-FAT.tar.gz], [http://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-rootfs.tar.gz yocto-ros-3.5.7-rootfs.tar.gz].
 
-->
 
  
==Python==
+
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/>
In order to install python 2.6 on the e-puck extension for Gumstix follow these steps:
+
Open a terminal and issue the following command: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20'</code>.<br/>
# download the package [http://projects.gctronic.com/Gumstix/python-gumstix.tar.gz python-gumstix.tar.gz]
+
<tt>192.168.1.20</tt> is the e-puck2 IP address that need to be changed accordingly to your robot.
# extract the package: <code>tar -zxvf python-gumstix.tar.gz</code>
 
# remove the micro sd from the robot and connect it to your computer; two partitions will be opened, one called <code>FAT</code> and the other called <code>overo</code> containing the file system (the partitions name could be a little different)
 
# copy the content of the decompressed file to the same position in the <code>overo</code> partition:
 
##<code>sudo cp -R /python-gumstix/usr/lib/* /overo/usr/lib</code>
 
##<code>sudo cp /python-gumstix/usr/bin/* /overo/usr/bin</code>
 
  
Alternatively if you have access to internet you can use the package manager:
+
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.
# <code>opkg install python</code>
 
# <code>opkg install python-modules</code>
 
# <code>opkg install python-pyserial</code>
 
  
In order to test your python installation you can download the following script [http://projects.gctronic.com/Gumstix/printhelp.py printhelp.py]; execute it by typing <code>python printhelp.py</code>.
+
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.
This is a minimal example of serial communication in python that let the gumstix communicate with the robot; basically it opens a serial connection with the robot and ask the available commands that you can use to get sensors data and change actuators state.<br/>
 
Another example is available here [http://projects.gctronic.com/Gumstix/getprox.py getprox.py]; in this script the values of the proximities are requested to the robot and printed to the console. The data are requested in binary format, for more information about the communication protocol refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Advanced_sercom advanced sercom].
 
==e-puck2==
 
When the gumstix extension is mounted on the e-puck2 robot, the same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the overo; since there is only one master (the overo), these devices will not be anymore reachable directly from the e-puck2 main microcontroller that will act instead as I2C slave.<br/>
 
It's worth notice that with e-puck2, the I2C bus is used also for the communication between the robot and the gumstix (to receive sensors and set the actuators); with e-puck1.x a serial channel was used instead for the communication between the robot and the gumstix.
 
  
===Firmware===
+
The refresh rate of the topics is about 11 Hz when the camera image is enabled (see [http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camon.pdf e-puck2_topics_wifi_refresh_camon.pdf]) and about 50 Hz when the camera image is disabled (see [http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camoff.pdf e-puck2_topics_wifi_refresh_camoff.pdf]). The same graphs can be created using the command <code>rosrun tf view_frames</code>.
A special firmware must be uploaded to the e-puck2 robot in order to let the main processor act as I2C slave.<br/>
 
In this firmware the main processor receive commands from the gumstix extension to actuate the motors and leds and give back the sensors values (proximity, microphones, selector, motors steps, tv remote) to the gumstix. When using this firmware the body led and front led aren't usable; the two extra long range proximity sensors mounted on the gumstix extension are also not available with e-puck2.<br/>
 
The selector on the robot must be in position 10. Be sure that the selector on the robot is in position 10, because the selector on the gumstix extension is not connected to the e-puck2 robot.<br/>
 
  
The pre-compiled firmware can be downloaded from [http://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_gumstix_b5bb1dc_13.12.18.elf  e-puck2_main-processor_gumstix.elf].<br/>
+
The following figure shows all the topics published by the e-puck2 WiFi ROS node. The same graph can be created using the command <code>rqt_graph</code>. <br/>
If you want to have a look a the source code, you can clone the git repository by issueing the command <code>git clone -b gumstix --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code>.<br/>
+
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi.png">]</span>
 +
''<font size="2">Click to enlarge</font>''
  
An example showing how to exchange data between the robot and the gumstix extension is called <code>i2c_e-puck2</code> and can be found in the directory <code>/home/root/demos/e-puck2/</code>.<br/>
+
==Move the robot==
Simply run the program by issueing <code>./i2c_e-puck2</code>; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz. The code is available from [http://projects.gctronic.com/epuck2/gumstix/i2c_e-puck2.zip  i2c_e-puck2.zip].
+
You have some options to move the robot.<br/>
  
====Packet format====
+
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/>
Gumstix to robot packet format, 19 bytes payload (the number in the parenthesis expresses the bytes for each field):
 
{| border="1"
 
| Left speed (2)
 
| Right speed (2)
 
| Speaker (1)
 
| LED1, LED3, LED5, LED7 (1)
 
| LED2 RGB (3)
 
| LED4 RGB (3)
 
| LED6 RGB (3)
 
| LED8 RGB (3)
 
| Additional (1) 
 
|}
 
* Left, right speed: [-2000 ... 2000]
 
* Speaker id: [0, 1, 2]
 
* LEDs on/off flag: bit0 for LED1, bit1 for LED3, bit2 for LED5, bit3 for LED7
 
* RGB LEDs: [0 (off) ... 100 (max)]
 
* Additional byte for future usage
 
  
Robot to gumstix packet format, 30 bytes payload (the number in the parenthesis expresses the bytes for each field):
+
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/>
{| border="1"
+
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/>
| 8 x Prox (16)
 
| 4 x Mic (8)
 
| Selector (1)
 
| Left steps (2)
 
| Right steps (2)
 
| TV remote (1) 
 
|}
 
  
===I2C devices===
+
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/>
====Ground sensor====
+
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.
Refer to section [http://www.gctronic.com/doc/index.php?title=Overo_Extension#Ground_sensor Ground_sensor].
 
  
====IMU====
+
==Control the RGB LEDs==
An example showing how to read data from the IMU is called <code>i2c_mpu9250</code> and can be found in the directory <code>/home/root/demos/e-puck2/</code>.<br/>
+
The general command to change the RGB LEDs colors is the following:<br/>
Simply run the program by issueing <code>./i2c_mpu9250</code> and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal. The code is available from [http://projects.gctronic.com/epuck2/gumstix/i2c_mpu9250.zip  i2c_mpu9250.zip].
+
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"</code><br/>
 
+
The values range is from 0 (off) to 100 (completely on). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the RGB LEDs.<br/>
====Distance sensor====
 
 
 
=Configuration=
 
==Graphic mode==
 
The resolution of the monitor can be modified in the u-boot command line, that can be entered at booting. In the u-boot command line type:
 
<pre>
 
setenv dvimode "1280x720MR-16@60"
 
saveenv
 
boot
 
</pre>
 
Now the configuration is saved in the flash; if your monitor doesn't support the current resolution, repeat the procedure with a different configuration (change the resolution numbers).
 
  
Note that the DVI Controller ([http://projects.gctronic.com/Gumstix/tfp410.pdf TFP410]) mounted on Summit and Tobi supports resolutions from VGA (640x480) to UXGA (1600x1200).
+
For instance to set all the RGB LEDs to red, issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"</code><br/>
  
Useful files to look at:
+
To turn off all the RGB LEDs issue the following command:<br/>
* linux_source_home/drivers/video/modedb.c: explains what's the mean of the dvimode names
+
<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>
* linux_source_home/Documentation/fb/viafb.modes: list of available modes usable with the ''fbset'' tool
 
  
==GPIO - pins mode==
+
==Control the LEDs==
There are three different ways to read GPIO lines:  
+
The general command to change the LEDs state is the following:<br/>
:1. Kernel space: GPIO lines handled through an API
+
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7, body LED, front LED]}"</code><br/>
:2. User space:  
+
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/>
::2.1. standard filesystem commands like ''cat'' and ''echo'' (static configuration)
 
::2.2 direct physical memory access using ''devmem2'' or with a C application (dynamic configuration)
 
  
Afterward will be explained how to handle the GPIO lines on the Gumstix Overo COM in all different methods; information about this topic were found from various sites, but especially from the [http://sourceforge.net/p/gumstix/mailman/ mailing list]. Moreover for a general howto on GPIO refers to the linux documentation [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"].
+
For instance to turn on LED1, LED5, body LED and front LED, issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1,0,1,0,1,1]}"</code><br/>
  
===Kernel space===
+
To toggle the state of all the LEDs issue the following command:<br/>
 +
<code>rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [2,2,2,2,2,2]}"</code>
  
===User space===
+
==Visualize the camera image==
====Static configuration====
+
By default the camera is disabled to avoid communication delays. In order to enable it and visualize the image through ROS you need to pass an additional parameter <code>cam_en</code> to the launch script as follows:<br/>
Each of the microprocessor IO pins can be configured to work in different ways for different purposes; in case we desire a certain pin to be configured as a gpio line, we must modify the function assigned to that pin (mux configuration) in the U-Boot board configuration file, that for the Gumstix Overo COM is located at "U-BootSrc/board/overo/overo.h". <!-- you can have a look at it [http://www.sakoman.net/cgi-bin/gitweb.cgi?p=u-boot-omap3.git;a=blob;f=board/overo/overo.h;h=4c7ac27fa6818d4f474bc42330134fd0a5520a37;hb=HEAD here].--> <br/>
+
* Python: <code>roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'</code>
 +
* cpp:
 +
** Bluetooth: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'</code>
 +
** WiFi: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20' cam_en:='true'</code>
  
To know which modes are available for the pins consult the chapter ''7-System Control Module'' (more specifically ''7.4.4-Pad Functional Multiplexing and Configuration'') in the [http://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf OMAP35x TRM]. <br/>
+
Then with the Python ROS node you need to open another terminal and issue the command <code>rosrun image_view image_view image:=/camera</code> that will open a window with the e-puck2 camera image.<br/>
 +
With the cpp ROS node the image is visualized directly in the Rviz window (on the right).<br/>
  
Assume we want to have the possibility to switch on and off a led attached to the line gpio70; in order to accomplish this task, we need to follow these steps:
+
When using the Bluetooth ROS node, by default the image is greyscale and its size is 160x2, but you can change the image parameters in the launch script.<br/>
 +
Instead when using the WiFi node, the image is RGB565 and its size is fixed to 160x120 (you can't change it).
 +
==Multiple robots==
 +
There is a lunch script file designed to run up to 4 robots simultaneously, you can find it in <code>~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck2.launch</code>. Here is an example to run 2 robots:<br/>
 +
<code>roslaunch epuck_driver_cpp multi_epuck2.launch robot_addr0:='192.168.1.21' robot_addr1:='192.168.1.23'</code><br/>
 +
After issueing the command, rviz will be opened showing the values of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm.
  
:'''1.''' Modify the board configuration file "overo.h" specifying that the pin has to behave as a gpio line:
+
==Troubleshooting==
<pre>
+
===Robot state publisher===
MUX_VAL(CP(DSS_DATA0), (IDIS | PTU | DIS | M4)) /*DSS_DATA0 => GPIO70*/\
+
If you get an error similar to the following when you start a node with roslaunch:
</pre>
 
:*IDIS = input disable, namely output pin
 
:*PTU = pull type up, but could be also PTD (pull type down) because of the third parameter
 
:*DIS = disable pull type up/down
 
:*M4 = mode 4 (gpio)
 
:This give us a GPIO pin that is output and not pulled up or down.
 
:'''2.''' Build U-Boot and place the generated ''u-boot.bin'' image in the flash ([http://www.gumstix.org/how-to/70-writing-images-to-flash.html Writing images to onboard nand]) or in a micro sd card ([http://www.gumstix.org/create-a-bootable-microsd-card.html Creating a bootable microSD card])
 
:'''3.''' After login, we can see all the GPIO pins that have been exported by the kernel to userspace in the /sys/class/gpio/ directory. In order to access the gpio70 line, we should export it first, by typing:
 
<pre>
 
echo "70" > /sys/class/gpio/export
 
</pre>
 
:Now the following line is active /sys/class/gpio/gpio70.
 
:'''4.''' At this point we must configure the direction of the exported line and set a logical value (1 or 0) to that line, we can do that by typing:
 
 
<pre>
 
<pre>
echo "high" > /sys/class/gpio/gpio70/direction
+
ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x)
 
</pre>
 
</pre>
:This command set the pin in output and give it a value of 1.
+
Then you need to change the launch file from:
:'''5.''' Finally we can switch on or off the led, by setting the value of the gpio line:
 
 
<pre>
 
<pre>
echo "value" > /sys/class/gpio/gpio70/value
+
<node name="robot_state_publisher" pkg="robot_state_publisher" type="state_publisher" />
 
</pre>
 
</pre>
:Where value=1 means switch on, and value=0 means switch off.
+
To:
 
 
 
 
In order to automate the process of creating a gpio line accessible through "/sys/class/gpio/", we must modify the board configuration file in the kernel source; this file can be found in "KernelSrc/arch/arm/mach-omap2/board-overo.c" (and related definitions in "KernelSrc/arch/arm/plat-omap/include/mach/board-overo.h"). These files must contain instructions to initialize the gpio line that we want to export in user space and set their direction and initial value. <br/>
 
Consider the previous example in which we would like to control a led with the gpio70 pin; for this purpose the following instructions must be added in the board configuration file ''board.overo.c'' within the ''overo_init'' function:
 
<pre>
 
if ((gpio_request(70, "OVERO_GPIO_DD00") == 0) && (gpio_direction_output(70, 1) == 0)) {
 
gpio_export(70, 0);
 
gpio_set_value(70, 1); //not really needed, the initial output value is set with gpio_direction_output
 
} else {
 
printk(KERN_ERR "could not obtain gpio for OVERO_GPIO_DD00\n");
 
}
 
</pre>
 
After this modification we need to build the kernel and copy it to the flash or micro sd card, and after login we will have the /sys/class/gpio/gpio70 line automatically active.<br/>
 
For more information on the previous snippet code refers to [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"].
 
 
 
<!--
 
Read a value
 
Set a pin in input
 
-->
 
 
 
====Dynamic configuration====
 
If you aren't familiar with modifying and building U-Boot and kernel, you would probably choose to modify the pin configuration at runtime, without the need to touch any board configuration file. The only way to change the configuration of the pins is to access directly the physical memory of the microprocessor, in particular its configuration registers. <br/>
 
The utility [http://buildroot.uclibc.org/downloads/sources/devmem2.c devmem2] allows for easy reading and writing of the memory; after building and installing this utility on the Gumstix Overo COM, you are ready to change the ports functionality. Consider the previous example of the led on gpio70, to change the pin mode to gpio you must issue the following command:
 
 
<pre>
 
<pre>
devmem2 0x480020DC b 0x14
+
<node name="robot_state_publisher" pkg="robot_state_publisher" type="robot_state_publisher" />
 
</pre>
 
</pre>
''0x480020DC'' is the address of the register we want to write to and can be found observing the table 7-4 on chapter 7.4.4.3 of the [http://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf OMAP35x TRM]; ''b'' means we want to write a byte to that register and finally ''0x14'' is the value we want to write. The pin mode depends on the last three bits, in this case the mode is set to 4, namely the pin is a gpio. From now on we can follow steps from 3 to 5 of the previous chapter to switch on and off the led.
+
This is due to the fact that <code>state_publisher</code> was a deprecated alias for the node named <code>robot_state_publisher</code> (see [https://github.com/ros/robot_state_publisher/pull/87 https://github.com/ros/robot_state_publisher/pull/87]).
 
 
An example on modifying the pins configuration through the C programming language can be found in the following link [http://docwiki.gumstix.org/index.php?title=Sample_code/C/gpregs gpregs.c].
 
 
 
===Useful links/resources===
 
For more information on GPIO usage, have a look at the following links:
 
* [https://www.kernel.org/doc/Documentation/gpio/gpio.txt "KernelSrc/Documentation/gpio.txt"]
 
* [http://sourceforge.net/p/gumstix/mailman/ gumstix mailing list]
 
* [http://wiki.gumstix.org/index.php?title=GPIO http://wiki.gumstix.org/index.php?title=GPIO]
 
* [http://www.avrfreaks.net/wiki/index.php/Documentation:Linux/GPIO http://www.avrfreaks.net/wiki/index.php/Documentation:Linux/GPIO]
 
* [http://www.hy-research.com/omap3_pinmux.html http://www.hy-research.com/omap3_pinmux.html]
 
* [http://focus.ti.com/docs/prod/folders/print/omap3530.html http://focus.ti.com/docs/prod/folders/print/omap3530.html]
 
* [http://pixhawk.ethz.ch/omap/start http://pixhawk.ethz.ch/omap/start]
 
* [http://docs.blackfin.uclinux.org/doku.php?id=gpio http://docs.blackfin.uclinux.org/doku.php?id=gpio]
 
 
 
<!--
 
==U-Boot==
 
You can find the U-Boot source at "git://gitorious.org/u-boot-omap3/mainline.git" or "http://git.gitorious.org/u-boot-omap3/mainline.git".
 
-->
 
 
 
=Webots interface=
 
Nikola Velickovic developed an interface with the Webots simulator during his MSc Thesis in 2012.
 
His report is available [http://projects.gctronic.com/Gumstix/MScThesis_NikolaVelickovic_2012.tar.gz here].
 
His files are available [http://projects.gctronic.com/Gumstix/ThesisProjectFiles(30.12.2011).tar.gz here].
 
 
 
=FAQ=
 
'''1. Why the serial communication between Gumstix Overo COM and the robot doesn't work?''' <br/>
 
There could be three possible reasons for the communication problem:
 
* selector position incorrect: you need to be sure that the robot selector is in position 10 in order to start the right software on the robot side
 
* wrong device: the serial device is identified as /dev/ttyS0 in the linux machine, be sure to use it when you're using for example the sertest demo ("./sertest -p /dev/ttyS0 -b 230400")
 
* battery discharged: somebody could be deceived from the fact that the linux console is still usable, but if the orange led on the robot indicating the low battery level is turned on, then the robot will not be able anymore to respond, even if you are working on the linux console; either change or charge your battery and try again. <br/>
 
  
'''2. I am able to communicate with the robot through the serial line, but seems that I receive only garbage, why?''' <br/>
+
=Tracking=
Probably the baudrate isn't correct; with the robot selector in position 10 you need to configure the baudrate at 230400 (e.g "./sertest -p /dev/ttyS0 -b 230400"). <br/>
+
Some experiments are done with the [https://en.wikibooks.org/wiki/SwisTrack SwisTrack software] in order to be able to track the e-puck2 robots through a color marker placed on top of the robots.
 
 
'''3. Can I use bluetooth to connect to the robot? Can I use the [http://www.gctronic.com/doc/index.php/E-Puck#PC_interface monitor]?''' <br/>
 
Yes, you can connect to the robot with bluetooth and play with the monitor interface placing the selector in position 3. You'll experience some errors on the values displayed on the monitor due to the additional two long IR sensors that aren't considered when the interface was developed; moreover you will not be able to receive images from the robot. <br/>
 
 
 
'''4. Why I cannot connect to the robot through SSH? <br/>
 
* first of all be sure that the network is well configured (you can i.e. ping the robot sucessfully)
 
* check the SSH daemon is running typing: ''ps -ef | grep sshd''; if it is not running then setup the SSH daemon to run automatically at boot; for this purpose you can type ''update-rc.d sshd defaults 99''. This command will install the links to ''sshd'' into rc*.d dirs. See the man page for more informations.
 
* if the SSH server is running, but you get an error like "ssh: connect to host 192.168.1.2 port 22: Connection refused" when trying to connect, you can check whether a user and group sshd are created. If not, add the following entries in the system:
 
<pre>
 
/etc/group:sshd:*:27:
 
/etc/passwd:sshd:*:27:27:sshd privsep:/var/empty:/sbin/nologin
 
</pre>
 
  
'''5. How to auto-login and execute applications automatically at startup? <br/>
+
The requirements are the following:
Refers to the instructions explained here [https://wiki.gumstix.com/index.php/AutoLogin https://wiki.gumstix.com/index.php/AutoLogin].
+
* e-puck robots equipped with a color marker attached on top of the robot; beware that there should be a white border of about 1 cm to avoid wrong detection (marker merging). The colors marker were printed with a laser printer.
 +
* USB webcam with a resolution of at least 640x480. In our tests we used the <code>Trust SpotLight Pro</code>.
 +
* Windows OS: the SwisTrack pre-compiled package was built to run in Windows. Moreover the controller example depends on Windows libraries.<br/>''Anyway it's important to notice that SwisTrack is multiplatform and that the controller code can be ported to Linux.
 +
* An arena with uniform light conditions to make the detection more robust.
  
'''6. Are micro SDHC supported? <br/>
+
==Controller example==
Yes they are supported.
+
In this example we exploit the ''SwisTrack'' blobs detection feature in order to detect the color markers on top of the robots and then track these blob with a ''Nearest Neighbour tracking'' algorithm.<br/>
 +
The ''SwisTrack'' application get an image from the USB camera, then applies some conversions and thresholding before applying the blobs detection and finally tracks these blobs. All the data, like the blob's positions, are published to the network (TCP). <br/>
 +
The controller is a separate application that receives the data from SwisTrack through the network and opens a Bluetooth connection with each robot in order to remote control them. In the example, the informations received are printed in the terminal while moving the robots around (obstacles avoidance).<br/>
 +
The following schema shows the connections schema:<br/>
 +
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/tracking-schema.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/tracking-schema.png">]</span><br/>
  
=Videos=
 
<!--{{#ev:youtube|LQC9lvn9w8Q}}
 
Comments:
 
We have sent an e-puck on a mission to find our office plant.
 
It's actually a standard e-puck with a wifi connection to the laptop and the Gumstix's overo extention  with Linux OS, all runned by a powerful 0.6 Ghz processor. -->
 
  
{{#ev:youtube|a0Ozy-oRQIs}} <br/>
+
Follow these steps to run the example:
Comments: This e-puck is on an exploration, his camera sends continuous image to the computer with a wifi connection.
+
* program all the e-puck2 robots with the last factory firmware (see section [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Firmware update]) and put the selector in position 3
 +
* pair the robots with the computer, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth]
 +
* the controller example is based on the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#C.2B.2B_remote_library C++ remote library], so download it
 +
* download the controller example by issueing the following command: <code>git clone https://github.com/e-puck2/e-puck2_tracking_example</code>.<br/> When building the example, make sure that both the library and the example are in the same directory
 +
* download the pre-compiled [http://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip SwisTrack software] and extract it. The ''SwisTrack'' executable can be found in <code>SwisTrackEnvironment/SwisTrack - Release.exe</code>
 +
* prepare the arena: place the USB camera on the roof pointing towards the robots. Download the [http://projects.gctronic.com/epuck2/tracking/e-puck2-tracking-markers.pdf markers] and attach one of them on top of each robot.
 +
* download the [http://projects.gctronic.com/epuck2/tracking/swistrack-conf.zip configuration files package] for ''SwisTrack'' and extract it. Run the ''SwisTrack'' executable and open the configuration file called <code>epuck2.swistrack</code>. All the components to accomplish the tracking of '''2 robots''' should be loaded automatically.<br/> If needed you can tune the various components to improve the blobs detection in your environment or for tracking more robots.
 +
* Run the controller example: at the beginning you must enter the Bluetooth UART port numbers for the 2 robots. Then the robots will be moved slightly in order to identify which robot belong to which blob. Then the controller loop is started sending motion commands to the robots for doing obstacles avoidance and printing the data received from SwisTrack in the terminal.
  
=Useful links=
+
The following image shows the example running:<br/>
[http://www.gumstix.org/ http://www.gumstix.org/] <br/>
+
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/tracking-epuck2.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/tracking-epuck2_small.png">]</span><br/>
[http://wiki.gumstix.org/index.php?title=Main_Page http://wiki.gumstix.org/index.php?title=Main_Page] <br/>
 
[http://docwiki.gumstix.org/index.php/Gumstix_Buildroot_Support_Wiki http://docwiki.gumstix.org/index.php/Gumstix_Buildroot_Support_Wiki] <br/>
 
[http://docwiki.gumstix.org/index.php?title=U-Boot http://docwiki.gumstix.org/index.php?title=U-Boot] <br/>
 
[http://www.openembedded.org/wiki/Main_Page http://www.openembedded.org/wiki/Main_Page] <br/>
 
[http://www.e-puck.org/ http://www.e-puck.org/] <br/>
 
[http://www.jumpnowtek.com/ http://www.jumpnowtek.com/] <br/>
 

Revision as of 12:25, 18 November 2020

e-puck2 main wiki

1 Robot configuration

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

1.1 USB

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

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

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

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

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

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

1.2 Bluetooth

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

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

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

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

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

1.3 WiFi

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

Put the selector in position 15.

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

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

2 Connecting to the Bluetooth

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

  1. Channel 1, GDB: port to connect with GDB if the programmer is in mode 1 or 3 (refer to chapter Configuring the Programmer's settings for more information about these modes)
  2. Channel 2, UART: port to connect to the UART port of the main processor
  3. Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)

By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.
To make it visible, it is necessary to hold the USER button (also labeled "esp32" on the electronic board) while turning on the robot with the ON/OFF button.


Then it will be discoverable and you will be able to pair with it.
Note that a prompt could ask you to confirm that the number written on the screen is the same on the e-puck. just ignore this and accept. Otherwise if you are asked for a pin insert 0000.

2.1 Windows 7

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

2.2 Windows 10

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

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

2.3 Linux

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

2.4 Mac

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

2.5 Testing the Bluetooth connection

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

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

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

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

2.6 Python examples

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

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

2.6.1 Connecting to multiple robots

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

2.7 C++ remote library

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

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

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

3 Connecting to the WiFi

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

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

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

3.1 Network configuration

If there is no WiFi configuration saved in flash, then the robot will be in access point mode in order to let the user connect to it and setup a WiFi connection. The LED2 is red.

The access point SSID will be e-puck2_0XXXX where XXXX is the id of the robot; the password to connect to the access point is e-puck2robot.
You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address 192.168.1.1. The available networks are scanned automatically and listed in the browser page as shown in figure 1. Choose the WiFi signal you want the robot to establish a conection with from the web generated list, and enter the related password; if the password is correct you'll get a message saying that the connection is established as shown in figure 2. After pressing OK you will be redirected to the main page showing the network to which you're connected and the others available nearby as shown in figure 3. If you press on the connected network, then you can see your IP address as shown in figure 4; take note of the address since it will be needed later.

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


Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically.
Remember that you need to power cycle the robot at least once for the new configuration to be active.

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

In order to reset the current configuration you need to press the user button for 2 seconds (the LED2 red will turn on), then you need to power cycle the robot to enter access point mode.


3.2 Finding the IP address

Often the IP address assigned to the robot will remain the same when connecting to the same network, so if you took note of the IP address in section Network configuration you're ready to go to the next section.

Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to the port labeled Serial Monitor (see chapter Finding the USB serial ports used). Then power cycle the robot and the IP address will be shown in the terminal (together with others informations), as illustrated in the following figure:

3.3 Testing the WiFi connection

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

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

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

3.4 Web server

When the robot is in access point mode you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface.
You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address 192.168.1.1/monitor.html.

3.5 Python examples

3.5.1 Connecting to multiple robots

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

4 Communication protocol

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

4.1 Bluetooth and USB

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

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

see section Communication protocol: WiFi for the content description

0x09 Set all actuators

see section Communication protocol: WiFi for the content description

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

4.2 WiFi

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

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

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

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

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

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

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

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

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

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

5 Webots

TBD

6 ROS

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

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

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

6.1 Initial configuration

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

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

6.2 Running the Python ROS node

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

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

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

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

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

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

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

6.3 Running the cpp ROS node

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

6.3.1 Bluetooth

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

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

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

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

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

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

6.3.2 WiFi

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

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

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

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

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

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

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

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

6.4 Move the robot

You have some options to move the robot.

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

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

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

6.5 Control the RGB LEDs

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

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

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

6.6 Control the LEDs

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

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

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

6.7 Visualize the camera image

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

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

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

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

6.8 Multiple robots

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

6.9 Troubleshooting

6.9.1 Robot state publisher

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

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

Then you need to change the launch file from:

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

To:

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

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

7 Tracking

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

The requirements are the following:

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

7.1 Controller example

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


Follow these steps to run the example:

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

The following image shows the example running: