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

From GCtronic wiki
(Difference between pages)
Jump to: navigation, search
(Control the RGB LEDs)
 
(WiFi configuration)
 
Line 1: Line 1:
[{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
+
=Overview=
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck-overview.jpg <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck-overview-small.jpg">]</span><br/>
 +
Features:
 +
* Raspberry Pi zero W (rPi) connected to the robot via I2C
 +
* interface between the robot base camera and the rPi via USB
 +
* 1 digital microphone and 1 speaker
 +
* USB hub connected to the rPi with 2 free ports
 +
* uUSB cable to the rPi uart port. Also ok for charging
 +
* 2 chargers. 1 for the robot battery and 1 for the auxiliary battery on top of the extension
 +
* charging contact points in front for automatic charging. External docking station available
 +
* several extension options. 6 i2C channels, 2 ADC inputs
 +
* several LED to show the status of the rPi and the power/chargers
  
=Robot configuration=
+
=Getting started=
This section explains how to configure the robot based on the communication channel you will use for your developments, thus you need to read only one of the following sections, but it would be better if you spend a bit of time reading them all in order to have a full understanding of the available configurations.
+
This introductory section explains the minimal procedures needed to work with the Raspberry Pi Zero W mounted on the Pi-puck extension board and gives a general overview of the available basic demos and scripts shipped with the system flashed on the micro SD. More advanced demos are described in the following separate sections (e.g. ROS), but the steps documented here are fundamental, so be sure to fully understand them. <br/>
  
==USB==
+
The extension is mostly an interface between the e-puck robot and the Raspberry Pi, so you can exploit the computational power of a Linux machine to extend the robot capabilities.<br/>
The main microcontroller is initially programmed with a firmware that support USB communication.<br/>
 
  
If the main microcontroller isn't programmed with the factory firmware or if you want to be sure to have the last firmware on the robot, you need to program it with the last factory firmware by referring to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update].<br/>
+
In most cases, the Pi-puck extension will be attached to the robot, but it's interesting to note that it can be used also alone when the interaction with the robot isn't required.<br/>
 +
The following sections assume the full configuration (robot + extension), unless otherwise stated.
  
The radio module can be programmed with either the <code>Bluetooth</code> or the <code>WiFi</code> firmware, both are compatible with USB communication:
+
==Requirements==
* Bluetooth: refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
+
The robot must be programmed with a special firmware in order to communicate via I2C bus with the Raspberry Pi mounted on the Pi-puck extension. The same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the Raspberry Pi. Since the Raspberry Pi acts as I2C master, these devices will not be anymore reachable directly from the robot main microcontroller that will act instead as I2C slave.
* WiFi: download the [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)] and then refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 
  
When you want to interact with the robot from the computer you need to place the selector in position 8 to work with USB. <br/>
+
===e-puck1===
 +
The e-puck1 robot must be programmed with the following firmware [https://raw.githubusercontent.com/yorkrobotlab/pi-puck/master/e-puck1/pi-puck-e-puck1.hex pi-puck-e-puck1.hex].
  
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/>
+
===e-puck2===
 +
The e-puck2 robot must be programmed with the following firmware [http://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_extension_b346841_07.06.19.elf  e-puck2_main-processor_extension.elf (07.06.19)] and the selector must be placed in position 10.<br/>
  
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called <code>advanced sercom v2</code>, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB_2 Communication protocol: BT and USB] for detailed information about this protocol.<br/>
+
==Turn on/off the extension==
 +
To turn on the extension you need to press the <code>auxON</code> button as shown in the follwoing figure; this will turn on also the robot (if not already turned on). Similarly, if you turn on the robot then also the extension will turn on automatically.<br/>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck_btn_on_off.jpg <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck_btn_on_off-small.jpg">]</span><br/>
  
==Bluetooth==
+
To turn off the Pi-puck you need to press and hold the <code>auxON</code> button for 2 seconds; this will initiate the power down procedure.<br>
The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication.<br/>
 
  
If the main microcontroller and radio module aren't programmed with the factory firmware or if you want to be sure to have the last firmwares on the robot, you need to program them with the last factory firmwares:
+
Beware that by turning off the robot, the extension will not be turned off automatically if it is powered from another source like the micro usb cable or a secondary battery. You need to use its power off button to switch it off. Instead if there is no other power source, then by turning off the robot also the extension will be turned off (not cleanly).
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
 
* for the radio module, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 
  
When you want to interact with the robot from the computer you need to place the selector in position 3 if you want to work with Bluetooth. <br/>
+
==Console mode==
 +
The Pi-puck extension board comes with a pre-configured system ready to run without any additional configuration.<br/>
 +
In order to access the system from a PC in console mode, the following steps must be performed:<br/>
 +
1. connect a micro USB cable from the PC to the extension module. If needed, the drivers are available in the following link [https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers USB to UART bridge drivers]<br/>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck_usb.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck_usb-small.png">]</span><br/>
 +
2. execute a terminal program and configure the connection with 115200-8N1 (no flow control). The serial device is the one created when the extension is connected to the computer<br/>
 +
3. switch on the robot (the extension will turn on automatically); now the terminal should display the Raspberry Pi booting information. If the robot isn't present, then you can directly power on the extension board with the related button<br/>
 +
4. login with <code>user = pi</code>, <code>password = raspberry</code><br/>
  
Section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth] gives step by step instructions on how to accomplish your first Bluetooth connection with the robot.<br/>
+
==Battery charge==
 +
You can either charge the robot battery or the additional battery connected to the Pi-puck extension or both the batteries by simply plugging the micro USB cable.<br/>
 +
The following figure shows the connector for the additional battery.<br/>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck_battery.jpg <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck_battery-small.jpg">]</span><br/>
  
Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called <code>advanced sercom v2</code>, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB_2 Communication protocol: BT and USB] for detailed information about this protocol.<br/>
+
The robot can also autonomously charge itself if the charging wall is available. The Pi-puck extension includes two spring contacts on the front side that let the robot easily make contact with the charging wall and charge itself. The charging wall and the spring contacts are shown in the following figures:<br/>
 +
