|
|
| Line 1: |
Line 1: |
| [{{fullurl:e-puck2}} e-puck2 main wiki]<br/>
| | =Overview= |
| =Introduction= | | <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 <code>C programming</code> language is used to develop code for the main microcontroller of the e-puck2 robot. The [http://www.chibios.org ChibiOS] embedded real-time OS was chosen to be integrated in the firmware, since it support the STM32F4 family of microprocessors, it includes an HAL (Hardware Abstraction Layer), it's well documented and finally it's free.<br>
| | Features: |
| Before starting to code, you need to install the developing environment and its dependencies, all the steps are documented afterwards.<br>
| | * Raspberry Pi zero W (rPi) connected to the robot via I2C |
| The factory firmware integrates both the e-puck2 library used to handle all the sensors and actuators together with a series of demos that use this library. Thus you can either take the factory firmware and directly modify its main, otherwise you can start a fresh new project by linking the factory firmware project as an external library.<br>
| | * interface between the robot base camera and the rPi via USB |
| You can also modify the library itself, but before digging into the details, try to contact us, maybe we're already working on that subject or we can help you.
| | * 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 |
|
| |
|
| =Installation of the e-puck2 environment= | | =Getting started= |
| <code>Eclipse_e-puck2</code> is a distribution of Eclipse IDE for C/C++ Developers specially modified to edit and compile e-puck2's projects out of the box. It doesn't require to be installed and everything needed is located in the package given. The only dependency needed to be able to run Eclipse is '''Java'''.
| | 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 demos and scripts shipped with the system flashed on the micro SD. The extension is mostly an interface between the e-puck robot and the Raspberry Pi.<br/> |
|
| |
|
| ==Installation for Windows==
| | 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/> |
| ===Java 8 32bits===
| | The following sections assume the full configuration (robot + extension), unless otherwise stated. |
| This section can be ignored if Java version >= 8 32bits is already installed on your computer.<br>
| |
| To verify you already installed Java, you can open <code>Programs and Features</code> from the <code>control panel</code> and search for a <code>Java 8 Update xxx</code> install. If this entry isn't present, then you need to install it:
| |
|
| |
|
| #Go to the [https://www.java.com/en/download/manual.jsp Java download page] and download the <code>Windows offline</code> pacakge. This is the 32bits version of Java.
| | ==Requirements== |
| #Run the downloaded installer and follow its instructions to proceed with the installation of Java 32bits.
| | 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. |
| #Close the internet browser if it opened at the end of the installation.
| | ===e-puck1=== |
|
| |
|
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_windows.png">]</span><br/>
| | ===e-puck2=== |
| :''Java download page''
| | The e-puck2 robot must be programmed with the following firmware [http://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_gumstix_c35e8da_06.11.18.elf e-puck2_main-processor_gumstix.elf] and the selector must be placed in position 10.<br/> |
| | This is needed in order to exchange data with the robot through I2C. |
|
| |
|
| ===Eclipse_e-puck2=== | | ==Console mode== |
| #Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Win32_11_apr_2018.zip Eclipse_e-puck2 package for windows].
| | The Pi-puck extension board comes with a pre-configured system ready to run without any additional configuration.<br/> |
| #Unzip the downloaded file to the location you want (can take time). It is strongly recommended for better performance and less extraction time to use 7Zip. You can download it on http://www.7-zip.org.
| | In order to access the system from a PC in console mode, the following steps must be performed:<br/> |
| #You can now run the <code>Eclipse_e-puck2.exe</code> to launch Eclipse.
| | 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/> |
| #You can create a shortcut to <code>Eclipse_e-puck2.exe</code> and place it anywhere if you want.
| | 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 extensino 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/> |
|
| |
|
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Windows.png">]</span><br/>
| | =Operating system= |
| :''Eclipse_e-puck2 folder obtained after extraction''
| | 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]. |
|
| |
|
| '''Important things to avoid :'''
| | user/pw: pi/raspberry<br/> |
| :1. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.
| | The system starts in console mode, to switch to desktop (LXDE) mode issue the command <code>startx</code>. |
| ::Example :
| |
| ::<code>C:\epfl_stuff\Eclipse_e-puck2</code> OK
| |
| ::<code>C:\epfl stuff\Eclipse_e-puck2</code> NOT OK
| |
| :2. You must not put <code>Eclipse_e-puck2</code> folder into <code>Program Files (x86)</code>. Otherwise the compilation when using Eclipse will not work. | |
| :3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.
| |
|
| |
|
| ===Configuring the PATH variable===
| | 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/> |
| The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
| | 1. <code>sudo raspi-config</code><br/> |
| | 2. Select <code>Advanced Options</code> and then <code>Expand Filesystem</code><br/> |
| | 3. reboot |
|
| |
|
| If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
| | ==Startup configuration== |
| | The following scripts need to be executed at each startup, alternatively you can set to run them automatically at startup: |
| | * <code>/home/pi/i2c_enable</code> |
| | : this is neeeded to enable the I2C bus |
| | * <code>sudo python3 /home/pi/camera-test.py</code> |
| | : this is needed to correctly configure the camera of the robot |
|
| |
|
| <code>set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%</code>
| | =Robot configuration= |
| | ==e-puck1== |
|
| |
|
| What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
| | ==e-puck2== |
| | The e-puck2 robot must be programmed with the following firmware [http://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_gumstix_c35e8da_06.11.18.elf e-puck2_main-processor_gumstix.elf] and the selector must be placed in position 10.<br/> |
| | This is needed in order to exchange data with the robot through I2C. |
|
| |
|
| If you want to set the <code>PATH</code> variable permanently, then go to <code>Control panel</code> => <code>System</code> => <code>Advanced system settings</code> => <code>Environment variables</code>. A list of variables defined for the user is shown, double click on the <code>PATH</code> variable (from the user variables list) and add at the end <code>;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin</code>, then click <code>OK</code> three times.
| | =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/> |
| | Follow the steps in the section [http://www.gctronic.com/doc/index.php?title=Pi-puck#Robot_configuration Robot configuration], only once.<br/> |
| | Follow the steps in the section [http://www.gctronic.com/doc/index.php?title=Pi-puck#Startup_configuration System: Startup configuration], each time the system is powered on.<br/> |
| | The PC (if used) and the Pi-puck extension are supposed to be configured in the same network. |
|
| |
|
| Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
| | ==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>. |
|
| |
|
| ==Installation for Linux== | | ==Running the ROS node== |
| ===Java 8===
| | Before starting the e-puck2 ROS node on the Pi-puck, issue the following commands: |
| This section can be ignored if Java is already installed on your computer.<br>
| | * <code>export ROS_IP=pipuck-ip</code> |
| To verify whether it is installed or not you can type the following command into a terminal window: <code>update-java-alternatives -l</code>. If Java is installed, you will get some information about it, otherwise the command will be unknown.<br>
| | * <code>export ROS_MASTER_URI=http://roscore-ip:11311</code> |
| You need to have <code>Java 1.8.xxxx</code> listed to be able to run <code>Eclipse_e-puck2</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). |
|
| |
|
| Type the following commands in a terminal session to install Java SDK:
| | To start the e-puck2 ROS node issue the command:<br/> |
| <pre>sudo add-apt-repository ppa:openjdk-r/ppa | | <code>roslaunch epuck_driver_cpp epuck_minimal.launch debug_en:=true ros_rate:=20</code><br/> |
| sudo apt-get update
| | <!-- |
| sudo apt-get install openjdk-8-jre </pre>
| | 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 |
| | --> |
|
| |
|
| ===Eclipse_e-puck2===
| | The following graph shows all the topics published by the e-puck2 driver node:<br/> |
| #Install <code>make</code> (probably you already have it installed) by issueing the command: <code>sudo apt-get install make</code>
| | <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> |
| #Download the Eclipse_e-puck2 package for Linux [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz 32bits] / [http://projects.gctronic.com/epuck2//Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_64bits.tar.gz 64bits]. Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand <code>uname -a</code> in the terminal window and look for <code>i686</code> (32bit) or <code>x86_64</code> (64 bit).
| | ''<font size="2">Click to enlarge</font>'' |
| #Extract the downloaded file to the location you want (can take time): <code>tar -zxvf package_name.tar.gz</code>
| |
| #You can now run the <code>Eclipse_e-puck2</code> executable to launch Eclipse.
| |
|
| |
|
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png <img width=800 src="http://projects.gctronic.com/epuck2/wiki_images/Eclipse_e-puck2_Folder_Linux.png">]</span><br/> | | ==Get the source code== |
| :''Eclipse_e-puck2 folder obtained after extraction''
| | The last version of the e-puck2 ROS node can be downloaded from the git: <code>git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp.git</code> |
|
| |
|
| Note : The icon of the <code>Eclipse_e-puck2</code> executable will appear after the first launch of the program.
| | =OpenCV= |
| | OpenCV 3.4.1 is integrated in the Pi-puck system. |
|
| |
|
| '''Important things to avoid :'''
| | ==Blob tracking== |
| :1. You cannot create a Link to the <code>Eclipse_e-puck2</code> executable because otherwise the program will think its location is where the Link is and it will not find the resources located in the <code>Eclipse_e-puck2</code> folder.
| | A simple demo was developed to track an orange blob. It is thought to be run with the omnivision extension. The robot rotate in place towards the target when it finds one.<br/> |
| :2. The path to the <code>Eclipse_e-puck2</code> folder must contain zero space.
| | The code can be downloaded from the following repo: <code>git clone https://github.com/e-puck2/e-puck2_pi_blob-tracking.git</code> |
| ::Example :
| |
| ::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
| |
| ::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
| |
| :3. The file’s structure in the <code>Eclipse_e-puck2</code> folder must remain the same. It means no file inside this folder must be moved to another place.
| |
| | |
| ===Configuring the PATH variable=== | |
| The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
| |
| | |
| If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
| |
| | |
| <code>export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
| |
| | |
| What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
| |
| | |
| If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.profile</code> file by issuing the command:<br>
| |
| <code>echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile</code><br>
| |
| Close and reopen the terminal before using your newly set environment variable.
| |
| | |
| Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
| |
| | |
| ==Installation for Mac==
| |
| ===Command Line Tools ===
| |
| To compile on Mac with <code>Eclipse_e-puck2</code>, it is necessary to have the <code>Command Line Tools</code> installed. It is a bundle of many commonly used tools.<br>
| |
| You can install it by typing the following command in a terminal window: <code>xcode-select --install</code>. It will then open a popup asking you if you want to install this bundle. Otherwise it will tell you it is already installed.
| |
| | |
| ===Java 8===
| |
| This section can be ignored if Java is already installed on your computer.<br>
| |
| To verify whether it is installed or not you can type the following command into a terminal window. It will list all the Java runtimes installed on your Mac: <code>/usr/libexec/java_home -V</code><br>
| |
| You need to have <code>Java SE 8</code> listed to be able to run <code>Eclipse_e-puck2</code>.
| |
| | |
| :1. Go to the [http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html Java download page] and download the <code>Mac OS X Java 8 SE Development Kit</code>. It is the <code>.dmg</code> file without the Demos and Samples.
| |
| ::For example: <code>jdk-8uXXX-macosx-x64.dmg</code>
| |
| :2. Open the <code>.dmg</code> file downloaded, run the installer and follow the instructions to proceed with the installation of Java SDK.
| |
| | |
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/Java_mac.png">]</span><br/>
| |
| :''Java download page''
| |
| | |
| ===Eclipse_e-puck2===
| |
| :1. Download the [http://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_11_apr_2018.dmg Eclipse_e-puck2 package for Mac].
| |
| :2. Open the <code>.dmg</code> file downloaded (confirm opening if a warning message appear) and ''drag and drop'' the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder
| |
| ::Note: you can place the <code>Eclipse_e-puck2.app</code> anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in <code>Applications</code>.
| |
| :3. You can create an Alias to <code>Eclipse_e-puck2.app</code> and place it anywhere if you want.
| |
| | |
| ===First launch and Gatekeeper===
| |
| It’s very likely that <code>Gatekeeper</code> (one of the protections of Mac OS) will prevent you to launch <code>Eclipse_e-puck2.app</code> because it isn’t signed from a known developer.<br>
| |
| If you can’t run the program because of a warning of the system, press <code>OK</code> and try to launch it by right clicking on it and choosing <code>open</code> in the contextual menu (may be slow to open the first time).<br>
| |
| If <code>Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.</code> or if <code>"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.</code> appears after executing the app the first time, it is needed to disable temporarily <code>Gatekeeper</code>.
| |
| | |
| To do so :
| |
| | |
| :1. Go to <code>System Preferences->security and privacy->General</code> and authorize downloaded application from <code>Anywhere</code>.
| |
| | |
| ::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/security_tab_mac.png">]</span><br/>
| |
| ::''Security settings of Mac OS''
| |
| | |
| ::If you are on Mac OS Sierra or greater (greater or equal to Mac OS 10.12), you must type the following command on the terminal to make the option above appear.
| |
| ::<code>sudo spctl --master-disable</code>
| |
| :2. Now you can try to run the application and it should work.
| |
| :3. If Eclipse opened successfully, it is time to reactivate <code>Gatekeeper</code>. Simply set back the setting of <code>Gatekeeper</code>.
| |
| ::For the ones who needed to type a command to disable <code>Gatekeeper</code>, here is the command to reactivate it.
| |
| ::<code>sudo spctl --master-enable</code>
| |
| | |
| This procedure is only needed the first time. After that <code>Gatekeeper</code> will remember your choice to let run this application and will not bother you anymore, as long as you use this application. If you re-download it, you will have to redo the procedure for <code>Gatekeeper</code>.
| |
| | |
| '''Important things to avoid :'''
| |
| :1. The path to the <code>Eclipse_e-puck2.app</code> must contain zero space.
| |
| ::Example :
| |
| ::<code>/home/student/epfl_stuff/Eclipse_e-puck2</code> OK
| |
| ::<code>/home/student/epfl stuff/Eclipse_e-puck2</code> NOT OK
| |
| :2. The file’s structure in the <code>Eclipse_e-puck2.app</code> must remain the same. It means no file inside this app must be moved to another place.
| |
| | |
| ===Configuring the PATH variable===
| |
| The <code>PATH</code> variable is an environment variable used to store a list of the paths to the folders containing the executables we can then run in a terminal from any path.
| |
| | |
| If you want to use the <code>arm-none-eabi</code> toolchain provided inside the <code>Eclipse_e-puck2</code> package, you have to add it to the <code>PATH</code> variable to be able to call it inside a terminal window. To set the <code>PATH</code> variable you need to issue the following command:
| |
| | |
| <code>export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
| |
| | |
| If you put the <code>Eclipse_e-puck2.app</code> into the <code>Applications</code> folder then the exact command would be:
| |
| | |
| <code>export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH</code>
| |
| | |
| What is important to know is that this procedure is temporary. It applies only to the terminal window used to type it. If you open a new terminal window or close this one, you will have to set again the <code>PATH</code> variable.
| |
| | |
| If you want to set the <code>PATH</code> variable permanently, then you need to set it in the <code>.bash_profile</code> file by issuing the command:<br>
| |
| <code>echo 'export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.bash_profile</code><br>
| |
| Close and reopen the terminal before using your newly set environment variable.
| |
| | |
| Note : The <code>arm-none-eabi</code> version can differ from the one given in this example. It could be needed to adapt the path to the correct version.
| |
| | |
| =Get the source code=
| |
| The code of the e-puck2 is open source and is available as a git repository. To download the source code you need to install git on your system:
| |
| * Windows: downlaod git from [https://gitforwindows.org/ https://gitforwindows.org/] and follow the installation instructions (default configuration is ok)
| |
| * Linux: issue the command <code>sudo apt-get install git</code>
| |
| * Mac: issue the command <code>brew install git</code>
| |
| | |
| The source code can downloaded with the command: <code>git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git</code><br/>
| |
| The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.
| |
| | |
| This repository contains the main microcontroller factory firmware together with the e-puck2 library. This library includes all the functions needed to interact with the robot's sensors and actuators; the factory firmware shows how to use these functions.<br/>
| |
| | |
| A snapshot of the repository can be donwloaded from [http://projects.gctronic.com/epuck2/e-puck2_main-processor_snapshot_16.02.18_13fa922.zip e-puck2_main-processor_snapshot_16.02.18.zip].<br/>
| |
| | |
| =Creating a project=
| |
| ==Main microcontroller factory firmware project==
| |
| If you want to modify the code of the factory firmware running on the main microcontroller, or if you want to have a look at the implementation details, then you can add this project in Eclipse by following the next steps:<br/>
| |
| # Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
| |
| # Next click on the <code>Browse</code> button and choose the project folder of the git repository downloaded previously (should be named <code>e-puck2_main-processor</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
| |
| # Click on the <code>Finish</code> button and the project is added to Eclipse.
| |
| # Build the project by selecting one directory of the project from the left panel and then <code>Project->Build Project</code>.
| |
| | |
| ==Project template==
| |
| The main microcontroller factory firmware project can also be used as a library to build your own project on top of it.<br>
| |
| | |
| To accomplish that, you have to copy the folder <code>Project_template</code>, contained in the <code>e-puck2_main-processor</code> project, and place it in the same directory of the <code>e-puck2_main-processor</code> project; you can of course rename the folder to the name you want (e.g. <code>myproject</code>). You must end up with the following directory tree:<br>
| |
| * e-puck2
| |
| ** e-puck2_main-processor
| |
| ** myproject
| |
| | |
| Then you can add this project in Eclipse by following the next steps:
| |
| # Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
| |
| # Next click on the <code>Browse</code> button and choose the project folder of your project (e.g. <code>myproject</code>) and set a project name (otherwise you can keep the one created by Eclipse). Choose <code>None</code> for the the toolchain.
| |
| # Click on the <code>Finish</code> button and the project is added to Eclipse.
| |
| # Select the project root folder and go to <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
| |
| # Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
| |
| ##Select the project root folder and go to <code>File->New->Folder</code>.
| |
| ##Check <code>Advanced >></code> on the bottom.
| |
| ##Choose <code>Link to alternate location (Linked Folder)</code>.
| |
| ##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
| |
| # Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
| |
| # After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
| |
| | |
| Now you can write your own program. If you want to add source files (<code>.c</code>) to the project you need to add them also in the <code>makefile</code>, in the <code>CSRC</code> definition. All the headers files (<code>.h</code>) located next to the <code>makefile</code> are automatically included in the compilation, but if you need to place them into folders, you have to specify these folders in the <code>makefile</code>, in the <code>INCDIR</code> definition. The same is needed for any desired <code>.h</code> files from other external folders.<br/>
| |
| In the <code>makefile</code> you can also set the name of your project.<br/>
| |
| This <code>makefile</code> uses the main makefile of the <code>e-puck2_main-processor</code> project. This means you can add custom commands to the <code>makefile</code> but it should not interfere with the main makefile.
| |
| | |
| =Configuring the Debugger's settings=
| |
| <code>Eclipse_e-puck2</code> contains everything needed to compile, program and debug the e-puck2.<br>
| |
| The only settings to configure with a new project are located under the <code>Debug Configurations</code> tab of Eclipse (you can also find it on <code>Run->Debug Configurations</code>).
| |
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png <img width=231 src="http://projects.gctronic.com/epuck2/wiki_images/Debug_configuration.png">]</span><br/>
| |
| Once in the settings, select <code>Generic Blackmagic Probe</code> preset on the left panel. Then you need to configure two things :
| |
| | |
| # In the <code>main</code> tab, select which project to debug and the path to the compiled file. If the project has already been compiled, Eclipse should have indexed the binaries and you can list the project and the compiled files using respectively the <code>Browse...</code> and <code>Search Project...</code> buttons.<br/> If there is nothing apering when you press <code>Search Project...</code> then you must enter the <code>.elf</code> file name by hand, which can be found in your project <code>build</code> folder (e.g. <code>build/e-puck2_main-processor.elf</code>).
| |
| # In the <code>Startup</code> tab, you need to replace the serial port name written on the first line of the text box by the one used by the GDB Server of your robot. [http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used See how to find it].
| |
| :* For Windows, it will be <code>\\.\COMX</code>, <code>X</code> being the port number.
| |
| :* For Linux, it will be <code>/dev/ttyACMX</code>, <code>X</code> being the port number
| |
| :* For Mac, it will be <code>/dev/cu.usbmodemXXXXX</code>, <code>XXXXX</code> being the port number.
| |
| :* You can also type <code>${COM_PORT}</code> instead of the com port in order to use the variable <code>COM_PORT</code> for the debug configuration.<br>To change the value of this variable, go to the <code>main</code> tab again, click on the <code>Variables...</code> button and click on the <code>Edit Variables...</code> button. The opened window will let you edit the value of the variable.<br>Using the variable <code>COM_PORT</code> instead of the real com port in a debug configuration is useful if for example you have multiple debug configurations. If for some reason you need to change the serial port to use, then you can simply edit the variable <code>COM_PORT</code> instead of editing the serial port for each debug configuration.
| |
| | |
| If you want to debug another project, you can duplicate this settings and change the relevant parts (project name and path to compiled file) in order to have one launch configuration for each project.<br/>
| |
| :<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug.jpg <img width=400 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug-small.jpg">]</span><br/>
| |
| | |
| Now you should be able to use the debugger with Eclipse.
| |
| | |
| =Running a debugging session=
| |
| Once the debugger is configured, you can start a debugging session. When starting a session, the robot is programmed with the current developed program, thus starting a debugging session means also updating the main microcontroller firmware. This is in fact the way to update the firwmare via Eclipse; to do it manually refer to the section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update].
| |
| | |
| To start a session follow the next steps:
| |
| # Connect the robot to the computer and turn it on
| |
| # From Eclipse, launch the debug configuration previously set: from the menu <code>Run->Debug configurations...</code>, select the configuration and click on the <code>Debug</code> button.<br>Alternatively you can directly select your configuration from the debugger drop-down menu.<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png <img width=350 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug2.png">]</span><br/>
| |
| # When the debugging session is started, Eclipse will change the view to the <code>Debug perspective</code>. Right-click on the main process and select <code>Restart</code> to restart the program from the beginning<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug3-small.png">]</span>
| |
| # Click on the <code>Resume</code> button on top of the window to start your program. Now you can suspend and resume whenever you want, then when you want to modify your code again you click on the <code>Terminate</code> button and click on the <code>C/C++ perspective</code> button.<br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug4-small.png">]</span>
| |
| | |
| ==Adding breakpoints==
| |
| | |
| ==Watch variables==
| |
| | |
| ==Analyze microcontroller registers content==
| |
| When a debugging session is started, the microcontroller's registers state can be inspected by clicking on the <code>EmbSys Registers</code> tab on the top right side of the <code>Debug perspective</code>.
| |
| <br><span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug5.png <img width=500 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2-debug5-small.png">]</span>
| |
| | |
| =Example projects=
| |
| ==Digital Signal Processing (DSP) and wav playback==
| |
| In this example the [http://www.keil.com/pack/doc/CMSIS/DSP/html/index.html CMSIS-DSP] library is used to compute the Fast Fourier Transform of the signal coming from the microphones. The processing power of the main microntroller let the signal to be processed continuously. Moreover this example shows how to play wav files stored in the micro sd.<br/>
| |
| | |
| The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_example_dsp_05.10.18_3aa8b81.elf e-puck2_example_dsp.elf (05.10.18)].
| |
| | |
| ===Usage===
| |
| There are basically two demos in this example, one run on selector position 0 and the other in selector position 1.<br/>
| |
| | |
| When the selector is in position 0, then the resulting frequency (max amplitude bin) of the computed FFT is mapped to the RGB LEDs: LEDs will be blue when frequency detected is around 250..900 Hz, green when frequency is around 900..1500 Hz and red with 1500..2200 Hz. The brightness of the LEDs is also changed with the frequency.<br/>
| |
| The distance sensor (ToF) is also used to detect people in front of the robot. When someone is detected within 50 cm, then the measured distance is mapped to a frequency emitted through the speaker; the generated tone is between 260 Hz (far) and 2240 Hz (near). You can use your hand to play some melody, the robot in the meantime will detect the frequency and show it through the RGB.<br/>
| |
| | |
| When the selector is in position 1, the robot will play a wav file stored in the micro sd when one of the proximity sensors is "touched" (with your finger you go near the proximity and then you go away, like pressing a button). For each proximity there is a different wav file that will be played: for proximity 0 it will be played <code>0.wav</code>, for proximity 1 it will be played <code>1.wav</code> and so on till proximity 7 with <code>7.wav</code>.<br/>
| |
| | |
| All the wav files you need are stored in the <code>wav</code> directory within the project, put all of them in a micro sd partitioned in FAT32 and you're ready to go. Alternatively you can play your own wav files, beware to name them from <code>0.wav</code> to <code>7.wav</code> and they must be 16 KHz, mono.
| |
| | |
| ===Building===
| |
| First of all download the source code with the command: <code>git clone https://github.com/e-puck2/e-puck2_example_dsp.git</code><br/>
| |
| The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
| |
| Place the cloned repo folder <code>e-puck2_example_dsp</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
| |
| * e-puck2
| |
| ** e-puck2_main-processor
| |
| ** e-puck2_example_dsp
| |
| | |
| Then you can add this project in Eclipse by following the next steps:
| |
| # Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
| |
| # Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_dsp</code>. Choose <code>None</code> for the the toolchain.
| |
| # Click on the <code>Finish</code> button and the project is added to Eclipse.
| |
| # Select the project root folder and go to <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
| |
| # Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
| |
| ##Select the project root folder and go to <code>File->New->Folder</code>.
| |
| ##Check <code>Advanced >></code> on the bottom.
| |
| ##Choose <code>Link to alternate location (Linked Folder)</code>.
| |
| ##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
| |
| # Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
| |
| # After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
| |
| | |
| ==Microphones recording and pitch scaling==
| |
| This example shows how to record the audio (voice) from the onboard microphones and save it in the micro SD.<br/>
| |
| Moreover it applies a pitch scaling algorithm to the data before playing it from the micro SD.<br/>
| |
| The pitch scale processing is based on the SOLA algorithm and a simple implementation is available from the following link [https://www.surina.net/article/time-and-pitch-scaling.html https://www.surina.net/article/time-and-pitch-scaling.html]. Have a look at this site bacause it has a good explanation of the algorithm.<br/>
| |
| | |
| The pre-built firmware is available here [http://projects.gctronic.com/epuck2/e-puck2_example_pitch_scale_07.11.18_26d16f0.elf e-puck2_example_pitch_scale.elf (07.11.18)].
| |
| | |
| ===Usage===
| |
| The example requires a micro SD (FAT32) inserted in the robot.<br/>
| |
| | |
| When the robot is turned on, it waits for the button press that triggers the recording. The voice is recorded for about 2 seconds and saved into the micro SD as wav
| |
| file. Once the recording is finished, the pitch scale is applied and then the modified voice is played.<br/>
| |
| | |
| You can choose whether to get an higher or lower pitch by changing the <code>TIME_SCALE</code> parameter in <code>sola.c</code>:
| |
| * if you want to get an higher pitch, then change <code>TIME_SCALE</code> to a value > 1.0
| |
| * if you want to get a lower pitch, then change the <code>TIME_SCALE</code> to a value < 1.0
| |
| Of course, if the parameter is changed, you need to rebuild the project and reflash the robot.
| |
| | |
| ===Building===
| |
| First of all download the source code with the command: <code>git clone https://github.com/e-puck2/e-puck2_example_pitch_scale.git</code><br/>
| |
| The command must be issued in <code>Git bash</code> on Windows, or in a terminal on Linux / Mac.<br/>
| |
| Place the cloned repo folder <code>e-puck2_example_pitch_scale</code> in the same directory of the <code>e-puck2_main-processor</code> project; you must end up with the following directory tree:<br>
| |
| * e-puck2
| |
| ** e-puck2_main-processor
| |
| ** e-puck2_example_pitch_scale
| |
| | |
| Then you can add this project in Eclipse by following the next steps:
| |
| # Run Eclipse and then select <code>File->New->Makefile Project with Existing Code</code>.
| |
| # Next click on the <code>Browse</code> button and choose the project folder <code>e-puck2_example_pitch_scale</code>. Choose <code>None</code> for the the toolchain.
| |
| # Click on the <code>Finish</code> button and the project is added to Eclipse.
| |
| # Select the project root folder and go to <code>Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers</code> and check <code>CDT Cross GCC Built-in Compiler Settings</code>.<br> Then in the textbox below, write <code>arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"</code>.
| |
| # Create a linked folder inside your project that links to the <code>e-puck2_main-processor</code> library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library.
| |
| ##Select the project root folder and go to <code>File->New->Folder</code>.
| |
| ##Check <code>Advanced >></code> on the bottom.
| |
| ##Choose <code>Link to alternate location (Linked Folder)</code>.
| |
| ##Type <code>PROJECT_LOC/../e-puck2_main-processor</code> and click the <code>Finish</code> button.
| |
| # Build the project by selecting one file of the project from the left panel and then <code>Project->Build Project</code>. The result of the compilation will appear in the <code>build</code> folder in your project folder.
| |
| # After you compile the project, select the project root folder and go to <code>Project->C/C++ Index->Rebuild</code> to rebuild the index (we need to have compiled at least one time in order to let Eclipse find all the paths to the files used).
| |
| | |
| =Firmware update using factory bootloader=
| |
| This procedure should be used only if the normal firmware update steps described in the section [http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Main microcontroller: firmware update] don't work. This is a recovery procedure.<br/>
| |
| The programmer's microcontroller features a factory bootloader that can be entered by acting on some special pins, the bootloader mode is called DFU (device firmware upgrade). You can enter DFU mode by contacting two pinholes together while inserting the USB cable (no need to turn on the robot). The two pin holes are located near the USB connector of the e-puck2, see the photo below.
| |
| | |
| ::<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds_DFU_413.png <img width=200 src="http://projects.gctronic.com/epuck2/wiki_images/e-puck2_top_leds_DFU_413.png">]</span><br/>
| |
| ::''Location of the pin holes to put the programmer into DFU''
| |
| | |
| The programmer will be recognized as <code>STM Device in DFU Mode</code> device.
| |
| | |
| '''Note for Windows users''': the device should be recognized automatically (in all Windows versions), but in case it won't be detected then you need to install a <code>libusbK</code> driver for the DFU device.<br>
| |
| Follow the same procedure as explained in section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers Installing the USB drivers] using <code>libusbK</code> driver instead of <code>USB Serial (CDC)</code>.
| |
| | |
| ==Linux/Mac==
| |
| In order to update the programmer firmware you need an utility called <code>dfu-util</code>, it should be already installed from section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates].<br/>
| |
| To uplaod the firmware, issue the following command: <code>sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D programmer-firmware.bin</code>
| |
| | |
| ==Windows==
| |
| Start the <code>DfuSe</code> application (previously installed from section [http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates Installing the dependencies for firmwares updates]). The programmer in DFU mode will be automatically detected as shown in figure 1. Then you need to open the compiled firmware by clicking on <code>choose</code> and then locating the file with <code>dfu</code> extension, as shown in figure 2. Now click on the <code>upgrade</code> button, a warning message will be shown, confirm the action by clicking on <code>yes</code> as shown in figure 3. If all is ok you'll be prompted with a message saying that the upgrade was successfull as shown in figure 4.<br/>
| |
| <span class="plainlinks">
| |
| <table>
| |
| <tr>
| |
| <td align="center">[1]</td>
| |
| <td align="center">[2]</td>
| |
| <td align="center">[3]</td>
| |
| <td align="center">[4]</td>
| |
| </tr>
| |
| <tr>
| |
| <td>[http://projects.gctronic.com/epuck2/wiki_images/dfu1.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/dfu1.png">]</td>
| |
| <td>[http://projects.gctronic.com/epuck2/wiki_images/dfu2.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/dfu2.png">]</td>
| |
| <td>[http://projects.gctronic.com/epuck2/wiki_images/dfu3.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/dfu3.png">]</td>
| |
| <td>[http://projects.gctronic.com/epuck2/wiki_images/dfu4.png <img width=250 src="http://projects.gctronic.com/epuck2/wiki_images/dfu4.png">]</td>
| |
| </tr>
| |
| </table>
| |
| </span><br/>
| |
Click to enlarge