Pi-puck and Others Extensions: Difference between pages

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


==I2C bus==
The documentation and hardware files are available in the following links:
I2C is used to let communicate various elements present in the robot, Pi-puck and extensions. An overall schema is shown in the following figure:<br/>
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Schematics.pdf Schematics (pdf)]
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/i2c-buses.png <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/i2c-buses.png">]</span><br/>
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Assembling.pdf Assembling (pdf)]
An I2C switcher is included in the Pi-puck extension in order to support additional I2C buses (the RPi alone has only one usable I2C bus). These are needed to avoid conflicts between Time-of-Flight sensors that have a fixed I2C address.
* [https://projects.gctronic.com/randb/eRandB_Ed.D_BillOfMaterials.xls Bill of Materials (xls)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_PCB.pdf PCB (pdf)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_HardwareSourceFiles.zip Hardware source files(zip)]
* [https://projects.gctronic.com/randb/eRandB_Ed.D_Fabrication.zip Fabrication: Gerber, pick and place, ... (zip)]
* [https://projects.gctronic.com/randb/eRandB_manual.pdf e-RandB manual (pdf)]
* [https://projects.gctronic.com/randb/eRandB_firmware.zip e-RandB firmware (zip)]
* [https://projects.gctronic.com/randb/eRandB_software.tgz e-puck software and examples (tgz)]


=Getting started=
You can find more information about this board in the following links: [http://www.e-puck.org/index.php?option=com_content&view=article&id=35&Itemid=23 http://www.e-puck.org/index.php?option=com_content&view=article&id=35&Itemid=23].
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/>


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 following table lists the I2C the registers map:
 
<blockquote>
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/>
{| border="1" cellpadding="10" cellspacing="0"
The following sections assume the full configuration (robot + extension), unless otherwise stated.
!Address !!Read !!Write
 
|-
==Requirements==
|0 || 1 if data available, 0 otherwise || -
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.
|-
 
|1 || data MSB || -
===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].
|2 || data LSB || -
 
|-
===e-puck2===
|3 || bearing MSB || -
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/>
|-
 
|4 || bearing LSB: <code>double((MSB<<8)+LSB)*0.0001</code> to get angle in degrees|| -
==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/>
|5 || range MSB || -
<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/>
|-
 
|6 || range LSB || -
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>
|-
 
|7 || max peak (adc reading) MSB || -
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).
|-
 
|8 || max peak (adc reading) LSB || -
==Console mode==
|-
The Pi-puck extension board comes with a pre-configured system ready to run without any additional configuration.<br/>
|9 || sensor that received the data (between 0..11) || -
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/>
|12 || - || Set transmission power (communication range): between 0 (max range) and 255 (min range)
<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/>
|13 || - || data LSB (prepare)
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/>
|14 || - || data MSB (send <code>(MSB<<8)+LSB</code>)
 
|-
==Battery charge==
|16 || - || 0 store light conditions (calibration)
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/>
|17 || - || 1=onboard calculation, 0=host calculation
<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/>
|-
 
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/>
 
==Reset button==
A button is available to reset the robot, when pressed it will resets only the robot restarting its firmware. This is useful for instance during development or for specific demos in which a restart of the robot is needed. In these cases you don't need to turn off completely the robot (and consequently also the Pi-puck if energy is supplied by the robot) but instead you can simply reset the robot. The position of the reset button is shown in the following figure:<br/>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pipuck_reset.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pipuck_reset-small.png">]</span><br/>
 
=How to communicate with the robot and its sensors=
==Communicate with the e-puck1==
Refer to the repo [https://github.com/yorkrobotlab/pi-puck-e-puck1 https://github.com/yorkrobotlab/pi-puck-e-puck1].
 
==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/>
The same example is also available in Python, you can run it by issueing <code>python3 e-puck2_test.py</code>.
 
===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]
</blockquote>
* Speaker: sound 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):
==Firmware source code==
{| border="1"
| 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)


==Communicate with the IMU==
===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 <code>/home/pi/Pi-puck/e-puck1/</code>.<br/>
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/>


===e-puck2===
==e-puck 1==
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/>
A simple [https://projects.gctronic.com/randb/test-eRandB.zip MPLAB project] was created to let start using these modules. With the selector it's possible to choose whether the robot is an emitter (selector in position 0) or a receiver (selector in position 1). The receiver will send the information (data, bearing, distance, sensor) through Bluetooth.
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/>
The same example is also available in Python, you can run it by issueing <code>python3 e-puck2_imu.py</code>.


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


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/>
=Ground sensors=
<span class="plainlinks">[http://www.gctronic.com/doc/images/E-puck-groundsensors.jpg <img width=200 src="http://www.gctronic.com/doc/images/E-puck-groundsensors.jpg">]</span>


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/>
The factory firmware of both the e-puck1 and e-puck2 supports the ground sensors extension: for e-puck1 refer to the section [https://www.gctronic.com/doc/index.php?title=E-Puck#Standard_firmware Standard firmware], for e-puck2 refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware Factory firmware].
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]).


==Capture an image==
Once the robot is programmed with its factory firmware, you can get the values from the ground sensors through Bluetooth by putting the selector in position 3 and issueing the command <code>m</code> that will return 5 values, the first 3 values are related to the ground sensors (left, center, right), the last 2 values are related to the cliff extension (if available).<br/>
The robot camera is connected to the Pi-puck extension as a USB camera, so you can access it very easily.<br/>
For more information about the Bluetooth connection refer to section [https://www.gctronic.com/doc/index.php?title=E-Puck#Getting_started Getting started] (e-puck1) or [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth Connecting to the Bluetooth] (e-puck2).<br/>
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/>
For more information about the Bluetooth protocol refer to section [https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol Advanced sercom protocol].
You can build the program with the command <code>g++ $(pkg-config --libs --cflags opencv) -ljpeg -o snapshot snapshot.cpp</code>.<br/>
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'''.<br/>
The same example is also available in Python, you can run it by issueing <code>python3 snapshot.py</code>.


==Communicate with the ground sensors extension==
If you couple the e-puck extension for Gumstix Overo with the ground sensor refer to the section [http://www.gctronic.com/doc/index.php/Overo_Extension#Ground_sensor http://www.gctronic.com/doc/index.php/Overo_Extension#Ground_sensor] to have an example on how to read the sensor values.
Both e-puck1 and e-puck2 support the [https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors ground sensors extension].<br/>
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 same example is also available in Python, you can run it by issueing <code>python3 groundsensor.py</code>.


==Wireless remote control==
You can find more information about the ground sensors extension module in the following link [http://www.e-puck.org/index.php?option=com_content&view=article&id=17&Itemid=18 http://www.e-puck.org/index.php?option=com_content&view=article&id=17&Itemid=18].<br/>
If you want to control the robot from a computer, for instance when you have an algorithm that requires heavy processing not suitable for the Pi-puck or when the computer acts as a master controlling a fleet of robots that return some information to the controller, then you have 3 options:<br/>
1) The computer establishes a WiFi connection with the Pi-puck to receive data processed by the Pi-puck (e.g. results of an image processing task); at the same time the computer establishes a Bluetooth connection directly with the e-puck2 robot to control it.
:''Disadvantages'':
:- the Bluetooth standard only allow up to seven simultaneous connections
:- doubled latency (Pi-puck <-> pc and pc <-> robot)
2) The computer establishes a WiFi connection with both the Pi-puck and the e-puck2 robot.
:''Advantages'':
:- only one connection type needed, easier to handle
:''Disadvantages'':
:- doubled latency (Pi-puck <-> pc and pc <-> robot)
3) The computer establishes a WiFi connection with the Pi-puck and then the Pi-puck is in charge of controlling the robot via I2C based on the data received from the computer controller.
:''Advantages'':
:- less latency involved
:- less number of connections to handle
:- depending on your algorithm, it would be possible to initially develop the controller on the computer (easier to develop and debug) and then transfer the controller directly to the Pi-puck without the need to change anything related to the control of the robot via I2C


The following figure summarizes these 3 options:<br/>
==Assembly for e-puck2==
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/wireless-remote-control-options.png <img width=600 src="http://projects.gctronic.com/epuck2/wiki_images/wireless-remote-control-options.png">]</span>
<span class="plainlinks"><table><tr><td align="center">[1]</td><td align="center">[2]</td><td align="center">[3.1]</td><td align="center">[3.2]</td><td align="center">[3.3]</td><td align="center">[3.4]</td></tr><tr><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-2_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.2.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.3.jpeg <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.3_small.jpeg">][https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.4.jpeg <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.4_small.jpeg">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.5.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-3.5.png">]</td></tr><tr><td align="center">[4]</td><td align="center">[5.1]</td><td align="center">[5.2]</td><td align="center">[5.3]</td><td align="center">[5.4]</td><td align="center">[6]</td></tr><tr><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-4.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-4_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.1.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.1_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.2.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.2_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.3.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.3_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.4.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-5.4_small.png">]</td><td align="center">[https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-6.png <img height=200 src="https://projects.gctronic.com/epuck2/wiki_images/ground-assembly-6_small.png">]</td></tr></table></span>
# Unscrew the 3 spacers and remove the battery.
# Remove the top side from the case body gently.
# Detach the plastic camera adapter from the camera with the help of pliers; be careful to not stress the camera flex cable. Then you need to cut off the two protruding pieces (see 3.2) on the back of the plastic adapter; for this operation you can use nippers (see 3.3). Take the adapter (now is flat on the back as shown in 3.4) and insert it as before.
# Plug the ground module into its connector on the e-puck2; make the cable pass through the battery contact.
# First push the ground module within its slot in the body case, then slide in also the top side of the robot paying attention to the motors wires position: the back battery contact must remain between the body and motors wires and make sure the wires aren't stuck in the springs. Both the ground cable and camera flex cable must bend forming an "S" shape.
# Push the top all way down, then remount the spacers and plug in the battery. You're done.


=How to work with the Pi-puck=
=Cliff sensor=
==Demos and scripts update==
The cliff module extends the capability of the groundsensor with two additional sensors placed in front of the wheels. One possible application is that the e-puck can now detect the end of a table and react accordingly. Moreover this module can be coupled with the automatic charger for the e-puck, that could let the robot autonomously charge itself when needed. The two spring contacts adapt only to the cliff module.
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/>
To update the repository follow these steps:<br/>
1. go to the directory <code>/home/pi/Pi-puck</code><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/>


==Audio recording==
==Assembly==
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/>
<span class="plainlinks"><table><tr><td align="center">[1]</td><td align="center">[2]</td><td align="center">[3]</td><td align="center">[4.1]</td><td align="center">[4.2]</td></tr><tr><td>[http://www.gctronic.com/doc/images/cliff-mounting-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-2-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-3.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-3-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-4-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-4-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-4-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-4-2-small.jpg">]</td></tr><tr><td align="center">[5.1]</td><td align="center">[5.2]</td><td align="center">[6]</td><td align="center">[7]</td><td align="center">[8]</td></tr><tr><td>[http://www.gctronic.com/doc/images/cliff-mounting-5-1.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-5-1-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-5-2.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-5-2-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-6.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-6-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-7.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-7-small.jpg">]</td><td>[http://www.gctronic.com/doc/images/cliff-mounting-8.jpg <img height=200 src="http://www.gctronic.com/doc/images/cliff-mounting-8-small.jpg">]</td></tr></table></span>
<code>arecord -Dmic_mono -c1 -r16000 -fS32_LE -twav -d2 test.wav</code><br/>
# Unscrew the 3 screws, unmount the e-jumper (top piece where there is the speaker) and unscrew the 3 spacers
You can also specify a rate of 48 KHz with <code>-r48000</code>
# Remove the pcb from the case body gently
 
# Detach the two parts, cliff and ground pcb
==Audio play==
# Plug the ground module into its connector on the e-puck
Use <code>aplay</code> to play <code>wav</code> files and <code>mplayer</code> to play <code>mp3</code> files.
# Attach the cliff module to the ground module being careful to leave the battery contact in the middle
 
# Push the ground module within its slot in the body case, the cliff module will remain external
==Battery reading==
# Once both the modules are aligned, push them down
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/>
# The modules will remain really close to the case bottom; once the modules are fitted remount the spacers, the e-jumper and the screws
The first 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/>
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.
 
==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. For more information about ''wpa_supplicant'' refer to [https://hostap.epitest.fi/wpa_supplicant/ https://hostap.epitest.fi/wpa_supplicant/].
 
Once the configuration is done, you can also connect to the Pi-puck with <code>SSH</code>. If you are working in Windows you can use [https://www.putty.org/ PuTTY].
 
===How to know your IP address===
A simple method to know your IP address is to connect the USB cable to the Pi-puck extension and issue the command <code>ip a</code>; from the command's result you will be able to get you current assigned IP address.
 
If you prefer to know your IP address remotely (without connecting any cable) then you can use <code>nmap</code>.<br/>
For example you can search all connected devices in your network with the following command: <code>nmap 192.168.1.*</code>. Beware that you need to specify the subnet based on your network configuration.<br/>
From the command's result you need to look for the hostname <code>raspberrypi</code>.<br/>
If you are working in Windows you can use the [https://nmap.org/zenmap/ Zenmap] application.
 
==File transfer==
===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/>
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/>
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/>
<!--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/>-->
Example of receiving a file from the computer using the <code>Minicom</code> terminal program:<br/>
1. in the Pi-puck console type <code>rx -Z</code><br/>
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/>
===WiFi===
The Pi-puck extension supports <code>SSH</code> connections.<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>


If you are working in Windows you can use [https://www.putty.org/ PuTTY].
==Electrical schema==
 
The circuit diagram of the e-puck cliff extension is available to the community on the following link [https://projects.gctronic.com/cliff-sensor/CliffSensorV1.0.pdf electrical schema].  
==Image streaming==
 
 
==Bluetooth LE==
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/>
To start the service you need to type: <code>python uart_peripheral.py</code>.<br/>
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.
 
=Operating system=
The system is based on Raspbian Stretch and can be downloaded from the following link [http://projects.gctronic.com/epuck2/PiPuck/pi-puck-os_16.12.19.zip pi-puck-os_16.12.19.zip].
 
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/>
1. <code>sudo raspi-config</code><br/>
2. Select <code>Advanced Options</code> and then <code>Expand Filesystem</code><br/>
3. reboot
 
==e-puck2 camera configuration==
The e-puck2 camera need to be configured through I2C before it can be used. For this reason a Python script is called at boot that detects and configures the camera. The script resides in the Pi-puck repository installed in the system (<code>/home/pi/Pi-puck/camera-configuration.py</code>), so beware to not remove it.
 
If the robot is plugged after the boot process is completed, you need to call manually the Python configuration script before using the camera by issueing the command <code>python3 /home/pi/Pi-puck/camera-configuration.py</code>.
 
In order to automatically run the script at boot, the <code>/etc/rc.local</code> was modified by adding the call to the script just before the end of the file.
 
==Power button handling==
The power button press is handled by a background service (<code>systemd</code>) started automatically at boot. The service description file is located in <code>/etc/systemd/system/power_handling.service</code> and it calls the <code>/home/pi/power-handling/</code> program. Beware to not remove neither of these files.<br/>
The source code of the power button handling program is available in the Pi-puck repository and is located in <code>/home/pi/Pi-puck/power-handling/power-handling.c</code>.
 
==Desktop mode==
The system starts in console mode, to switch to desktop (LXDE) mode issue the command <code>startx</code>.
===Camera viewer===
A camera viewer called <code>luvcview</code> is installed in the system. You can open a terminal and issue simply the command <code>luvcview</code> to see the image coming from the robot camera.
 
==VNC==
[https://www.realvnc.com/en/ VNC] is a remote control desktop application that lets you connect to the Pi-puck from your computer and then you will see the desktop of the Pi-puck inside a window on your computer. You'll be able to control it as though you were working on the Pi-puck itself.<br/>
VNC is installed in the system and the ''VNC server'' is automatically started at boot, thus you can connect with ''VNC Viewer'' from your computer by knowing the IP address of the Pi-puck (refer to section [https://www.gctronic.com/doc/index.php?title=Pi-puck#How_to_know_your_IP_address How to know your IP address]).<br/>
Notice that the ''VNC server'' is started also in console mode.
 
==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 <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).
 
==Audio output configuration==
You can enable or disable audio output by modifying the <code>config.txt</code> file in the <code>boot</code> partition.<br/>
To enable audio output insert the line: <code>gpio=22=op,dh</code>
To disable audio output insert the line: <code>gpio=22=op,dl</code>
If you don't need to play audio files it is suggested to disable audio output in order to save power.
 
=ROS=
ROS Kinetic is integrated in the Pi-puck system.
==Initial configuration==
The ROS workspace is located in <code>~/rosbots_catkin_ws/</code><br/>
The e-puck2 ROS driver is located in <code>~/rosbots_catkin_ws/src/epuck_driver_cpp/</code><br/>
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/>
The PC (if used) and the Pi-puck extension are supposed to be configured in the same network.
 
==Running roscore==
<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>.
 
==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).
 
To start the e-puck2 ROS node issue the command:<br/>
<code>roslaunch epuck_driver_cpp epuck_minimal.launch debug_en:=true ros_rate:=20</code><br/>
<!--
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
-->
 
The following graph shows all the topics published by the e-puck2 driver node:<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>
''<font size="2">Click to enlarge</font>''
 
==Get the source code==
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><br/>
 
To update to the last version follow these steps:
# <code>cd ~/rosbots_catkin_ws/src/</code>
# <code>rm -R -f epuck_driver_cpp</code>
# <code>git clone -b pi-puck https://github.com/gctronic/epuck_driver_cpp.git</code>
# <code>cd ~/rosbots_catkin_ws/</code>
# <code>catkin_make --pkg epuck_driver_cpp</code>
 
==Python version==
A Python version developed by the York University can be found here [https://github.com/yorkrobotlab/pi-puck-ros https://github.com/yorkrobotlab/pi-puck-ros].
 
=OpenCV=
OpenCV 3.4.1 is integrated in the Pi-puck system.
 
=York Robotics Lab Expansion Board=
The York Robotics Lab developed an expansion board for the Pi-puck extension that includes: 9-DoF IMU, 5-input navigation switch, RGB LED, XBee socket, 24-pin Raspberry Pi compatible header. For more information have a look at [https://pi-puck.readthedocs.io/en/latest/extensions/yrl-expansion/ https://pi-puck.readthedocs.io/en/latest/extensions/yrl-expansion/].<br/>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/yrl-expansion-top.jpg <img width=350 src="http://projects.gctronic.com/epuck2/wiki_images/yrl-expansion-top.jpg">]</span><br/>
 
An example showing how to communicate with the YRL expansion board is available in the Pi-puck repository of the York Robotics Lab:
# <code> git clone https://github.com/yorkrobotlab/pi-puck.git pi-puck_yrl</code>
# <code>cd pi-puck_yrl/python-library</code>
# <code>python3 pipuck-library-test.py -x</code> Once started, press in sequence up, down, left, right, center to continue the demo.
 
==Assembly==
The assembly is very simple: place the YRL expansion board on top of the Raspberry Pi and then connect them with the provided screws. Once they are connected, you can attach both on top of the Pi-puck extension.<br/>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/yrl-exp1.jpg <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/yrl-exp1.jpg">]</span>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/yrl-exp2.jpg <img width=150 src="http://projects.gctronic.com/epuck2/wiki_images/yrl-exp2.jpg">]</span>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/yrl-exp3.jpg <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/yrl-exp3.jpg">]</span><br/>
==XBee==
In this section it is explained how to send data from the Pi-puck to the computer using XBee modules Series 1.


The XBee module mounted on the YRL expansion must be programmed with the <code>XBEE 802.15.4-USB ADAPTER</code> firmware; this can be done with the [http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/xctu XTCU software]. With XTCU be sure to program also the same parameters on both modules in order to be able to communicate between each other: <code>Channel</code> (e.g. <code>C</code>), <code>PAN ID</code> (e.g. <code>3332</code>), <code>DH = 0</code>, <code>DL = 0</code>, <code>MY = 0</code>.
==Software==
===e-puck firmware===
Refers to the section [http://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware E-Puck Standard firmware] for the firmware that need to be uploaded to the robot.
Essentially the standard ''asercom'' demo (selector 3) released with the e-puck robot is extended in order to request and visualize 5 sensors values instead of 3 when issueing the ''m'' command; the sequence is: ground left, ground center, ground right, cliff right, cliff left. In order to enable the cliff sensors you need to ''define CLIFF_SENSORS'' in the ''asercom.c'' file in order to build the code parts related to this module.


Some Python examples ara available in the [https://github.com/yorkrobotlab/pi-puck-expansion-board YRL Expansion Board GitHub repository] that can be used to communicate with the XBee module mounted on the YRL expansion. These examples are based on the [https://github.com/digidotcom/xbee-python Digi XBee Python library] that can be installed with the command <code>pip3 install digi-xbee</code>. This library requires the XBee module to be configured in API mode; you can setup this mode following these steps:
===e-puck demos===
# <code> git clone https://github.com/yorkrobotlab/pi-puck-expansion-board.git</code>
To demonstrate the capabilities of the cliff sensors module here is an MPLAB project [https://projects.gctronic.com/cliff-sensor/Demo-cliff-autocharge.zip Demo-cliff-autocharge.zip] that contains two demos:
# <code>cd pi-puck-expansion-board/xbee</code>
* selector 0: in this demo the robot is eventually piloted to the charger station autonomously after moving around for some time aovoiding obstacles; the demo is shown in the [http://www.gctronic.com/doc/index.php/Others_Extensions#Videos video section].<br/>
# <code>python3 xbee-enable-api-mode.py</code>
* selector 1: this is a cliff avoidance demo in which the robot is moved forward until it detects the end of the table and tries to avoid it moving back and rotating; the demo is shown in the [http://www.gctronic.com/doc/index.php/Others_Extensions#Videos video section].


Now connect the second module to the computer and run XTCU, select the console view and open the serial connection. Then run the [http://projects.gctronic.com/epuck2/PiPuck/xbee-send-broadcast.py xbee-send-broadcast.py] example from the Pi-puck by issuing the command: <code>python3 xbee-send-broadcast.py</code>. From the XTCU console you should receive <code>Hello Xbee World!</code>.
===Extension firmware===
The ground sensor fimrware developed at EPFL (can be downloaded at the [http://www.e-puck.org http://www.e-puck.org] site from [http://www.e-puck.org/index.php?option=com_phocadownload&view=category&id=9:ground-sensors&Itemid=38 this page]) was extended to interact with the additional two sensors. The source code can be downloaded from [https://projects.gctronic.com/cliff-sensor/pic18_floor_sensor_c18-cliff.zip cliff-firmware]; it is an MPLAB project and the MPLAB C Compiler for PIC18 MCUs is needed to build the project.<br/>
The communication between the e-puck and the module is handled through I2C (address 0xC0) and the following registers are defined:
* 0x00: reflected light, left IR sensor - high byte
* 0x01: reflected light, left IR sensor - low byte
* 0x02: reflected light, center IR sensor - high byte
* 0x03: reflected light, center IR sensor - low byte
* 0x04: reflected light, right IR sensor - high byte
* 0x05: reflected light, right IR sensor - low byte
* 0x06: ambient light, left IR sensor - high byte
* 0x07: ambient light, left IR sensor - low byte
* 0x08: ambient light, center IR sensor - high byte
* 0x09: ambient light, center IR sensor - low byte
* 0x0A: ambient light, right IR sensor - high byte
* 0x0B: ambient light, right IR sensor - low byte
* 0x0C: software revision number
* 0x0D: reflected light, right cliff sensor - high byte
* 0x0E: reflected light, right cliff sensor - low byte
* 0x0F: reflected light, left cliff sensor - high byte
* 0x10: reflected light, left cliff sensor - low byte
* 0x11: ambient light, right cliff sensor - high byte
* 0x12: ambient light, right cliff sensor - low byte
* 0x13: ambient light, left cliff sensor - high byte
* 0x14: ambient light, left cliff sensor - low byte


For more information refer to [https://pi-puck.readthedocs.io/en/latest/extensions/yrl-expansion/xbee/ https://pi-puck.readthedocs.io/en/latest/extensions/yrl-expansion/xbee/].
===e-puck2 demos===
The same demo developed for the e-puck1 that let the robot autonomously reach the charging station and charge itself is available also for the e-puck2. You can find the source code in the following repository [https://github.com/e-puck2/e-puck2_cliff_autocharge https://github.com/e-puck2/e-puck2_cliff_autocharge].


=Time-of-Flight Distance Sensor add-on=
==Images==
The Pi-puck extension integrates six sensor board sockets that can be used to add up to six VL53L1X-based distance sensor add-ons. The Pi-puck equipped with these add-ons is shown in the following figure:<br/>
Robot equipped with the cliff sensor: <br/>
<span class="plainlinks">[http://projects.gctronic.com/epuck2/wiki_images/pi-puck-tof.jpg <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/pi-puck-tof.jpg">]</span><br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff+charger.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff+charger.jpg">]</span> <br/>
For more information have a look at [https://pi-puck.readthedocs.io/en/latest/extensions/tof-sensor/#time-of-flight-distance-sensor https://pi-puck.readthedocs.io/en/latest/extensions/tof-sensor/#time-of-flight-distance-sensor].


<font style="color:red"> Beware that once the socket for the ToF add-on sensor '''3''' is soldered on the pi-puck extension, you are no more able to connect the HDMI cable.</font>
The robot can be easily moved to the charging station as shown in the following figure: <br/>
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff-charging.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff-charging.jpg">]</span> <br/>


==Communicate with the ToF sensors==
The following figure shows the two additional sensors (near the wheels) mounted on the cliff module and the three frontal sensors of the ground module: <br/>
In order to communicate with the sensors you can use the <code>multiple-i2c-bus-support</code> branch of the [https://github.com/pimoroni/vl53l1x-python vl53l1x-python] library from [https://shop.pimoroni.com/ Pimoroni]. To install this library follow these steps:
<span class="plainlinks">[http://www.gctronic.com/doc/images/Cliff-zoom.jpg <img width=300 src="http://www.gctronic.com/doc/images/Cliff-zoom.jpg">]</span> <br/>
# <code>git clone -b multiple-i2c-bus-support https://github.com/pimoroni/vl53l1x-python.git</code>
# <code>cd vl53l1x-python</code>
# <code>sudo python3 setup.py install</code>


A Python example showing how to read data from the ToF sensors is available in the Pi-puck repository of the York Robotics Lab:
==Videos==
# <code> git clone https://github.com/yorkrobotlab/pi-puck.git pi-puck_yrl</code>
{{#ev:youtube|7iFmLBng3qg}}
# <code>cd pi-puck_yrl/python-library</code>
{{#ev:youtube|NYOcb1QoUTM}}
# <code>python3 pipuck-library-test.py -t</code>

Revision as of 09:00, 17 December 2021

Range and bearing


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

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

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

The following table lists the I2C the registers map:

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

Firmware source code

e-puck 1

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

e-puck 2

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

Ground sensors

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

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

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

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

Assembly for e-puck2

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

Cliff sensor

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

Assembly

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

Electrical schema

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

Software

e-puck firmware

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

e-puck demos

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

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

Extension firmware

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

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

e-puck2 demos

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

Images

Robot equipped with the cliff sensor:

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

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

Videos

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