<span class="plainlinks">[https://www.gctronic.com/img2/shop/pipuck-charger-robot.jpg <img width=250 src="https://www.gctronic.com/img2/shop/pipuck-charger-robot-small.jpg">]</span>
 +
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck_contacts.jpg <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck_contacts-small.jpg">]</span><br/>
  
==WiFi==
+
=How to communicate with the robot and its sensors=
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):
+
==Communicate with the e-puck1==
* for the main microcontroller, refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update main microcontroller firmware update]
+
Refer to the repo [https://github.com/yorkrobotlab/pi-puck-e-puck1 https://github.com/yorkrobotlab/pi-puck-e-puck1].
* [http://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip radio module wifi firmware (25.02.19)], for information on how to update the firmware refer to section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 radio module firmware update]
 
Put the selector in position 15.<br/>
 
  
Section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi Connecting to the WiFi] gives step by step instructions on how to accomplish your first WiFi connection with the robot.<br/>
+
==Communicate with the e-puck2==
 +
An example showing how to exchange data between the robot and the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/e-puck2/</code>.<br/>
 +
You can build the program with the command <code>gcc e-puck2_test.c -o e-puck2_test</code>.<br/>
 +
Now you can run the program by issueing <code>./e-puck2_test</code>; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz.<br/>
 +
===Packet format===
 +
Extension to robot packet format, 20 bytes payload (the number in the parenthesis represents 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)
 +
| Settings (1)
 +
| Checksum (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)]
 +
* 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)
 +
* Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..18)
  
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/>
+
Robot to extension packet format, 47 bytes payload (the number in the parenthesis represents the bytes for each field):
 
+
{| border="1"
=Connecting to the Bluetooth=
+
| 8 x Prox (16)  
 
+
| 8 x Ambient (16)
The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer:
+
| 4 x Mic (8)  
# 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)
+
| Selector + button (1)  
# Channel 2, UART: port to connect to the UART port of the main processor
+
| Left steps (2)
# Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now)
+
| Right steps (2)
 
+
| TV remote (1)
By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer.<br>
+
| Checksum
'''To make it visible, it is necessary to hold the USER button (also labeled "esp32" on the electronic board) while turning on the robot with the ON/OFF button.'''<br>
+
|}
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-bt-pair.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-bt-pair-small.png">]</span><br/>
+
* Selector + button: selector values represented by 4 least significant bits (bit0, bit1, bit2, bit3); button state is in bit4 (1=pressed, 0=not pressed)
Then it will be discoverable and you will be able to pair with it.<br>
+
* Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..45)
Note that a prompt could ask you to confirm that the number written on the screen is the same on the e-puck. just ignore this and accept. Otherwise if you are asked for a pin insert 0000.
 
 
 
==Windows 7==
 
When you pair your computer with the e-puck2, 3 COM ports will be automatically created.
 
To see which COM port corresponds to which channel you need to open the properties of the paired e-puck2 robot from <code>Bluetooth devices</code>. Then the ports and related channels are listed in the <code>Services</code> tab, as shown in the following figure:<br/>
 
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win7.png <img width=300 src="http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win7.png">]</span>
 
 
 
==Windows 10==
 
When you pair your computer with the e-puck2, 6 COM ports will be automatically created. The three ports you will use have <code>Outgoing</code> direction and are named <code>e_puck2_xxxxx-GDB</code>, <code>e_puck2_xxxxx-UART</code>, <code>e_puck2_xxxxx-SPI</code>. <code>xxxxx</code> is the ID number of your e-puck2.<br/>
 
To see which COM port corresponds to which channel you need to:
 
# open the Bluetooth devices manager
 
# pair with the robot
 
# click on <code>More Bluetooth options</code>
 
# the ports and related channels are listed in the <code>COM Ports</code> tab, as shown in the following figure:<br/>
 
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png <img height=300 src="http://projects.gctronic.com/epuck2/wiki_images/BT-connection-win10.png">]</span>
 
  
==Linux==
+
==Communicate with the IMU==
Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: <br/>
+
===e-puck1===
<code>sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2</code><br/>
+
An example written in C showing how to read data from the IMU (LSM330) mounted on e-puck 1.3 is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/e-puck1/</code>.<br/>
The MAC address is visible from the Bluetooth manager. The parameter <code>2</code> indicates the channel, in this case a port for the <code>UART</code> channel is created. If you want to connect to another service you need to change this parameter accordingly (e.g. <code>1</code> for <code>GDB</code> and <code>3</code> for <code>SPI</code>). Now you can use <code>/dev/rfcomm0</code> to connect to the robot.
+
You can build the program with the command <code>gcc e-puck1_imu.c -o e-puck1_imu</code>.<br/>
 +
Now you can run the program by issueing <code>./e-puck1_imu</code> and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal.<br/>
  
==Mac==
+
===e-puck2===
When you pair your computer with the e-puck2, 3 COM ports will be automatically created: <code>/dev/cu.e-puck2_xxxxx-GDB</code>, <code>/dev/cu.e-puck2_xxxxx-UART</code> and <code>/dev/cu.e-puck2_xxxxx-SPI</code>. xxxxx is the ID number of your e-puck2.
+
An example showing how to read data from the IMU (MPU-9250) is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/e-puck2/</code>.<br/>
 +
You can build the program with the command <code>gcc e-puck2_imu.c -o e-puck2_imu</code>.<br/>
 +
Now you can run the program by issueing <code>./e-puck2_imu</code> and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal.<br/>
  
==Testing the Bluetooth connection==
+
==Communicate with the ToF sensor==
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/>
+
The Time of Flight sensor is available only on the e-puck2 robot.<br/>
In the connection textfield you need to enter the UART channel port, for example:
 
* Windows 7: <code>COM258</code>
 
* Windows 10: <code>e_puck2_xxxxx-UART</code>
 
* Linux: <code>/dev/rfcomm0</code>
 
* Mac: <code>/dev/cu.e-puck2_xxxxx-UART</code>
 
and then click <code>Connect</code>. <br/>
 
You should start receiving sensors data and you can send commands to the robot.<br/>
 
  
Alternatively you can also use a simple terminal program (e.g. <code>realterm</code> in Windows) instead of the PC application, then you can issue manually the commands to receive sensors data or for setting the actuators (once connected, type <code>h + ENTER</code> for a list of availables commands).
+
First of all you need to verify that the VL53L0X Python package is installed with the following command: <code>python3 -c "import VL53L0X"</code>. If the command returns nothing you're ready to go, otherwise if you receive an <code>ImportError</code> then you need to install the package with the command: <code>pip3 install git+https://github.com/gctronic/VL53L0X_rasp_python</code>.<br/>
  
==Connecting to multiple robots==
+
A Python example showing how to read data from the ToF sensor is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/e-puck2/</code>.<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.
+
You can run the example by issueing <code>python3 VL53L0X_example.py</code> (this is the example that you can find in the repository [https://github.com/gctronic/VL53L0X_rasp_python/tree/master/python https://github.com/gctronic/VL53L0X_rasp_python/tree/master/python]).
  
==Python examples==
+
==Capture an image==
Here are some basic Python example that show how to get data from the robot through Bluetooth using the commands available with the <code>advanced sercom v2</code>:
+
The robot camera is connected to the Pi-puck extension as a USB camera, so you can access it very easily.<br/>
* [http://projects.gctronic.com/epuck2/printhelp.py printhelp.py]: print the list of commands available in the <code>advanced sercom v2</code>
+
An example showing how to capture an image from the robot's camera using OpenCV is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/snapshot/</code>.<br/>
* [http://projects.gctronic.com/epuck2/getprox.py getprox.py]: print the values of the proximity sensors
+
You can build the program with the command <code>g++ $(pkg-config --libs --cflags opencv) -ljpeg -o snapshot snapshot.cpp</code>.<br/>
In both examples you need to set the correct Bluetooth serial port related to the robot.
+
Now you can run the program by issueing <code>./snapshot</code>; this will save a VGA image (JPEG) named <code>image01.jpg</code> to disk.<br/>
 +
The program can accept the following parameters:<br/>
 +
<code>-d DEVICE_ID</code> to specify the input video device from which to capture an image, by default is <code>0</code> (<code>/dev/video0</code>). This is useful when working also with the [http://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3 Omnivision V3] extension that crates another video device; in this case you need to specify <code>-d 1</code> to capture from the robot camera.<br/>
 +
<code>-n NUM</code> to specify how many images to capture (1-99), by default is 1<br/>
 +
<code>-v</code> to enable verbose mode (print some debug information)<br/>
 +
Beware that in this demo the acquisition rate is fixed to 5 Hz, but the camera supports up to 15 FPS.
  
=Connecting to the WiFi=
+
==Communicate with the ground sensors extension==
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/>
+
Both e-puck1 and e-puck2 support the [https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors ground sensors extension].<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.
+
This extension is attached to the I2C bus and can be read directly from the Pi-puck.<br/>
 +
An example written in C showing how to read data from the ground sensors extension is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/ground-sensor/</code>.<br/>
 +
You can build the program with the command <code>gcc groundsensor.c -o groundsensor</code>.<br/>
 +
Now you can run the program by issueing <code>./groundsensor</code>; this demo will print the sensors data on the terminal.<br/>
  
The LED2 is used to indicate the state of the WiFi connection:
+
=How to work with the Pi-puck=
* red indicates that the robot is in ''access point mode'' (waiting for configuration)
+
==Demos and scripts update==
* green indicates that the robot is connected to a network and has received an IP address
+
First of all you should update to the last version of the demos and scripts released with the system that you can use to start playing with the Pi-puck extension and the robot.<br/>
* blue (toggling) indicates that the robot is transferring the image to the computer
+
To update the repository follow these steps:<br/>
* off when the robot cannot connect to the saved configuration
+
1. go to the directory <code>/home/pi/Pi-puck</code><br/>
::<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/>
+
2. issue the command <code>git pull</code><br/>
 +
Then to update some configurations of the system:<br/>
 +
1. go to the directory <code>/home/pi/Pi-puck/system</code><br/>
 +
2. issue the command <code>./update.sh</code>; the system will reboot.<br/>
 +
You can find the Pi-puck repository here [https://github.com/gctronic/Pi-puck https://github.com/gctronic/Pi-puck].<br/>
  
==Network configuration==
+
==Audio recording==
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.  
+
Use the <code>arecord</code> utility to record audio from the onboard microphone. The following example shows how to record an audio of 2 seconds (<code>-d</code> parameter) and save it to a wav file (<code>test.wav</code>):<br/>
 +
<code>arecord -Dmic_mono -c1 -r16000 -fS32_LE -twav -d2 test.wav</code><br/>
 +
You can also specify a rate of 48 KHz with <code>-r48000</code>
  
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/>
+
==Audio play==
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/>
+
Use <code>aplay</code> to play <code>wav</code> files and <code>mplayer</code> to play <code>mp3</code> files.
  
<span class="plainlinks">
+
==Battery reading==
<table>
+
An example showing how to measure both the battery of the robot and the battery of the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/battery/</code>.<br/>
<tr>
+
The first time you need to change the mode of the script in order to be executable with the command <code>sudo chmod +x read-battery.sh</code>.<br/>
<td align="center">[1]</td>
+
Then you can start reading the batteries value by issueing <code>./read-battery.sh</code>.; this demo will print the batteries values (given in Volts) on the terminal.
<td align="center">[2]</td>
 
<td align="center">[3]</td>
 
<td align="center">[4]</td>
 
</tr>
 
<tr>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup1.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup2.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup3.png">]</td>
 
<td>[http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/esp32-wifi-setup4.png">]</td>
 
</tr>
 
</table>
 
</span><br/>
 
Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically.<br/>
 
Remember that you need to power cycle the robot at least once for the new configuration to be active.<br/>
 
  
Once the connection is established, the LED2 will be green.<br/>
+
==WiFi configuration==
 +
Specify your network configuration in the file <code>/etc/wpa_supplicant/wpa_supplicant-wlan0.conf</code>.<br/>
 +
Example:<br/>
 +
<pre>
 +
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 +
update_config=1
 +
country=CH
 +
network={
 +
        ssid="MySSID"
 +
        psk="9h74as3xWfjd"
 +
}
 +
</pre>
 +
You can have more than one <code>network</code> parameter to support more networks.<br/>
 +
Once the configuration is done, you can also connect to the Pi-puck with <code>SSH</code>.
  
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''.
+
===How to know your IP address===
::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-wifi-reset-small.png">]</span><br/>
 
  
==Finding the IP address==
+
==File transfer==
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/>
+
===USB cable===
 
+
You can transfer files via USB cable between the computer and the Pi-puck extension by using on of the <code>zmodem</code> protocol.<br/>
Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to the port labeled <code>Serial Monitor</code> (see chapter [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Finding the USB serial ports used]). Then power cycle the robot and the IP address will be shown in the terminal (together with others informations), as illustrated in the following figure:<br/>
+
The <code>lrzsz</code> package is pre-installed in the system, thus you can use the <code>sx</code> and <code>rx</code> utilities to respectevely send files to the computer and receive files from the computer.<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>
+
Example of sending a file to the computer using the <code>Minicom</code> terminal program:<br/>
 
+
1. in the Pi-puck console type <code>sx --zmodem fliename.ext</code>. The transfer should start automatically and you'll find the file in the home directory.<br/>
==Testing the WiFi connection==
+
<!--2. to start the transfer type the sequence <code>CTRL+A+R</code>, then chose <code>xmodem</code> and finally enter the name you want to assign to the received file. You'll find the file in the home directory.<br/>-->
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:
+
Example of receiving a file from the computer using the <code>Minicom</code> terminal program:<br/>
* [http://projects.gctronic.com/epuck2/monitor_wifi_27dddd4.zip Windows executable - WiFi]
+
1. in the Pi-puck console type <code>rx -Z</code><br/>
* Mac (not available yet)
+
2. to start the transfer type the sequence <code>CTRL+A+S</code>, then chose <code>zmodem</code> and select the file you want to send with the <code>spacebar</code>. Finally press <code>enter</code> to start the transfer.<br/>
* [http://projects.gctronic.com/epuck2/monitor_wifi_linux64bit_27dddd4.tar.gz Ubuntu 14.04 (or later) - 64 bit]
+
===WiFi===
 
+
The Pi-puck extension supports <code>SSH</code> connections.<br/>
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/>
+
To exchange files between the Pi-puck and the computer, the <code>scp</code> tool (secure copy) can be used. An example of transferring a file from the Pi-puck to the computer is the following:<br/>
 
+
<code>scp pi@192.168.1.20:/home/pi/example.txt example.txt</code>
Run the PC application, insert the IP address of the robot in the connection textfield and then click on the <code>Connect</code> button. You should start receiving sensors data and you can send commands to the robot. The LED2 blue will toggle.<br/>
 
 
 
==Web server==
 
When the robot is in ''access point mode'' you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface.<br/>
 
You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address <code>192.168.1.1/monitor.html</code>.
 
 
 
=Communication protocol=
 
This section is the hardest part to understand. It outlines all the details about the communication protocols that you'll need to implement in order to communicate with the robot form the computer. So spend a bit of time reading and re-reading this section in order to grasp completely all the details.
 
 
 
==Bluetooth and USB==
 
The communication protocol is based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol], used with the e-puck1.x robot. The <code>advanced sercom v2</code> includes all the commands available in the <code>advanced sercom</code> protocol and add some additional commands to handle the new features of the e-puck2 robot. In particular here are the new commands:
 
{| border="1" cellpadding="10" cellspacing="0"
 
!Command
 
!Description
 
!Return value / set value
 
|-
 
|<code>0x08</code>
 
|Get all sensors
 
|see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi]
 
|-
 
|<code>0x09</code>
 
|Set all actuators
 
|see section [http://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 Communication protocol: WiFi]
 
|-
 
|<code>0x0A</code>
 
|Set RGB LEDs, values from 0 (off) to 100 (completely on)
 
|<code>[LED2_red][LED2_blue][LED2_green][LED4_red][LED4_blue][LED4_green][LED6_red][LED6_blue][LED6_green][LED8_red][LED8_blue][LED8_green]</code>
 
|-
 
|<code>0x0B</code>
 
|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>
 
|}
 
  
==WiFi==
+
If you are working in Windows you can use [https://www.putty.org/ PuTTY].
The communication is based on TCP; the robot create a TCP server and wait for a connection.<br/>
 
  
Each packet is identified by an ID (1 byte). The following IDs are used to send data from the robot to the computer:
+
==Image streaming==
* 0x00 = reserved
 
* 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565
 
* 0x02 = sensors packet; packet size (without id) = 104 bytes; the format of the returned values are based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol] and are compatible with e-puck1.x:
 
  
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
 
:*Acc: raw axes values, between -1500 and 1500, resolution is +-2g
 
:*Acceleration: acceleration magnitude <img width=70 src="http://projects.gctronic.com/epuck2/wiki_images/3dvector-magnitude.png">, between 0.0 and about 2600.0 (~3.46 g)
 
:*Orientation: between 0.0 and 360.0 degrees <table><tr><td align="center">0.0 deg</td><td align="center">90.0 deg</td><td align="center">180 deg</td><td align="center">270 deg</td></tr><tr><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation0.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation90.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation180.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/orientation270.png"></td></tr></table>
 
  
:*Inclination: between 0.0 and 90.0 degrees (when tilted in any direction)<table><tr><td align="center">0.0 deg</td><td align="center">90.0 deg</td></tr><tr><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination0.png"></td><td><img width=80 src="http://projects.gctronic.com/epuck2/wiki_images/inclination90.png"></td></tr></table>
+
==Bluetooth LE==
:*Gyro: raw axes values, between -32768 and 32767, range is +-250dps
+
An example of a ''BLE uart service'' is available in the Pi-puck repository; you can find it in the directory <code>/home/pi/Pi-puck/ble/</code>.<br/>
:*Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla)
+
To start the service you need to type: <code>python uart_peripheral.py</code>.<br/>
:*Temp: temperature given in Celsius degrees
+
Then you can use the ''e-puck2-android-ble app'' you can find in chapter [https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#Connecting_to_the_BLE Connecting to the BLE] in order to connect to the Pi-puck extension via BLE. Once connected you'll receive some dummy data for the proximity values and by clicking on the motion buttons you'll see the related action printed on the Pi-puck side. This is a starting point that you can extend based on your needs.
:*IR proximity: between 0 (no objects detected) and 4095 (object near the sensor)
 
:*IR ambient: between 0 (strong light) and 4095 (dark)
 
:*ToF distance: distance given in millimeters
 
:*Mic volume: between 0 and 4095
 
:*Motors steps: 1000 steps per wheel revolution
 
:*Battery:
 
:*uSD state: 1 if the micro sd is present and can be read/write, 0 otherwise
 
:*TV remote data: RC5 protocol
 
:*Selector position: between 0 and 15
 
:*Ground proximity: between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white)
 
:*Ground ambient: between 0 (strong light) and 1023 (dark)
 
:*Button state: 1 button pressed, 0 button released
 
* 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested
 
The following IDs are used to send data from the computer to the robot:
 
* 0x80 = commands packet; packet size (without id) = 20 bytes:
 
  
:<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot.jpg <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-pc-to-robot.jpg">]</span><br/>
+
=Operating system=
 +
The system is based on Raspbian Stretch and can be downloaded from the following link [http://projects.gctronic.com/epuck2/PiPuck/gctronic-stretch-ros-kinetic-opencv3.4.1_15.03.19.img.tar.gz gctronic-stretch-ros-kinetic-opencv3.4.1.img.tar.gz].
  
:*request:
+
When booting the first time, the first thing to do is expanding the file system in order to use all the available space on the micro sd:<br/>
:** bit0: 0=stop image stream; 1=start image stream
+
1. <code>sudo raspi-config</code><br/>
:** bit1: 0=stop sensors stream; 1=start sensors stream
+
2. Select <code>Advanced Options</code> and then <code>Expand Filesystem</code><br/>
:*settings:
+
3. reboot
:** bit0: 1=calibrate IR proximity sensors
 
:** bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet)
 
:** bit2: 0=set motors speed; 1=set motors steps (position)
 
:*left and right: when bit2 of <code>settings</code> field is <code>0</code>, then this is the desired motors speed (-1000..1000); when <code>1</code> then this is the value that will be set as motors position (steps)
 
:*LEDs: 0=off; 1=on; 2=toggle
 
:** bit0: 0=LED1 off; 1=LED1 on
 
:** bit1: 0=LED3 off; 1=LED3 on
 
:** bit2: 0=LED5 off; 1=LED5 on
 
:** bit3: 0=LED7 off; 1=LED7 on
 
:** bit4: 0=body LED off; 1=body LED on
 
:** bit5: 0=front LED off; 1=front LED on
 
:*RGB LEDs: for each LED, it is specified in sequence the value of red, green and blue (0...100)
 
:* sound id: 0x01=MARIO, 0x02=UNDERWOLRD, 0x04=STARWARS, 0x08=4KHz, 0x10=10KHz, 0x20=stop sound
 
  
For example to receive the camera image (stream) the following steps need to be followed:<br/>
+
==Desktop mode==
1) connect to the robot through TCP<br/>
+
The system starts in console mode, to switch to desktop (LXDE) mode issue the command <code>startx</code>.
2) send the command packet:
+
===Camera viewer===
:{| border="1"
 
|0x80
 
|0x01
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|0x00
 
|}
 
3) read the ID (1 byte) and the QQVGA color image pakcet (38400 bytes)<br/>
 
4) go to step 3
 
  
=Webots=
+
==I2C communication==
TBD
+
The communication between the Pi-puck extension and the robot is based on I2C. The system is configured to exploit the I2C hardware peripheral in order to save CPU usage, but if you need to use the software I2C you can enable it by modifying the <code>/boot/config.txt</code> file and removing the <code>#</code> symbol (comment) in front of the line with the text <code>dtparam=soft_i2c</code> (it is placed towards the end of the file).
  
 
=ROS=
 
=ROS=
This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema:<br/>
+
ROS Kinetic is integrated in the Pi-puck system.
<span class="plainlinks">[http://www.gctronic.com/doc/images/epuck-ros-schema.png <img width=450 src="http://www.gctronic.com/doc/images/epuck-ros-schema-small.png">]</span>
 
''<font size="2">Click to enlarge</font>''<br/>
 
 
 
First of all you need to install and configure ROS, refer to [http://wiki.ros.org/Distributions http://wiki.ros.org/Distributions] for more informations. <font style="color:red"> This tutorial is based on ROS Kinetic</font>.
 
 
 
Starting from the work done with the e-puck1 (see [https://www.gctronic.com/doc/index.php?title=E-Puck#ROS E-Puck ROS]), we updated the code in order to support the e-puck2 robot.
 
 
 
 
==Initial configuration==
 
==Initial configuration==
The following steps need to be done only once, after installing ROS:
+
The ROS workspace is located in <code>~/rosbots_catkin_ws/</code><br/>
: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: 
+
The e-puck2 ROS driver is located in <code>~/rosbots_catkin_ws/src/epuck_driver_cpp/</code><br/>
<pre>  mkdir -p ~/catkin_ws/src
+
Remember to follow the steps in the section [http://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements Requirements ] and section [https://www.gctronic.com/doc/index.php?title=Pi-puck#Demos_and_scripts_update Demos and scripts update], only once.<br/>
  cd ~/catkin_ws/src
+
The PC (if used) and the Pi-puck extension are supposed to be configured in the same network.
  catkin_init_workspace
 
  cd ~/catkin_ws/
 
  catkin_make
 
  source devel/setup.bash </pre>
 
:2. You will need to add the line <code>source ~/catkin_ws/devel/setup.bash</code> to your <tt>.bashrc</tt> in order to automatically have access to the ROS commands when the system is started
 
:3. Move to <code>~/catkin_ws/src</code> and clone the ROS e-puck2 driver repo:
 
:* if you are working with Python: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>
 
:* if you are working with cpp: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>
 
:4. Install the dependencies:
 
:* Python:
 
:** The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies:
 
:*** install the Python setup tools: <code>sudo apt-get install python-setuptools</code>
 
:*** install the Python image library: <code>sudo apt-get install python-imaging</code>
 
:*** install pybluez: <code>sudo pip install pybluez</code>
 
:**** install pybluez dependencies: <code>sudo apt-get install libbluetooth-dev</code>
 
:* cpp:
 
:** install the library used to communicate with Bluetooth: <code>sudo apt-get install libbluetooth-dev</code>
 
:5. Open a terminal and go to the catkin workspace directory (<tt>~/catkin_ws</tt>) and issue the command <code>catkin_make</code>, there shouldn't be errors
 
:6. Program the e-puck2 robot with the [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware factory firmware] and put the selector in position 3
 
 
 
==Running the Python ROS node==
 
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver</code>. <br/>
 
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
 
Moreover make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): <code>chmod +x ./src/epuck_driver/scripts/epuck2_driver.py</code>. <br/>
 
  
Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
+
==Running roscore==
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.
+
<code>roscore</code> can be launched either from the PC or directly from the Pi-puck.<br/>
 +
Before starting roscore, open a terminal and issue the following commands:
 +
* <code>export ROS_IP=roscore-ip</code>
 +
* <code>export ROS_MASTER_URI=http://roscore-ip:11311</code>
 +
where <code>roscore-ip</code> is the IP of the machine that runs <code>roscore</code><br/>
 +
Then start <code>roscore</code> by issueing <code>roscore</code>.
  
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>.
+
==Running the ROS node==
 +
Before starting the e-puck2 ROS node on the Pi-puck, issue the following commands:
 +
* <code>export ROS_IP=pipuck-ip</code>
 +
* <code>export ROS_MASTER_URI=http://roscore-ip:11311</code>
 +
where <code>pipuck-ip</code> is the IP of the Pi-puck extension and <code>roscore-ip</code> is the IP of the machine that runs <code>roscore</code> (can be the same IP if <code>roscore</code> runs directly on the Pi-puck).
  
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/>
+
To start the e-puck2 ROS node issue the command:<br/>
Open a terminal and issue the following command: <code>roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'</code>.<br/>
+
<code>roslaunch epuck_driver_cpp epuck_minimal.launch debug_en:=true ros_rate:=20</code><br/>
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
+
<!--
 +
To start the e-puck2 ROS node issue the command:<br/>
 +
<code>roslaunch epuck_driver_cpp epuck_controller.launch epuck_id:='3000'</code><br/>
 +
This launch file will start the e-puck2 node and the camera node.
 +
If you are using a PC, then you can start <code>rviz</code>:
 +
* in a terminal issue the command <code>rviz rviz</code>
 +
* open the configuration file named <code>single_epuck_driver_rviz.rviz</code> you can find in <code>epuck_driver_cpp/config/</code> directory
 +
-->
  
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.<br/>
+
The following graph shows all the topics published by the e-puck2 driver node:<br/>
The following graph shows all the topics published by the e-puck2 driver node and the <code>rviz</code> interface: <br/>
+
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/ros-e-puck2_.jpg <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/ros-e-puck2_small.jpg">]</span>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_small.png">]</span>
 
 
''<font size="2">Click to enlarge</font>''
 
''<font size="2">Click to enlarge</font>''
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz.png <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-rviz_small.png">]</span>
 
''<font size="2">Click to enlarge</font>''<br/>
 
 
==Running the cpp ROS node==
 
First of all get the last version of the ROS e-puck2 driver from github. Move to <code>~/catkin_ws/src</code> and issue: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp</code>. <br/>
 
Then build the driver by opening a terminal and issueing the command <code>catkin_make</code> from within the catkin workspace directory (e.g. ~/catkin_ws).<br/>
 
 
Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth].<br/>
 
Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to <tt>System Settings</tt>, <tt>Bluetooth</tt> and select the robot; once selected you'll see in the right side the related MAC address.
 
 
First thing to do before launching the script file is running the <tt>roscore</tt>, open another terminal tab and issue the command <tt>roscore</tt>.
 
 
Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [http://wiki.ros.org/roslaunch roslaunch]).<br/>
 
Open a terminal and issue the following command: <code>roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'</code>.<br/>
 
<tt>B4:E6:2D:EB:9C:4F</tt> is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot.
 
 
If all is going well the robot will be ready to exchange data and [http://wiki.ros.org/rviz/UserGuide rviz] will be opened showing the informations gathered from the topics published by the e-puck2 driver node.<br/>
 
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.
 
 
==Move the robot==
 
You have some options to move the robot.<br/>
 
 
The first one is to use the <code>rviz</code> interface: in the bottom left side of the interface there is a <code>Teleop</code> panel containing an ''interactive square'' meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right.<br/>
 
 
The second method to move the robot is using the <code>ros-kinetic-turtlebot-teleop</code> ROS package. If not already done, you can install this package by issueing <code>sudo apt-get install ros-kinetic-turtlebot-teleop</code>.<br/>
 
There is a lunch file in the e-puck2 ROS driver that configures this package in order to be used with the e-puck2 robot. To start the launch file, issue the following command <code>roslaunch epuck_driver epuck2_teleop.launch</code>, then follow the instructions printed on the terminal to move the robot.<br/>
 
 
The third method is by directly publishing on the <code>/mobile_base/cmd_vel</code> topic, for instance by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'</code> the robot will rotate on the spot, instead by issueing the following command <code>rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'</code> the robot will move straight forward.<br/>
 
Beware that there shouldn't be any other node publishing on the <code>/mobile_base/cmd_vel</code> topic, otherwise your commands will be overwritten.
 
 
==Control the RGB LEDs==
 
The general command to change the RGB LEDs colors is the following:<br/>
 
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"</code><br/>
 
The values range is from 0 (off) to 100 (completely on). Have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2#Overview e-puck2 overview] to know the position of the RGB LEDs.<br/>
 
  
For instance to set all the RGB LEDs to red, issue the following command:<br/>
+
==Get the source code==
<code>rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"</code><br/>
+
The last version of the e-puck2 ROS node can be downloaded from the git: <code>git clone -b pi-puck https://github.com/gctronic/epuck_driver_cpp.git</code>
  
To turn off all the RGB LEDs issue the following command:<br/>
+
=OpenCV=
<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>
+
OpenCV 3.4.1 is integrated in the Pi-puck system.

Revision as of 14:44, 18 November 2019

1 Overview


Features:

  • Raspberry Pi zero W (rPi) connected to the robot via I2C
  • interface between the robot base camera and the rPi via USB
  • 1 digital microphone and 1 speaker
  • USB hub connected to the rPi with 2 free ports
  • uUSB cable to the rPi uart port. Also ok for charging
  • 2 chargers. 1 for the robot battery and 1 for the auxiliary battery on top of the extension
  • charging contact points in front for automatic charging. External docking station available
  • several extension options. 6 i2C channels, 2 ADC inputs
  • several LED to show the status of the rPi and the power/chargers

2 Getting started

This introductory section explains the minimal procedures needed to work with the Raspberry Pi Zero W mounted on the Pi-puck extension board and gives a general overview of the available basic demos and scripts shipped with the system flashed on the micro SD. More advanced demos are described in the following separate sections (e.g. ROS), but the steps documented here are fundamental, so be sure to fully understand them.

The extension is mostly an interface between the e-puck robot and the Raspberry Pi, so you can exploit the computational power of a Linux machine to extend the robot capabilities.

In most cases, the Pi-puck extension will be attached to the robot, but it's interesting to note that it can be used also alone when the interaction with the robot isn't required.
The following sections assume the full configuration (robot + extension), unless otherwise stated.

2.1 Requirements

The robot must be programmed with a special firmware in order to communicate via I2C bus with the Raspberry Pi mounted on the Pi-puck extension. The same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the Raspberry Pi. Since the Raspberry Pi acts as I2C master, these devices will not be anymore reachable directly from the robot main microcontroller that will act instead as I2C slave.

2.1.1 e-puck1

The e-puck1 robot must be programmed with the following firmware pi-puck-e-puck1.hex.

2.1.2 e-puck2

The e-puck2 robot must be programmed with the following firmware e-puck2_main-processor_extension.elf (07.06.19) and the selector must be placed in position 10.

2.2 Turn on/off the extension

To turn on the extension you need to press the auxON button as shown in the follwoing figure; this will turn on also the robot (if not already turned on). Similarly, if you turn on the robot then also the extension will turn on automatically.

To turn off the Pi-puck you need to press and hold the auxON button for 2 seconds; this will initiate the power down procedure.

Beware that by turning off the robot, the extension will not be turned off automatically if it is powered from another source like the micro usb cable or a secondary battery. You need to use its power off button to switch it off. Instead if there is no other power source, then by turning off the robot also the extension will be turned off (not cleanly).

2.3 Console mode

The Pi-puck extension board comes with a pre-configured system ready to run without any additional configuration.
In order to access the system from a PC in console mode, the following steps must be performed:
1. connect a micro USB cable from the PC to the extension module. If needed, the drivers are available in the following link USB to UART bridge drivers

2. execute a terminal program and configure the connection with 115200-8N1 (no flow control). The serial device is the one created when the extension is connected to the computer
3. switch on the robot (the extension will turn on automatically); now the terminal should display the Raspberry Pi booting information. If the robot isn't present, then you can directly power on the extension board with the related button
4. login with user = pi, password = raspberry

2.4 Battery charge

You can either charge the robot battery or the additional battery connected to the Pi-puck extension or both the batteries by simply plugging the micro USB cable.
The following figure shows the connector for the additional battery.

The robot can also autonomously charge itself if the charging wall is available. The Pi-puck extension includes two spring contacts on the front side that let the robot easily make contact with the charging wall and charge itself. The charging wall and the spring contacts are shown in the following figures:

3 How to communicate with the robot and its sensors

3.1 Communicate with the e-puck1

Refer to the repo https://github.com/yorkrobotlab/pi-puck-e-puck1.

3.2 Communicate with the e-puck2

An example showing how to exchange data between the robot and the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/e-puck2/.
You can build the program with the command gcc e-puck2_test.c -o e-puck2_test.
Now you can run the program by issueing ./e-puck2_test; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz.

3.2.1 Packet format

Extension to robot packet format, 20 bytes payload (the number in the parenthesis represents the bytes for each field):

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) Settings (1) Checksum (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)]
  • 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)
  • Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..18)

Robot to extension packet format, 47 bytes payload (the number in the parenthesis represents the bytes for each field):

8 x Prox (16) 8 x Ambient (16) 4 x Mic (8) Selector + button (1) Left steps (2) Right steps (2) TV remote (1) Checksum
  • Selector + button: selector values represented by 4 least significant bits (bit0, bit1, bit2, bit3); button state is in bit4 (1=pressed, 0=not pressed)
  • Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..45)

3.3 Communicate with the IMU

3.3.1 e-puck1

An example written in C showing how to read data from the IMU (LSM330) mounted on e-puck 1.3 is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/e-puck1/.
You can build the program with the command gcc e-puck1_imu.c -o e-puck1_imu.
Now you can run the program by issueing ./e-puck1_imu and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal.

3.3.2 e-puck2

An example showing how to read data from the IMU (MPU-9250) is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/e-puck2/.
You can build the program with the command gcc e-puck2_imu.c -o e-puck2_imu.
Now you can run the program by issueing ./e-puck2_imu and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal.

3.4 Communicate with the ToF sensor

The Time of Flight sensor is available only on the e-puck2 robot.

First of all you need to verify that the VL53L0X Python package is installed with the following command: python3 -c "import VL53L0X". If the command returns nothing you're ready to go, otherwise if you receive an ImportError then you need to install the package with the command: pip3 install git+https://github.com/gctronic/VL53L0X_rasp_python.

A Python example showing how to read data from the ToF sensor is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/e-puck2/.
You can run the example by issueing python3 VL53L0X_example.py (this is the example that you can find in the repository https://github.com/gctronic/VL53L0X_rasp_python/tree/master/python).

3.5 Capture an image

The robot camera is connected to the Pi-puck extension as a USB camera, so you can access it very easily.
An example showing how to capture an image from the robot's camera using OpenCV is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/snapshot/.
You can build the program with the command g++ $(pkg-config --libs --cflags opencv) -ljpeg -o snapshot snapshot.cpp.
Now you can run the program by issueing ./snapshot; this will save a VGA image (JPEG) named image01.jpg to disk.
The program can accept the following parameters:
-d DEVICE_ID to specify the input video device from which to capture an image, by default is 0 (/dev/video0). This is useful when working also with the Omnivision V3 extension that crates another video device; in this case you need to specify -d 1 to capture from the robot camera.
-n NUM to specify how many images to capture (1-99), by default is 1
-v to enable verbose mode (print some debug information)
Beware that in this demo the acquisition rate is fixed to 5 Hz, but the camera supports up to 15 FPS.

3.6 Communicate with the ground sensors extension

Both e-puck1 and e-puck2 support the ground sensors extension.
This extension is attached to the I2C bus and can be read directly from the Pi-puck.
An example written in C showing how to read data from the ground sensors extension is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/ground-sensor/.
You can build the program with the command gcc groundsensor.c -o groundsensor.
Now you can run the program by issueing ./groundsensor; this demo will print the sensors data on the terminal.

4 How to work with the Pi-puck

4.1 Demos and scripts update

First of all you should update to the last version of the demos and scripts released with the system that you can use to start playing with the Pi-puck extension and the robot.
To update the repository follow these steps:
1. go to the directory /home/pi/Pi-puck
2. issue the command git pull
Then to update some configurations of the system:
1. go to the directory /home/pi/Pi-puck/system
2. issue the command ./update.sh; the system will reboot.
You can find the Pi-puck repository here https://github.com/gctronic/Pi-puck.

4.2 Audio recording

Use the arecord utility to record audio from the onboard microphone. The following example shows how to record an audio of 2 seconds (-d parameter) and save it to a wav file (test.wav):
arecord -Dmic_mono -c1 -r16000 -fS32_LE -twav -d2 test.wav
You can also specify a rate of 48 KHz with -r48000

4.3 Audio play

Use aplay to play wav files and mplayer to play mp3 files.

4.4 Battery reading

An example showing how to measure both the battery of the robot and the battery of the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/battery/.
The first time you need to change the mode of the script in order to be executable with the command sudo chmod +x read-battery.sh.
Then you can start reading the batteries value by issueing ./read-battery.sh.; this demo will print the batteries values (given in Volts) on the terminal.

4.5 WiFi configuration

Specify your network configuration in the file /etc/wpa_supplicant/wpa_supplicant-wlan0.conf.
Example:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=CH
network={
        ssid="MySSID"
        psk="9h74as3xWfjd"
}

You can have more than one network parameter to support more networks.
Once the configuration is done, you can also connect to the Pi-puck with SSH.

4.5.1 How to know your IP address

4.6 File transfer

4.6.1 USB cable

You can transfer files via USB cable between the computer and the Pi-puck extension by using on of the zmodem protocol.
The lrzsz package is pre-installed in the system, thus you can use the sx and rx utilities to respectevely send files to the computer and receive files from the computer.
Example of sending a file to the computer using the Minicom terminal program:
1. in the Pi-puck console type sx --zmodem fliename.ext. The transfer should start automatically and you'll find the file in the home directory.
Example of receiving a file from the computer using the Minicom terminal program:
1. in the Pi-puck console type rx -Z
2. to start the transfer type the sequence CTRL+A+S, then chose zmodem and select the file you want to send with the spacebar. Finally press enter to start the transfer.

4.6.2 WiFi

The Pi-puck extension supports SSH connections.
To exchange files between the Pi-puck and the computer, the scp tool (secure copy) can be used. An example of transferring a file from the Pi-puck to the computer is the following:
scp pi@192.168.1.20:/home/pi/example.txt example.txt

If you are working in Windows you can use PuTTY.

4.7 Image streaming

4.8 Bluetooth LE

An example of a BLE uart service is available in the Pi-puck repository; you can find it in the directory /home/pi/Pi-puck/ble/.
To start the service you need to type: python uart_peripheral.py.
Then you can use the e-puck2-android-ble app you can find in chapter Connecting to the BLE in order to connect to the Pi-puck extension via BLE. Once connected you'll receive some dummy data for the proximity values and by clicking on the motion buttons you'll see the related action printed on the Pi-puck side. This is a starting point that you can extend based on your needs.

5 Operating system

The system is based on Raspbian Stretch and can be downloaded from the following link gctronic-stretch-ros-kinetic-opencv3.4.1.img.tar.gz.

When booting the first time, the first thing to do is expanding the file system in order to use all the available space on the micro sd:
1. sudo raspi-config
2. Select Advanced Options and then Expand Filesystem
3. reboot

5.1 Desktop mode

The system starts in console mode, to switch to desktop (LXDE) mode issue the command startx.

5.1.1 Camera viewer

5.2 I2C communication

The communication between the Pi-puck extension and the robot is based on I2C. The system is configured to exploit the I2C hardware peripheral in order to save CPU usage, but if you need to use the software I2C you can enable it by modifying the /boot/config.txt file and removing the # symbol (comment) in front of the line with the text dtparam=soft_i2c (it is placed towards the end of the file).

6 ROS

ROS Kinetic is integrated in the Pi-puck system.

6.1 Initial configuration

The ROS workspace is located in ~/rosbots_catkin_ws/
The e-puck2 ROS driver is located in ~/rosbots_catkin_ws/src/epuck_driver_cpp/
Remember to follow the steps in the section Requirements and section Demos and scripts update, only once.
The PC (if used) and the Pi-puck extension are supposed to be configured in the same network.

6.2 Running roscore

roscore can be launched either from the PC or directly from the Pi-puck.
Before starting roscore, open a terminal and issue the following commands:

where roscore-ip is the IP of the machine that runs roscore
Then start roscore by issueing roscore.

6.3 Running the ROS node

Before starting the e-puck2 ROS node on the Pi-puck, issue the following commands:

where pipuck-ip is the IP of the Pi-puck extension and roscore-ip is the IP of the machine that runs roscore (can be the same IP if roscore runs directly on the Pi-puck).

To start the e-puck2 ROS node issue the command:
roslaunch epuck_driver_cpp epuck_minimal.launch debug_en:=true ros_rate:=20

The following graph shows all the topics published by the e-puck2 driver node:
Click to enlarge

6.4 Get the source code

The last version of the e-puck2 ROS node can be downloaded from the git: git clone -b pi-puck https://github.com/gctronic/epuck_driver_cpp.git

7 OpenCV

OpenCV 3.4.1 is integrated in the Pi-puck system.