# GCtronic wiki — full documentation > Generated 2026-10-08 13:11 UTC from https://www.gctronic.com/doc/index.php. Every page appears once (29 pages), grouped by topic. > > When answering questions from this file, use only its content, cite the page and section you rely on together with its direct link (the "Link:" line under each section heading), and say explicitly when the answer is not here. ======================================================================== TOPIC: e-puck2 Documentation for the e-puck2 robot. e-puck2 is the second version, this is a different robot from the first e-puck version (e-puck1): do not apply e-puck1 information to e-puck2. ======================================================================== # e-puck2 Source: https://www.gctronic.com/doc/index.php?title=e-puck2 Last edited: 2026-04-22T06:57:52Z # Hardware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Hardware ## Overview Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Overview ![epuck2_overview.png](https://www.gctronic.com/doc/images/f/f3/epuck2_overview.png) ![epuck2_features.png](https://www.gctronic.com/doc/images/5/52/epuck2_features.png) The following figures show the main components offered by the e-puck2 robot and where they are physically placed: ![epuck2_components_position.png](https://www.gctronic.com/doc/images/b/b2/epuck2_components_position.png) ## Specifications Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Specifications The e-puck version 2 robot maintains full compatibility with its predecessor e-puck (e-puck HWRev 1.3 is considered in the following table): | **Feature** | **e-puck version 1.3** | **e-puck version 2** | **Compatibility** | **Additional** | | --- | --- | --- | --- | --- | | Size, weight | 70 mm diameter, 55 mm height, 150 g | Same form factor: 70 mm diameter, 45 mm, 130 g | ok.png | No e-jumper required | | Battery, autonomy | LiIPo rechargeable battery (external charger), 1800 mAh. About 3 hours autonomy. Recharging time about 2-3h. | Same battery; USB charging, recharging time about 2.5h. | plus.png | USB charging | | Processor | 16-bit dsPIC30F6014A @ 60MHz (15 MIPS), DSP core for signal processing | 32-bit STM32F407 @ 168 MHz (210 DMIPS), DSP and FPU, DMA | plus.png | ~10 times faster | | Memory | RAM: 8 KB; Flash: 144 KB | RAM: 192 KB; Flash: 1024 KB | plus.png | RAM: 24x more capable Flash:~7x more capable | | Motors | 2 stepper motors with a 50:1 reduction gear; 20 steps per revolution; about 0.13 mm resolution | Same motors | ok.png | | | Wheels | Wheels diamater = 41 mm Distance between wheels = 53 mm | Same wheels | ok.png | | | Speed | Max: 1000 steps/s (about 12.9 cm/s) | Max: 1200 steps/s (about 15.4 cm/s) | plus.png | 20% faster | | Mechanical structure | Transparent plastic body supporting PCBs, battery and motors | Same mechanics | ok.png | | | Distance sensor | 8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm | Same infra-red sensors Front real distance sensor, Time of fight (ToF), up to 2 meter. | plus.png | ToF sensor | | IMU | 3D accelerometer and 3D gyro | 3D accelerometer, 3D gyro, 3D magnetometer | plus.png | 3D magnetometer | | Camera | VGA color camera; typical use: 52x39 or 480x1 | Same camera; typical use: 160x120 | ok.png | Bigger images handling | | Audio | 3 omni-directional microphones for sound localization speaker capable of playing WAV or tone sounds | 4 omni-directional microhpones (digital) for sound localization speaker capable of playing WAV or tone sounds | plus.png | +1 front microphone | | LEDs | 8 red LEDs around the robot, green body light, 1 strong red LED in front | 4 red LEDs and 4 RGB LEDs around the robot, green light, 1 strong red LED in front | plus.png | 4x RGB LEDs | | Communication | RS232 and Bluetooth 2.0 for connection and programming | USB Full-speed, Bluetooth 2.0, BLE, WiFi | plus.png | WiFi, BLE | | Storage | Not available | Micro SD slot | plus.png | Micro SD | | Remote Control | Infra-red receiver for standard remote control commands | Same receiver | ok.png | | | Switch / selector | 16 position rotating switch | Same selector | ok.png | | | Extensions | Ground sensors, range and bearing, RGB panel, Gumstix extension, omnivision, your own | All extension supported | ok.png | | | Programming | Free C compiler and IDE, Webots simulator, external debugger | Free C compiler and IDE, Webots simulator, onboard debugger (GDB) | plus.png | Onboard debugger | This is the overall communication schema: ![comm_overall_epuck2E.jpg](https://www.gctronic.com/doc/images/9/9b/comm_overall_epuck2E.jpg) ## Documentation Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Documentation - **Main microcontroller**: STM32F407, [datasheet](https://projects.gctronic.com/epuck2/doc/STM32F407xx_datasheet.pdf), [reference-manual](https://projects.gctronic.com/epuck2/doc/STM32F407_reference-manual.pdf) - **Programmer/debugger**: STM32F413, [datasheet](https://projects.gctronic.com/epuck2/doc/STM32F413x_datasheet.pdf), [reference-manual](https://projects.gctronic.com/epuck2/doc/STM32F413_reference-manual.pdf) - **Radio module**: Espressif ESP32, [datasheet](https://projects.gctronic.com/epuck2/doc/esp32_datasheet_en.pdf), [reference-manual](https://projects.gctronic.com/epuck2/doc/esp32_technical_reference_manual_en.pdf); starting from e-puck 2.2 the ESP32 integrates 2MB PSRAM - **Camera**: PixelPlus PO8030D CMOS image sensor, [datasheet](https://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf), no IR cut filter : From about July 2019, the camera mounted on the e-puck2 robot is the Omnivision OV7670 CMOS image sensor, [datasheet](https://projects.gctronic.com/epuck2/doc/OV7670.pdf) - **Microphones**: STM-MP45DT02, [datasheet](https://projects.gctronic.com/epuck2/doc/mp45dt02.pdf) - **Optical sensors**: Vishay Semiconductors Reflective Optical Sensor, [datasheet](https://projects.gctronic.com/epuck2/doc/tcrt1000.pdf) - **ToF distance sensor**: STM-VL53L0X, [datasheet](https://projects.gctronic.com/epuck2/doc/VL53L0X-Datasheet.pdf), [user-manual](https://projects.gctronic.com/epuck2/doc/VL53L0X-UserManual-API.pdf) - **IMU**: InvenSense MPU-9250, [product-specification](https://projects.gctronic.com/epuck2/doc/MPU-9250-product-specification.pdf), [register-map](https://projects.gctronic.com/epuck2/doc/MPU-9250-Register-Map.pdf); starting from e-puck 2.2 the MPU-9250 was substituted by TDK Invesense ICM20942, [datasheet](https://projects.gctronic.com/epuck2/doc/DS-000189-ICM-20948-v1.6.pdf) - **Motors**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=7&Itemid=9) - **Speaker**: Diameter 13mm, power 500mW, 8 Ohm, DS-1389 or PSR12N08AK or similar - **IR receiver**: TSOP36230 ## Migrating from e-puck version 1.x to e-puck version 2 Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Migrating_from_e-puck_version_1.x_to_e-puck_version_2 The e-puck version 2 robot maintains full compatibility with its predecessor e-puck, but there are some improvements that you should be aware of. First of all the e-jumper, that is the small board that is attached on top of the e-puck version 1.x, isn't anymore needed in the e-puck version 2. The components available on the e-jumper are integrated directly in the robot board. On top of the e-puck version 2 you'll see a quite big free connector, this is used to attach the extensions board designed for the e-puck version 1.x that are fully compatible with the e-puck version 2; you must not connect the e-jumper in this connector. Secondly you don't need anymore to unplug and plugin the battery for charging, but instead you can charge the battery (up to 1 ampere) directly by connecting the USB cable. If you want you can still charge the battery with the e-puck version 1.x external charger, in case you have more than one battery. Moreover you don't need anymore a special serial cable (with probably an RS232 to USB adapter) to be able to communicate with the robot, but you can use the USB cable. Once connected to the computer a serial port will be available that you can use to easily exchange data with the robot. ## Extensions Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Extensions All the extensions (ground sensors, range and bearing, RGB panel, gumstix and omnvision) are supported by the e-puck version 2 robot, this means that if you have some extensions for the e-puck version 1.x you can still use them also with e-puck version 2. For more information about using the gumstix extension with e-puck version 2 robot refer to . # Getting Started Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Getting_Started The e-puck2 robot features 3 chips onboard: - the main microcontroller, that is responsible for handling the sensors and actuators and which runs also the demos/algorithms - the programmer, that provides programming/debugging capabilties and moreover it configures the USB hub and is responsible for the power management (on/off of the robot and battery measure) - radio module, that is responsible for handling the wireless communication (WiFi, BLE, BT), the RGB LEDs and the user button (the RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller) The robot is shipped with the last firmware version programmed on all 3 chips, so you can immediately start using the robot. The following sections explain the basic usage of the robot, **all the users should read this chapter completely in order to have a minimal working system ready to play with the e-puck2 robot**. Some sections will have more detailed information that can be read by following the links provided. When required, dedicated informations are given for all platforms (Windows, Linux, Mac). The commands given for Linux are related to the Ubuntu distribution, similar commands are available in other distributions. ## Turn on/off the robot Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Turn_on/off_the_robot To turn on the robot you need to press the power button (blue button) placed on the bottom side of the board, near the speaker, as shown in the following figures: : : ![epuck2_btn_on_off2.jpg](https://www.gctronic.com/doc/images/b/b0/epuck2_btn_on_off2.jpg) ![epuck2_btn_on_off.jpg](https://www.gctronic.com/doc/images/3/35/epuck2_btn_on_off.jpg) To turn off the robot you need to press the power button for 1 second. ## Meaning of the LEDs Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Meaning_of_the_LEDs The e-puck2 has three groups of LEDs that are not controllable by the user. : : ![epuck2_top_leds.png](https://www.gctronic.com/doc/images/5/5c/epuck2_top_leds.png) : *Top view of the e-puck2* - Charger: RED if charging, GREEN if charge complete and RED and GREEN if an error occurs - USB: Turned ON if the e-puck2 detects a USB connection with a computer - STATUS: Turned ON if the robot is ON and OFF if the robot is OFF. When ON, gives an indication of the level of the battery. Also blinks GREEN if the program is running during a debug session. Battery level indications (STATUS RGB LED): - GREEN if the system's tension is greater than 3.5V - ORANGE if the system's tension is between 3.5V and 3.4V - RED if the system's tension is between 3.4V and 3.3V - RED blinking if the system's tension is below 3.3V The robot is automatically turned OFF if the system's tension gets below 3.2V during 10 seconds. ## Connecting the USB cable Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Connecting_the_USB_cable A micro USB cable (included with the robot in the package) is needed to connect the robot to the computer. There are two connectors, one placed on top of the robot facing upwards and the other placed on the side of the robot, as shown in the following figures. Both can be used to charge the robot (up to 1 ampere) or to communicate with it, but do not connect two cables at the same time. Connect the USB cable where is more comfortable to you. : : ![epuck2_usb_conn.jpg](https://www.gctronic.com/doc/images/e/ec/epuck2_usb_conn.jpg) ![epuck2_usb_conn2.jpg](https://www.gctronic.com/doc/images/1/10/epuck2_usb_conn2.jpg) ## Installing the USB drivers Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers The USB drivers must be installed only for the users of a Windows version older than Windows 10: 1. Download and open [zadig-2.3.exe](https://projects.gctronic.com/epuck2/zadig-2.3.exe) 2. Connect the e-puck2 with the USB cable and turn it on. Three unknown devices appear in the device list of the program, namely **e-puck2 STM32F407**, **e-puck2 GDB Server (Interface 0)** and **e-puck2 Serial Monitor (Interface 2)**. 3. For each of the three devices mentioned above, select the `USB Serial (CDC)` driver and click on the `Install Driver` button to install it. Accept the different prompts which may appear during the process. At the end you can simply quit the program and the drivers are installed. These steps are illustrated on Figure 3 below. : : Note : The drivers installed are located in `C:\Users\"your_user_name"\usb_driver` : ![Zadig_epuck2_STM32F407.png](https://www.gctronic.com/doc/images/c/cc/Zadig_epuck2_STM32F407.png) : *Example of driver installation for e-puck2 STM32F407* The drivers are automatically installed with Windows 10, Linux and Mac OS. Anyway in Linux in order to access the serial ports, a little configuration is needed. Type the following command in a terminal session: `sudo adduser $USER dialout`. Once done, you need to log off to let the change take effect. ## Finding the USB serial ports used Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used Two ports are created by the e-puck2's programmer when the USB cable is connected to the robot (even if the robot is turned off): - **e-puck2 GDB Server**. The port used to program and debug the e-puck2. - **e-puck2 Serial Monitor**. Serial communication between the PC and the radio module (used also to program the radio module). A third port could be available depending on the code inside the e-puck2's microcontroller. With the factory firmware a port named **e-puck2 STM32F407** is created. ### Windows Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Windows 1. Open the Device Manager 2. Under **Ports (COM & LPT)** you can see the virtual ports connected to your computer. 3. Do a **Right-click -> properties** on the COM port you want to identify. 4. Go under the **details** tab and select **Bus reported device description** in the properties list. 5. The name of the port should be written in the text box below. 6. Once you found the desired device, you can simply look at its port number **(COMX)**. ### Linux Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Linux : 1. Open a terminal window (`ctrl+alt+t`) and enter the following command: `ls /dev/ttyACM*` : 2. Look for **ttyACM0** and **ttyACM1** in the generated list, which are respectively **e-puck2 GDB Server** and **e-puck2 Serial Monitor**. **ttyACM2** will be also available with the factory firmware, that is related to **e-puck2 STM32F407** port Note : Virtual serial port numbering on Linux depends on the connections order, thus it can be different if another device using virtual serial ports is already connected to your computer before connecting the robot, but the sequence remains the same. ### Mac Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Mac : 1. Open a terminal window and enter the following command: `ls /dev/cu.usbmodem*` : 2. Look for two **cu.usbmodemXXXX**, where XXXX is the number attributed by your computer. You should find two names, with a numbering near to each other, which are respectively **e-puck2 GDB Server** (lower number) and **e-puck2 Serial Monitor** (higher number). A third device **cu.usbmodemXXXX** will be available with the factory firmware, that is related to **e-puck2 STM32F407** port Note : Virtual serial port numbering on Mac depends on the physical USB port used and the device. If you want to keep the same names, you must connect to the same USB port each time. ## PC interface Link: https://www.gctronic.com/doc/index.php?title=e-puck2#PC_interface ![monitor.png](https://www.gctronic.com/doc/images/f/f0/monitor.png) A PC application was developed to start playing with the robot attached to the computer via USB cable: you can have information about all the sensors, receive camera images and control the leds and motors. Beware that it's not mandatory to download this application in order to work with the robot, but it is a nice demo that gives you an overview of all the sensors and actuators available on the robot, this is a first step to gain confidence with the robot. With the factory firmwares programmed in the robot, place the selector in position 8, attach the USB cable and turn on the robot. Enter the correct port (the one related to `e-puck2 STM32F407`) in the interface and click `connect`. The source code is available from the repository . ### Available executables Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Available_executables - [Windows executable](https://projects.gctronic.com/epuck2/monitor_win.zip): tested on Windows 7 and Windows 10 - [Max OS X executable (compatibles with all OS versions and hardware architectures)](https://projects.gctronic.com/epuck2/monitor_mac.zip) - [Ubuntu 14.04 (or later) - 64 bit](https://projects.gctronic.com/epuck2/monitor_linux64bit.tar.gz) On Linux remember to apply the configuration explained in the chapter [Installing the USB drivers](https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers) in order to access the serial port. ## Installing the dependencies for firmwares updates Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates You can update the firmware for all 3 chips: the main microcontroller, the radio module and the programmer. For doing that, you need some tools to be installed on the system. ### Windows Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Windows_2 To upload a new firmware in the microcontroller or in the radio module, you don't need to install anything, the packages provided include all the dependencies. To upload a new firmware in the programmer you need to install an application called `DfuSe` released by STMicroelectronics. You can download it from [DfuSe_V3.0.5.zip](https://projects.gctronic.com/epuck2/en.stsw-stm32080_DfuSe_Demo_V3.0.5.zip). ### Linux Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Linux_2 To upload a new firmware in the microcontroller or in the radio module, you need: - Python (>= 3.4): `sudo apt-get install python3` - Python pip: `sudo apt-get install -y python3-pip` - pySerial (>= 2.5): `sudo pip3 install pyserial` To upload a new firmware in the programmer you need: - dfu-util: `sudo apt-get install dfu-util` ### Mac Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Mac_2 Install the [Homewbrew](https://brew.sh) package manager by opening a terminal and issueing: `/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"` and then: `brew upgrade` To upload a new firmware in the microcontroller or in the radio module, you need: - Python (>= 3.4): `brew install python` (it will install also `pip`) - pySerial (>= 2.5): `pip3 install pyserial` To upload a new firmware in the programmer you need: - dfu-util: `brew install dfu-util` ## PC side development Link: https://www.gctronic.com/doc/index.php?title=e-puck2#PC_side_development This section is dedicated to the users that develop algorithms on the PC side and interact with the robot remotely through a predefined communication protocol. These users don't modify the firmware of the robot, but instead they use the factory firmware released with the robot. They update the robot firmware only when there is an official update. The remote control of the robot, by receiving sensors values and setting the actuators, is done through the following channels: Bluetooth, Bluetooth Low Energy, WiFi, USB cable. Examples of tools/environment used by these users: 1. Aseba 2. Simulator (e.g. Webots) 3. ROS 4. iOS, Android apps 5. Custom PC application 6. IoT (e.g. IFTTT) If you fall into this category, then follow this section for more information: [PC side development](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development). # Main microcontroller Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Main_microcontroller The e-puck2 robot main microcontroller is a 32-bit STM32F407 that runs at 168 MHz (210 DMIPS) and include DSP, FPU and DMA capabilities. The version chosen for the e-puck2 has 192 KB of total RAM and 1024 KB of flash, so there is a lot of memory to work with. This chip is responsible for handling the sensors and actuators and runs also the demos and algorithms. ## Factory firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware The main microcontroller of the robot is initially programmed with a firmware that includes many demos that could be started based on the selector position, here is a list of the demos with related position and a small description: - Selector position 0: Aseba - Selector position 1: Shell - Selector position 2: Read proximity sensors and when an object is near a proximity, turn on the corresponding LED - Selector position 3: Asercom protocol v2 (BT) / **Micropython** - Selector positoin 4: Range and bearing extension (receiver or transmitter, switch between them with button) - Selector position 5: Range and bearing extension - clustering demo (simultaneous transmitter and receiver). - Selector position 6: Move the robot back and forth exploiting the gyro, with LEDs animation - Selector position 7: Play a wav (mono, 16 KHz) named "example.wav" from the micro sd when pressing the button - Selector position 8: Asercom protocol v2 (USB) - Selector position 9: Local communication: transceiver - Selector position 10(A): this position is used to work with the Linux extensions. To work with gumstix refer to [Overo Extension: e-puck2](https://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2) , to work with Pi-puck refer to [Pi-puck: Requirements](https://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements) . - Selector position 11(B): Simple obstacle avoidance + some animation - Selector position 12(C): Hardware test - Selector position 13(D): LEDs reflect orientation of the robot - Selector position 14(E): Compass - Selector position 15(F): WiFi mode The pre-built firmware is available here [main microcontroller factory firmware (05.02.26)](https://projects.gctronic.com/epuck2/e-puck2_main-processor_05.02.26_3f17433.elf). ## Firmware update Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update Now and then there could be an official firmware update for the robot and it's important to keep the robot updated with the last firmware to get possibile new features, improvements and for bug fixes. The onboard programmer run a GDB server, so we use GDB commands to upload a new firmware, for this reason a toolchain is needed to upload a new firmware to the robot. The following steps explain how to update the main microcontroller firmware: 1. Download the package containing the required toolchain and script to program the robot: [Windows](https://projects.gctronic.com/epuck2/e-puck2-prog-main-micro-windows_14.02.23.zip), Linux [32 bits](https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux32_14.02.23.tar.gz)/[64 bits](https://projects.gctronic.com/epuck2/e-puck2-prog-main-linux64_14.02.23.tar.gz), [Mac OS](https://projects.gctronic.com/epuck2/e-puck2-prog-main-micro-macos_14.02.23.zip) 2. Download the last version of the [main microcontroller factory firmware (05.02.26)](https://projects.gctronic.com/epuck2/e-puck2_main-processor_05.02.26_3f17433.elf), or use your custom firmware 3. Extract the package and put the firmware file (with `elf` extension) inside the package directory; beware that only one `elf` file must be present inside this directory 4. Attach the USB cable and turn on the robot 5. Run the script from the package directory: : Windows: double click `program.bat` : Linux/Mac: issue the following command in a terminal `./program.sh`. If you get permission errors, then issue `sudo chmod +x program.sh` to let the script be executable. Beware that the script requires the `pyserial` module, so install it by issuing `pip3 install pyserial` When the upload is complete you'll see an output like in the following figure: ![f407_flashing.png](https://www.gctronic.com/doc/images/8/81/f407_flashing.png) The final lines should contain the entry `".data",`, this means that the upload was successfull. You can then close the terminal window if it is still open. ### Troubleshooting Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Troubleshooting - If you encounter some problem, try to unplug and plug again the USB cable and power cycle the robot, then retry. - If you still have problems, try by manually specifying the serial port at the top of the file `program_manual_conf.bat` (Windows) or `program_manual_conf.sh` (Linux/Mac) and run this script instead of `program.bat/program.sh`. - If you receive an error like `./program.sh: line 27: gcc-arm-none-eabi-7-2017-q4-major/bin/arm-none-eabi-gdb: Permission denied`, try issuing `sudo chmod -R +x gcc-arm-none-eabi-7-2017-q4-major` (for Linux/Mac users) and then retry. ## Robot side development Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Robot_side_development If you are an embedded developer and are brave enough, then you have complete access to the source code running on the robot, so you can discover what happen inside the main microcontroller and modify it to accomodate your needs. Normally the users that fall into this category develop algorithms optimized to run directly on the microcontroller, such as: 1. onboard image processing 2. swarm algorithms 3. fully autonomous behaviors 4. ... For more information about programming the robot itself, refer to section [Robot side development](https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development) # Radio module Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Radio_module The radio module chosen for the e-puck is the new ESP32 chip from [Espressif](https://www.espressif.com/), integrating a dual core that run up to 240 MHz, 4 MB of flash and 520 KB of RAM. It supports WiFi standards 802.11 b/g/n (access point mode supported), Bluetooth and Bluetooth LE 4.2. It is the successor of the ESP8266 chip. The following figure shows the various peripherals available on the ESP32: Starting from e-puck 2.2 the ESP32 chip integrates also additional 2MB of PSRAM. ![esp32-peripherals.png](https://www.gctronic.com/doc/images/2/28/esp32-peripherals.png) This chip first of all is responsible for handling the wireless communication, moreover it handles also the RGB LEDs (with PWM) and the user button. The RGB LEDs and button are connected to the radio module due to the pin number limitation on the main microcontroller. ## Factory firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_2 The radio module of the robot is initially programmed with a firmware that supports Bluetooth communication. The pre-built firmware for e-puck 2.0/2.1 is available here [radio module factory firmware 2.0/2.1 (06.02.26)](https://projects.gctronic.com/epuck2/esp32-firmware_06.02.26_baa628d_2.1.zip). The pre-built firmware for e-puck 2.2 is available here [radio module factory firmware 2.2 (06.02.26)](https://projects.gctronic.com/epuck2/esp32-firmware_06.02.26_baa628d_2.2.zip). For **Mac OS 15 and later versions**, use the following firmware [radio module factory firmware (30.01.25 Mac OS 15 - BLE)](https://projects.gctronic.com/epuck2/esp32-firmware-ble_30.01.25.zip). For details on how to connect refer to the section [PC side development - Mac OS 15](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Mac_OS_15_and_later_versions). ## WiFi firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_firmware At the moment the factory firmware supports only Bluetooth, if you want to work with WiFi you need to program the radio with a dedicated firmware, refer to section [PC side development: WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi). ## BLE firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#BLE_firmware At the moment the factory firmware supports only classic Bluetooth, if you want to work with Bluetooth Low Energy you need to program the radio with a dedicated firmware, refer to section [BLE](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#BLE). ## Firmware update Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 In order to update the firmware of the ESP32 WiFi module you need to use a python script called `esptool` provided by [Espressif](https://www.espressif.com/) (manufacturer of the chip). This script was modified to work with the e-puck2 robot and is included in the provided package. The following steps explain how to update the radio module firmware: 1. Download the package containing the required tools and script to program the robot: [Windows](https://projects.gctronic.com/epuck2/e-puck2-prog-radio-windows_14.02.23.zip), [Linux / Mac](https://projects.gctronic.com/epuck2/e-puck2-prog-radio-macos_14.02.23.zip) 2. Download the last version of the [radio module factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_2) or use another firmware (e.g. WiFi, BLE, your own). The firmware is composed by 3 files named `bootloader.bin`, `ESP32_E-Puck_2.bin` and `partitions_singleapp.bin` 3. Extract the package and put the firmware files inside the package directory; beware that the name of the `.bin` files must be the same as indicated in step 2 4. Attach the USB cable and turn on the robot 5. Run the script from the package directory: : Windows: double click `program.bat` : Linux/Mac: issue the following command in a terminal `./program.sh`. If you get permission errors, then issue `sudo chmod +x program.sh` to let the script be executable. Beware that the script requires the `pyserial` module, so install it by issuing `pip3 install pyserial` The upload should last about 10-15 seconds and you'll see the progress as shown in the following figure: ![esp32-flashing1.png](https://www.gctronic.com/doc/images/5/5f/esp32-flashing1.png) When the upload is complete you'll see that all 3 bin files are uploaded correctly as shown in the following figure: ![esp32-flashing2.png](https://www.gctronic.com/doc/images/2/20/esp32-flashing2.png) Sometime you could encounter a timeout error as shown in the following figures; in these cases you need to unplug and plug again the USB cable and power cycle the robot, then you can retry. Try also by power cycle the robot various times during the *Connecting* phase. ![esp32-flashing3.png](https://www.gctronic.com/doc/images/b/bc/esp32-flashing3.png) ![esp32-flashing4.png](https://www.gctronic.com/doc/images/7/79/esp32-flashing4.png) If you still have problems, try by manually specifying the serial port at the top of the file `program_manual_conf.bat` (Windows) or `program_manual_conf.sh` (Linux/Mac) and run this script instead of `program.bat/program.sh`. ## Development Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Development Probably, you'll never need to touch the firmware running in the radio module, but in case you need to modify the code or you're simply curious about what is happening at the low level, then refer to the section [Radio module development](https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development). # Programmer Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Programmer The e-puck2 robot is equipped with an onboard programmer and debugger that let you update the firmware of the robot and debug your code easily using a standard USB interface. There is a dedicated STM32F413 microcontroller that acts as the programmer with built in GDB server, so you can control exactly what happens using the [GNU Project Debugger](https://www.gnu.org/software/gdb/) in your host machine. The programmer microcontroller is also in charge of handling various low level features such as the configuration of the USB hub and the power button. ## Factory firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_3 The programmer is initially programmed with a firmware based on a ***modified version*** of [Black Magic Probe programmer/debugger](https://github.com/blacksphere/blackmagic/wiki). The pre-built firmware is available here [programmer-firmware.bin (28.05.20)](https://projects.gctronic.com/epuck2/e-puck2_programmer_28.05.20_3b600ec.bin); it is also available in dfu format here [programmer-firmware.dfu (28.05.20)](https://projects.gctronic.com/epuck2/e-puck2_programmer_28.05.20_3b600ec.dfu). ## Firmware update Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_3 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. : : ![e-puck2_top_leds_DFU_413.png](https://www.gctronic.com/doc/images/1/1d/e-puck2_top_leds_DFU_413.png) : *Location of the pin holes to put the programmer into DFU* The programmer will be recognized as `STM Device in DFU Mode` 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 `libusbK` driver for the DFU device. Follow the same procedure as explained in section [Installing the USB drivers](https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers) using `libusbK` driver instead of `USB Serial (CDC)`. **Note for users having robots id >= 5400**: the procedure is slightly different, please [contact us](https://www.gctronic.com/contact.php) if you really need to update the programmer's firmware. ### Linux/Mac Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Linux/Mac In order to update the programmer firmware you need an utility called `dfu-util`, it should be already installed from section [Installing the dependencies for firmwares updates](https://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates). To uplaod the firmware, issue the following command: `sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D programmer-firmware.bin` ### Windows Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Windows_3 Start the `DfuSe` application (previously installed from section [Installing the dependencies for firmwares updates](https://www.gctronic.com/doc/index.php?title=e-puck2#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 `choose` and then locating the file with `dfu` extension, as shown in figure 2. Now click on the `upgrade` button, a warning message will be shown, confirm the action by clicking on `yes` 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. | [1] | [2] | [3] | [4] | | --- | --- | --- | --- | | dfu1.png | dfu2.png | dfu3.png | dfu4.png | ## Development Link: https://www.gctronic.com/doc/index.php?title=e-puck2#Development_2 The programmer code shouldn't be modified, but if you know what you're doing then refer to section [Programmer development](https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development). --- # e-puck2 PC side development Source: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development Last edited: 2026-09-25T10:57:17Z [e-puck2 main wiki](http://www.gctronic.com/doc/index.php?title=e-puck2) # Robot configuration Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Robot_configuration This section explains how to configure the robot based on the communication channel you will use for your developments, thus you need to read only one of the following sections, but it would be better if you spend a bit of time reading them all in order to have a full understanding of the available configurations. ## USB Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#USB The main microcontroller is initially programmed with a firmware that support USB communication. If the main microcontroller isn't programmed with the factory firmware or if you want to be sure to have the last firmware on the robot, you need to program it with the last factory firmware by referring to section [main microcontroller firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update). The radio module can be programmed with either the `Bluetooth` or the `WiFi` firmware, both are compatible with USB communication: - Bluetooth: refer to section [radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) - WiFi: download the [radio module wifi firmware (25.02.19)](https://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip) and then refer to section [radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) When you want to interact with the robot from the computer you need to place the selector in position 8 to work with USB. Section [PC interface](https://www.gctronic.com/doc/index.php?title=e-puck2#PC_interface) gives step by step instructions on how to connect the robot with the computer via USB. Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both USB and Bluetooth communication channels use the same protocol called [advanced sercom v2](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB), refer to section [Communication protocol: BT and USB](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB_2) for detailed information about this protocol. ## Bluetooth Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth The main microcontroller and radio module of the robot are initially programmed with firmwares that together support Bluetooth communication. If the main microcontroller and radio module aren't programmed with the factory firmware or if you want to be sure to have the last firmwares on the robot, you need to program them with the last factory firmwares: - for the main microcontroller, refer to section [main microcontroller firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) - for the radio module, refer to section [radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) When you want to interact with the robot from the computer you need to place the selector in position 3 if you want to work with Bluetooth. Section [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth) gives step by step instructions on how to accomplish your first Bluetooth connection with the robot. Once you tested the connection with the robot and the computer, you can start developing your own application by looking at the details behind the communication protocol. Both Bluetooth and USB communication channels use the same protocol called [advanced sercom v2](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB), refer to section [Communication protocol: BT and USB](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB) for detailed information about this protocol. ## WiFi Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi For working with the WiFi, the main microcontroller must be programmed with the factory firmware and the radio module must be programmed with a dedicated firmware (not the factory one): - for the main microcontroller, refer to section [main microcontroller firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) - [radio module wifi firmware (25.02.19)](https://projects.gctronic.com/epuck2/esp32-firmware-wifi_25.02.19_e2f4883.zip), for information on how to update the firmware refer to section [radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) Put the selector in position 15(F). Section [Connecting to the WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi) gives step by step instructions on how to accomplish your first WiFi connection with the robot. The communication protocol is described in detail in the section [Communication protocol: WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2). ## BLE Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#BLE For working with the Bluetooth Low Energy, the main microcontroller must be programmed with the factory firmware and the radio module must be programmed with a dedicated firmware (not the factory one): - for the main microcontroller, refer to section [main microcontroller firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) - [radio module BLE firmware (03.02.25)](https://projects.gctronic.com/epuck2/esp32-firmware-ble_03.02.25_107e871.zip), for information on how to update the firmware refer to section [radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) Put the selector in position 15(F). Section [Connecting to BLE](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_BLE) gives information about BLE connection with the robot. Also BLE use the same protocol called [advanced sercom v2](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB), refer to section [Communication protocol: BT and USB](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB) for detailed information about this protocol. # Connecting to the Bluetooth Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth The factory firmware of the radio module creates 3 Bluetooth channels using the RFcomm protocol when the robot is paired with the computer: 1. Channel 1, GDB: port to connect with GDB if the programmer is in mode 1 or 3 (refer to chapter [Configuring the Programmer's settings](https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development#Configuring_the_Programmer.27s_settings) for more information about these modes) 2. Channel 2, UART: port to connect to the UART port of the main processor 3. Channel 3, SPI: port to connect to the SPI port of the main processor (not yet implemented. Just do an echo for now) By default, the e-puck2 is not visible when you search for it in the Bluetooth utility of your computer. **To make it visible, it is necessary to hold the USER button (also labeled "esp32" on the electronic board) while turning on the robot with the ON/OFF button.** : : ![e-puck2-bt-pair.png](https://www.gctronic.com/doc/images/4/43/e-puck2-bt-pair.png) Then it will be discoverable and you will be able to pair with it. Note that a prompt could ask you to confirm that the number written on the screen is the same on the e-puck. just ignore this and accept. Otherwise if you are asked for a pin insert 0000. ## Windows 7 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Windows_7 When you pair your computer with the e-puck2, 3 COM ports will be automatically created. To see which COM port corresponds to which channel you need to open the properties of the paired e-puck2 robot from `Bluetooth devices`. Then the ports and related channels are listed in the `Services` tab, as shown in the following figure: ![BT-connection-win7.png](https://www.gctronic.com/doc/images/8/82/BT-connection-win7.png) ## Windows 10 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Windows_10 When you pair your computer with the e-puck2, 6 COM ports will be automatically created. The three ports you will use have `Outgoing` direction and are named `e_puck2_xxxxx-GDB`, `e_puck2_xxxxx-UART`, `e_puck2_xxxxx-SPI`. `xxxxx` is the ID number of your e-puck2. To see which COM port corresponds to which channel you need to: 1. open the Bluetooth devices manager 2. pair with the robot 3. click on `More Bluetooth options` 4. the ports and related channels are listed in the `COM Ports` tab, as shown in the following figure: : ![BT-connection-win10.png](https://www.gctronic.com/doc/images/f/f5/BT-connection-win10.png) ## Linux Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Linux Once paired with the Bluetooth manager, you need to create the port for communicating with the robot by issueing the command: `sudo rfcomm bind /dev/rfcomm0 MAC_ADDR 2` The MAC address is visible from the Bluetooth manager. The parameter `2` indicates the channel, in this case a port for the `UART` channel is created. If you want to connect to another service you need to change this parameter accordingly (e.g. `1` for `GDB` and `3` for `SPI`). Now you can use `/dev/rfcomm0` to connect to the robot. ## Mac Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Mac When you pair your computer with the e-puck2, 3 COM ports will be automatically created: `/dev/cu.e-puck2_xxxxx-GDB`, `/dev/cu.e-puck2_xxxxx-UART` and `/dev/cu.e-puck2_xxxxx-SPI`. xxxxx is the ID number of your e-puck2. On **Mac OS 14**, only one port will be created, this is related to the UART channel. ### Mac OS 15 and later versions Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Mac_OS_15_and_later_versions Unfortunately Bluetooth classic is not well supported on Mac OS 15 and later versions, thus the Bluetooth LE is used instead. Basically a python script connects to the robot via BLE and at the same time creates a virtual serial port and then acts as bridge between BLE and the virtual serial port; the user can then simply open the virtual serial port and send commands and receive sensors data as done with Bluetooth classic. The "bridge python script" can be downloaded from [ble_bridge.py](https://projects.gctronic.com/epuck2/ble_bridge.py). It is based on the project . Requirements: `pip install ble-serial` Then you can start the script with the command: `python3 ble_bridge.py ROBOT_ID SERIAL_PORT`, where `ROBOT_ID` is the robot id (robot label) and `SERIAL_PORT` is the port you would like to use in your software. Example: `python3 ble_bridge.py 5437 /tmp/ttyBLE` #### Bluetooth classic Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_classic If you need to work with Bluetooth classic (using the [radio module factory firmware (28.11.25)](https://projects.gctronic.com/epuck2/esp32-firmware_28.11.25_b4de1a1.zip)), then some useful scripts are provided to ease the connection. Basically in order to work with Bluetooth classic, the robot need to be unpaired and paired again for each connection. The steps are: 1. Get the MAC address of the robot, this need to be done only once: turn it on in discoverable mode (press button while powering on) and issue the command `./get_mac_addr.sh ROBOT_ID (e.g. ./get_mac_addr.sh 5397)`. The shell script can be downloaded from [get_mac_addr.sh](https://projects.gctronic.com/epuck2/get_mac_addr.sh). 2. Unpair and pair again, this need to be done before each connection to the robot: issue the command `./reset_conn.sh MAC_ADDR`. The shell script can be downloaded from [reset_conn.sh](https://projects.gctronic.com/epuck2/reset_conn.sh). 3. Connect to the robot via the Bluetooth SPP serial port A python example can be downloaded from [pair_and_get_prox.py](https://projects.gctronic.com/epuck2/pair_and_get_prox.py): that includes steps 2 and 3 together. The shell scripts are based on the `blueutil` utility, you need to install it before running the scripts (e.g. `brew install blueutil`). ## Testing the Bluetooth connection Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Testing_the_Bluetooth_connection You need to download the PC application provided in section [PC interface: available executables](https://www.gctronic.com/doc/index.php?title=e-puck2#Available_executables). In the connection textfield you need to enter the UART channel port, for example: - Windows 7: `COM258` - Windows 10: `e_puck2_xxxxx-UART` - Linux: `/dev/rfcomm0` - Mac: `/dev/cu.e-puck2_xxxxx-UART` and then click `Connect`. You should start receiving sensors data and you can send commands to the robot. Alternatively you can also use a simple terminal program (e.g. `realterm` in Windows) instead of the PC application, then you can issue manually the commands to receive sensors data or for setting the actuators (once connected, type `h + ENTER` for a list of availables commands). ## Python examples Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Python_examples Here are some basic Python 3 examples that show how to get data from the robot through Bluetooth using the commands available with the [advanced sercom v2](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB): - [printhelp.py](https://projects.gctronic.com/epuck2/printhelp.py): print the list of commands available in the [advanced sercom v2](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB) - [getprox.py](https://projects.gctronic.com/epuck2/getprox.py): print the values of the proximity sensors - [complete.py](https://projects.gctronic.com/epuck2/complete.py): set all the actuators and get all the sensors data printing their values on the screen - [getimage.py](https://projects.gctronic.com/epuck2/getimage.py): request an image and save it to disk - [getmagnetometer.py](https://projects.gctronic.com/epuck2/getmagnetometer.py): enable the magnetometer and print its values - [ranb_asercom.py](https://projects.gctronic.com/epuck2/ranb_asercom.py): range and bearing communication through [asercom](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB) protocol - [play_freq.py](https://projects.gctronic.com/epuck2/play_freq.py): play a tone frequency - [get_mic_data.py](https://projects.gctronic.com/epuck2/get_mic_data.py): get the microphones sampling data, plot them (maptolib needed) and save them to csv In all the examples you need to set the correct Bluetooth serial port related to the robot. ### Connecting to multiple robots Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_multiple_robots Here is a simple Python 3 script [multi-robot.py](https://projects.gctronic.com/epuck2/multi-robot.py) that open a connection with 2 robots and exchange data with them using the [advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol). This example can be extended to connect to more than 2 robots. ### Automotive Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Automotive Initial project in which some robots navigate a city trying to handle the crossroads using only the onboard sensors. You can download the Python 3 script from [epuck2_automotive.py](https://projects.gctronic.com/epuck2/epuck2_automotive.py). Here is a video of this demo: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Audio processing Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Audio_processing The [locate_sound.py](https://projects.gctronic.com/epuck2/locate_sound.py) example demonstrates real-time audio processing using the robot's onboard microphone array. The script identifies a specific emitted tone and directs the robot to track and follow the sound source. Works with audio emitted from other robots and smartphones. Uses the microphone array to triangulate the source and adjust the robot's heading to follow it. Frequency between 1.5 KHz and 8 KHz can be easily identified. Have a look at the [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) . ## C++ remote library Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#C%2B%2B_remote_library A remote control library implemented in C++ is available to control the e-puck2 robot via a Bluetooth connection from the computer. The remote control library is multiplatform and uses only standard C++ libraries. You can download the library with the command `git clone https://github.com/e-puck2/e-puck2_cpp_remote_library`. A simple example showing how to use the library is also available; you can download it with the command `git clone https://github.com/e-puck2/e-puck2_cpp_remote_example`. Before building the example you need to build the library. Then when building the example, make sure that both the library and the example are in the same directory, that is you must end up with the following directory tree: : e-puck2_projects : |_ e-puck2_cpp_remote_library : |_ e-puck2_cpp_remote_example The complete API reference is available in the following link [e-puck2_cpp_remote_library_api_reference.pdf](https://projects.gctronic.com/epuck2/e-puck2_cpp_remote_library_api_reference_rev3ac41e3.pdf). # Connecting to the WiFi Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi The WiFi channel is used to communicate with robot faster than with Bluetooth. At the moment a QQVGA (160x120) color image is transferred to the computer together with the sensors values at about 10 Hz; of course the robot is also able to receive commands from the computer. In order to communicate with the robot through WiFi, first you need to configure the network parameters on the robot by connecting directly to it, since the robot is initially configured in access point mode, as explained in the following section. Once the configuration is saved on the robot, it will then connect automatically to the network and you can connect to it. The LED2 is used to indicate the state of the WiFi connection: - red indicates that the robot is in *access point mode* (waiting for configuration) - green indicates that the robot is connected to a network and has received an IP address - blue (toggling) indicates that the robot is transferring the image to the computer - off when the robot cannot connect to the saved configuration : : ![e-puck2-wifi-led.png](https://www.gctronic.com/doc/images/8/8d/e-puck2-wifi-led.png) ## Network configuration Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Network_configuration If there is no WiFi configuration saved in flash, then the robot will be in *access point mode* in order to let the user connect to it and setup a WiFi connection. The LED2 is red. The access point SSID will be `e-puck2_0XXXX` where `XXXX` is the id of the robot; the password to connect to the access point is `e-puck2robot`. You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address `192.168.1.1`. The available networks are scanned automatically and listed in the browser page as shown in *figure 1*. Choose the WiFi signal you want the robot to establish a conection with from the web generated list, and enter the related password; if the password is correct you'll get a message saying that the connection is established as shown in *figure 2*. After pressing `OK` you will be redirected to the main page showing the network to which you're connected and the others available nearby as shown in *figure 3*. If you press on the connected network, then you can see your IP address as shown in *figure 4*; **take note of the address since it will be needed later**. | [1] | [2] | [3] | [4] | | --- | --- | --- | --- | | esp32-wifi-setup1.png | esp32-wifi-setup2.png | esp32-wifi-setup3.png | esp32-wifi-setup4.png | Now the configuration is saved in flash, this means that when the robot is turned on it will read this configuration and try to establish a connection automatically. Remember that you need to power cycle the robot at least once for the new configuration to be active. Once the connection is established, the LED2 will be green. In order to reset the current configuration you need to press the user button for 2 seconds (the LED2 red will turn on), then you need to power cycle the robot to enter *access point mode*. ![e-puck2-wifi-reset.png](https://www.gctronic.com/doc/images/5/56/e-puck2-wifi-reset.png) ## Finding the IP address Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Finding_the_IP_address Often the IP address assigned to the robot will remain the same when connecting to the same network, so if you took note of the IP address in section [Network configuration](https://www.gctronic.com/doc/index.php?title=e-puck2#Network_configuration) you're ready to go to the next section. Otherwise you need to connect the robot to the computer with the USB cable, open a terminal and connect to the port labeled `Serial Monitor` (see chapter [Finding the USB serial ports used](https://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used)). Then power cycle the robot and the IP address will be shown in the terminal (together with others informations), as illustrated in the following figure: ![esp32-wifi-setup5.png](https://www.gctronic.com/doc/images/9/99/esp32-wifi-setup5.png) ## Testing the WiFi connection Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Testing_the_WiFi_connection A dedicated WiFi version of the PC application was developed to communicate with the robot through TCP protocol. You can download the executable from one of the following links: - [Windows executable - WiFi](https://projects.gctronic.com/epuck2/monitor_wifi_27dddd4.zip) - [Max OS X executable - WiFi](https://projects.gctronic.com/epuck2/monitor_mac_wifi.zip) - [Ubuntu 14.04 (or later) - 64 bit](https://projects.gctronic.com/epuck2/monitor_wifi_linux64bit_27dddd4.tar.gz) If you are interested to the source code, you can download it with the command `git clone -b wifi --recursive https://github.com/e-puck2/monitor.git` Run the PC application, insert the IP address of the robot in the connection textfield and then click on the `Connect` button. You should start receiving sensors data and you can send commands to the robot. The LED2 blue will toggle. ## Web server Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Web_server When the robot is in *access point mode* you can have access to a web page showing the camera image and some buttons that you can use to move the robot; it is a basic example that you can use as a starting point to develop your own web browser interface. You can use a phone, a tablet or a computer to connect to the robot's WiFi and then you need to open a browser and insert the address `192.168.1.1/monitor.html`. ## Python examples Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Python_examples_2 ### Connecting to multiple robots Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_multiple_robots_2 A simple Python 3 script was developed as a starting point to open a connection with multiple robots and exchange data with them using the [WiFi communication protocol](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2). The demo was tested with 10 robots but can be easily extended to connect to more robots. You can download the script with the command `git clone https://github.com/e-puck2/e-puck2_python_wifi_multi.git`. The code was tested to work with Python 3.x. # Connecting to BLE Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_BLE The BLE firmware of the radio module emulates a Serial Port Profile (SPP) using a single custom service: Services | UUID | Role | Description | | --- | --- | --- | | UUID: 0000abf0-0000-1000-8000-00805f9b34fb | Primary | SPP emulation service | That includes 2 characteristics: Characteristics | UUID | Properties | Description | | --- | --- | --- | | 0000abf1-0000-1000-8000-00805f9b34fb | WriteWithoutResponse | Data receive (from pc to robot) | | 0000abf2-0000-1000-8000-00805f9b34fb | Notify | Data notify (from robot to pc) | An example HTML page can be used for testing the BLE connection with the e-puck2 robot: . Beware that the HTML page is only compatible with **Chrome** (for PC and Android devices) and **[Bluefy](https://apps.apple.com/it/app/bluefy-web-ble-browser/id1492822055)** (for iOS devices). # Communication protocol Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Communication_protocol This section is the hardest part to understand. It outlines all the details about the communication protocols that you'll need to implement in order to communicate with the robot form the computer. So spend a bit of time reading and re-reading this section in order to grasp completely all the details. ## Bluetooth and USB Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB The communication protocol is based on the [advanced sercom protocol](http://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol), used with the e-puck1.x robot. The `advanced sercom v2` includes all the commands available in the `advanced sercom` protocol and add some additional commands to handle the new features of the e-puck2 robot. In particular here are the new commands: | Command | Description | Return value / set value | | --- | --- | --- | | `-0x08` | Get all sensors | packet-format-robot-to-pc.jpg see section [Communication protocol: WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2) for the content description | | `-0x09` | Set all actuators | packet-format-pc-to-robot-bt.jpg see section [Communication protocol: WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2) for the content description | | `-0x0A` | Set RGB LEDs, values from 0 (off) to 100 (completely on) | `[LED2_red][LED2_green][LED2_blue][LED4_red][LED4_green][LED4_blue][LED6_red][LED6_green][LED6_blue][LED8_red][LED8_green][LED8_blue]` | | `-0x0B` | Get button state: 0 = not pressed, 1 = pressed | `[STATE]` | | `-0x0C` | Get all 4 microphones volumes | `[MIC0_LSB][MIC0_MSB][MIC1_LSB][MIC1_MSB][MIC2_LSB][MIC2_MSB][MIC3_LSB][MIC3_MSB]` | | `-0x0D` | Get distance from ToF sensor (millimeters) | `[DIST_LSB][DIST_MSB]` | | `-0x0E` | Get SD state: 0 = micro sd not connected, 1 = micro sd connected | `[STATE]` | | `-0x0F` | Enable/disable magnetometer: 0 = disable, 1 = enable | `0 = success, 1 = error` | | `-0x10` | Set proximity state: 0 = disable proximity sampling 1 = enable fast proximity sampling (100 hz) 2 = enable slow proximity sampling (20 hz) | `0 = success, 1 = error` | | `-0x11` | Enable/disable time of flight sensor: 0 = disable, 1 = enable | `0 = success, 1 = error` | | `-0x13` | Play frequency | `[FREQ_LSB][FREQ_MSB]` Range between 100 and 10000 Hz. 0 for stopping. | ## WiFi Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 The communication is based on TCP; the robot create a TCP server and wait for a connection. Each packet is identified by an ID (1 byte). The following IDs are used to send data from the robot to the computer: - 0x00 = reserved - 0x01 = QQVGA color image packet (only the first segment includes this id); packet size (without id) = 38400 bytes; image format = RGB565 - 0x02 = sensors packet; packet size (without id) = 104 bytes; the format of the returned values are based on the [advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol) and are compatible with e-puck1.x: : ![packet-format-robot-to-pc.jpg](https://www.gctronic.com/doc/images/5/5b/packet-format-robot-to-pc.jpg) - Acc: raw axes values (0=X LSB, 1=X MSB, 2=Y LSB, 3=Y MSB, 4=Z LSB, 5=Z MSB), between -1500 and 1500, resolution is +-2g - Acceleration expressed in float: acceleration magnitude ![3dvector-magnitude.png](https://www.gctronic.com/doc/images/2/2a/3dvector-magnitude.png), between 0.0 and about 2600.0 (~3.46 g) - Orientation expressed in float: between 0.0 and 360.0 degrees | 0.0 deg | 90.0 deg | 180 deg | 270 deg | | --- | --- | --- | --- | | orientation0.png | orientation90.png | orientation180.png | orientation270.png | : - Inclination expressed in float: between 0.0 and 90.0 degrees (when tilted in any direction) | 0.0 deg | 90.0 deg | | --- | --- | | inclination0.png | inclination90.png | - Gyro: raw axes values (0=X LSB, 1=X MSB, 2=Y LSB, 3=Y MSB, 4=Z LSB, 5=Z MSB), between -32768 and 32767, range is +-250dps - Magnetometer: raw axes values expressed in float, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla) - Temp: temperature given in Celsius degrees - IR proximity (0=IR_0 LSB, 1=IR_0 MSB, ...): between 0 (no objects detected) and 4095 (object near the sensor) - IR ambient (0=IR_0 LSB, 1=IR_0 MSB, ...): between 0 (strong light) and 4095 (dark) - ToF distance: distance given in millimeters - Mic volume (0=MIC_0 LSB, 1=MIC_0 MSB, ...): between 0 and 4095 - Motors steps: 1000 steps per wheel revolution - Battery: - uSD state: 1 if the micro sd is present and can be read/write, 0 otherwise - TV remote data: RC5 protocol - Selector position: between 0 and 15 - Ground proximity (0=GROUND_0 LSB, 1=GROUND_0 MSB, ...): between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white) - Ground ambient (0=GROUND_0 LSB, 1=GROUND_0 MSB, ...): between 0 (strong light) and 1023 (dark) - Button state: 1 button pressed, 0 button released - 0x03 = empty packet (only id is sent); this is used as an acknowledgment for the commands packet when no sensors and no image is requested The following IDs are used to send data from the computer to the robot: - 0x80 = commands packet; packet size (without id) = 20 bytes: : ![packet-format-pc-to-robot.jpg](https://www.gctronic.com/doc/images/b/b2/packet-format-pc-to-robot.jpg) : - request: - bit0: 0=stop image stream; 1=start image stream - bit1: 0=stop sensors stream; 1=start sensors stream - settings: - bit0: 1=calibrate IR proximity sensors - bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet) - bit2: 0=set motors speed; 1=set motors steps (position) - left and right: when bit2 of `settings` field is `0`, then this is the desired motors speed (-1000..1000); when `1` then this is the value that will be set as motors position (steps) - LEDs: 0=off; 1=on - bit0: 0=LED1 off; 1=LED1 on - bit1: 0=LED3 off; 1=LED3 on - bit2: 0=LED5 off; 1=LED5 on - bit3: 0=LED7 off; 1=LED7 on - bit4: 0=body LED off; 1=body LED on - bit5: 0=front LED off; 1=front LED on - RGB LEDs: for each LED, it is specified in sequence the value of red, green and blue (0...100) - sound id: 0x01=MARIO, 0x02=UNDERWOLRD, 0x04=STARWARS, 0x08=4KHz, 0x10=10KHz, 0x20=stop sound, 0x40=Christmas song For example to receive the camera image (stream) the following steps need to be followed: 1) connect to the robot through TCP 2) send the command packet: : | 0x80 | 0x01 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | 0x00 | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | 3) read the ID (1 byte) and the QQVGA color image pakcet (38400 bytes) 4) go to step 3 # Webots Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Webots 1. Download the last version of [Webots](https://cyberbotics.com/) for your platform and install it. 2. Program the robot with the [WiFi firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_firmware) and put the selector in position 15(F). Connect the robot to your WiFi network. 3. Open the example world you can find in the Webots installation directory `Webots\projects\robots\gctronic\e-puck\worlds\e-puck2.wbt`. 4. Double click the robot or right click on robot and select `Show Robot Windows`, a new small window will appear: insert the IP address of the robot and click connect. : ![epuck2-webots.png](https://www.gctronic.com/doc/images/5/5c/epuck2-webots.png) If the IP address filed is not shown, then be sure that your PROTO version is correct: right click on robot, `Edit PROTO source`, change `version` field to `2`, save and reload world. 5. Now you can start the demo, the robot will be remote controlled. For more information have a look at the [e-puck Webots guide](https://cyberbotics.com/doc/guide/epuck?version=R2023a). # ROS Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#ROS This chapter explains how to use ROS with the e-puck2 robots by connecting them via Bluetooth or WiFi to the computer that runs the ROS nodes. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema: ![epuck2-ros-schema.png](https://www.gctronic.com/doc/images/5/5f/epuck2-ros-schema.png) *Click to enlarge* First of all you need to install and configure ROS, refer to for more informations. This tutorial is based on ROS Kinetic. The same instructions are working with ROS Noetic, beware to use `noetic` instead of `kinetic` when installing the packages. Starting from the work done with the e-puck1 (see [E-Puck ROS](https://www.gctronic.com/doc/index.php?title=E-Puck#ROS)), we updated the code in order to support the e-puck2 robot. ## Initial configuration Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Initial_configuration The following steps need to be done only once, after installing ROS: : 1. If not already done, create a catkin workspace, refer to . Basically you need to issue the following commands: ``` mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd ~/catkin_ws/ catkin_make source devel/setup.bash ``` : 2. You will need to add the line `source ~/catkin_ws/devel/setup.bash` to your .bashrc in order to automatically have access to the ROS commands when the system is started : 3. Move to `~/catkin_ws/src` and clone the ROS e-puck2 driver repo: - if you are working with Python (only Bluetooth communication supported at the moment): `git clone -b e-puck2 https://github.com/gctronic/epuck_driver` - if you are working with cpp: - Bluetooth communication: `git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp` - WiFi communication: `git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp` : 4. Install the dependencies: - ROS: - [gmapping (SLAM)](https://wiki.ros.org/gmapping) package: `sudo apt-get install ros-kinetic-gmapping` - [Rviz IMU plugin](https://wiki.ros.org/rviz_imu_plugin) package: `sudo apt-get install ros-kinetic-rviz-imu-plugin` - Python: - The ROS e-puck2 driver is based on the e-puck2 Python library that requires some dependencies: - install the Python setup tools: `sudo apt-get install python-setuptools` - install the Python image library: `sudo apt-get install python-imaging` - install pybluez version 0.22: `sudo pip install pybluez==0.22` - install pybluez dependencies: `sudo apt-get install libbluetooth-dev` - install OpenCV: `sudo apt-get install python3-opencv` - cpp: - install the library used to communicate with Bluetooth: `sudo apt-get install libbluetooth-dev` - install OpenCV: `sudo apt-get install libopencv-dev` - if you are working with OpenCV 4, then you need to change the header include from `#include ` to `#include ` : 5. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make`, there shouldn't be errors : 6. Program the e-puck2 robot with the [factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware) and put the selector in position 3 for Bluetooth communication or in position 15(F) for WiFi Communication : 7. Program the radio module with the correct firmware: - Bluetooth communication: use the [factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware_2) - WiFi communication: use the [WiFi firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#WiFi_firmware) ## Running the Python ROS node Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Running_the_Python_ROS_node First of all get the last version of the ROS e-puck2 driver from github. Move to `~/catkin_ws/src` and issue: `git clone -b e-puck2 https://github.com/gctronic/epuck_driver`. Then build the driver by opening a terminal and issueing the command `catkin_make` from within the catkin workspace directory (e.g. ~/catkin_ws). Moreover make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): `chmod +x ./src/epuck_driver/scripts/epuck2_driver.py`. Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth). Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to System Settings, Bluetooth and select the robot; once selected you'll see in the right side the related MAC address. First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore. Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [roslaunch](https://wiki.ros.org/roslaunch)). Open a terminal and issue the following command: `roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'`. B4:E6:2D:EB:9C:4F is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot. If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data and [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the informations gathered from the topics published by the e-puck2 driver node. The launch script is configured also to run the [gmapping (SLAM)](https://wiki.ros.org/gmapping) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points. The following figures show all the topics published by the e-puck2 driver node (left) and the `rviz` interface (right): ![e-puck2_topics.png](https://www.gctronic.com/doc/images/8/85/e-puck2_topics.png) *Click to enlarge* ![e-puck2-rviz.png](https://www.gctronic.com/doc/images/0/02/e-puck2-rviz.png) *Click to enlarge* ## Running the cpp ROS node Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Running_the_cpp_ROS_node There is a small difference at the moment between the Bluetooth and WiFi versions of the ROS node: the WiFi ROS node supports also the publication of the magnetometer data. ### Bluetooth Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_2 First of all get the last version of the ROS e-puck2 driver from github. Move to `~/catkin_ws/src` and issue: `git clone -b e-puck2 https://github.com/gctronic/epuck_driver_cpp`. Then build the driver by opening a terminal and issueing the command `catkin_make` from within the catkin workspace directory (e.g. ~/catkin_ws). Before actually starting the e-puck2 node you need to configure the e-puck2 robot as Bluetooth device in the system, refer to section [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth). Once the robot is paired with the computer, you need to take note of its MAC address (this will be needed when launching the ROS node). To know the MAC address of a paired robot, go to System Settings, Bluetooth and select the robot; once selected you'll see in the right side the related MAC address. First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore. Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [roslaunch](https://wiki.ros.org/roslaunch)). Open a terminal and issue the following command: `roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F'`. B4:E6:2D:EB:9C:4F is the e-puck2 Bluetooth MAC address that need to be changed accordingly to your robot. If all is going well the robot will be ready to exchange data and [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the informations gathered from the topics published by the e-puck2 driver node. The launch script is configured also to run the [gmapping (SLAM)](https://wiki.ros.org/gmapping) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points. ### WiFi Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_3 First of all get the last version of the ROS e-puck2 driver from github. Move to `~/catkin_ws/src` and issue: `git clone -b e-puck2_wifi https://github.com/gctronic/epuck_driver_cpp`. Then build the driver by opening a terminal and issueing the command `catkin_make` from within the catkin workspace directory (e.g. ~/catkin_ws). Before actually starting the e-puck2 node you need to connect the e-puck2 robot to your WiFi network, refer to section [Connecting to the WiFi](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_WiFi). First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore. Now you can finally start the e-puck2 ROS node, for this purposes there is a launch script (based on [roslaunch](https://wiki.ros.org/roslaunch)). Open a terminal and issue the following command: `roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20'`. 192.168.1.20 is the e-puck2 IP address that need to be changed accordingly to your robot. If all is going well the robot will be ready to exchange data and [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the informations gathered from the topics published by the e-puck2 driver node. The launch script is configured also to run the [gmapping (SLAM)](https://wiki.ros.org/gmapping) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. The gmapping package provides laser-based SLAM (Simultaneous Localization and Mapping) and since the e-puck2 has no laser sensor, the information from the 6 proximity sensors on the front side of the robot are interpolated to get 19 laser scan points. The refresh rate of the topics is about 11 Hz when the camera image is enabled (see [e-puck2_topics_wifi_refresh_camon.pdf](https://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camon.pdf)) and about 50 Hz when the camera image is disabled (see [e-puck2_topics_wifi_refresh_camoff.pdf](https://projects.gctronic.com/epuck2/wiki_images/e-puck2_topics_wifi_refresh_camoff.pdf)). The same graphs can be created using the command `rosrun tf view_frames`. The following figure shows all the topics published by the e-puck2 WiFi ROS node. The same graph can be created using the command `rqt_graph`. ![e-puck2_topics_wifi.png](https://www.gctronic.com/doc/images/b/bc/e-puck2_topics_wifi.png) *Click to enlarge* ## Move the robot Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Move_the_robot You have some options to move the robot. The first one is to use the `rviz` interface: in the bottom left side of the interface there is a `Teleop` panel containing an *interactive square* meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right. The second method to move the robot is using the `ros-kinetic-turtlebot-teleop` ROS package. If not already done, you can install this package by issueing `sudo apt-get install ros-kinetic-turtlebot-teleop`. There is a lunch file in the e-puck2 ROS driver that configures this package in order to be used with the e-puck2 robot. To start the launch file, issue the following command `roslaunch epuck_driver epuck2_teleop.launch`, then follow the instructions printed on the terminal to move the robot. The third method is by directly publishing on the `/mobile_base/cmd_vel` topic, for instance by issueing the following command `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'` the robot will rotate on the spot, instead by issueing the following command `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'` the robot will move straight forward. Beware that there shouldn't be any other node publishing on the `/mobile_base/cmd_vel` topic (e.g. Rviz), otherwise your commands will be overwritten. ## Control the RGB LEDs Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Control_the_RGB_LEDs The general command to change the RGB LEDs colors is the following: `rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [LED2 red, LED2 green, LED2 blue, LED4 red, LED4 green, LED4 blue, LED6 red, LED6 green, LED6 blue, LED8 red, LED8 green, LED8 blue]}"` The values range is from 0 (off) to 100 (completely on). Have a look at the [e-puck2 overview](https://www.gctronic.com/doc/index.php?title=e-puck2#Overview) to know the position of the RGB LEDs. For instance to set all the RGB LEDs to red, issue the following command: `rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [100,0,0, 100,0,0, 100,0,0, 100,0,0]}"` To turn off all the RGB LEDs issue the following command: `rostopic pub -1 /mobile_base/rgb_leds std_msgs/UInt8MultiArray "{data: [0,0,0, 0,0,0, 0,0,0, 0,0,0]}"` ## Control the LEDs Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Control_the_LEDs The general command to change the LEDs state is the following: `rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7, body LED, front LED]}"` The values are: 0 (off), 1 (on) and 2 (toggle). Have a look at the [e-puck2 overview](https://www.gctronic.com/doc/index.php?title=e-puck2#Overview) to know the position of the LEDs. For instance to turn on LED1, LED5, body LED and front LED, issue the following command: `rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1,0,1,0,1,1]}"` To toggle the state of all the LEDs issue the following command: `rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [2,2,2,2,2,2]}"` ## Visualize the camera image Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Visualize_the_camera_image By default the camera is disabled to avoid communication delays. In order to enable it and visualize the image through ROS you need to pass an additional parameter `cam_en` to the launch script as follows: - Python: `roslaunch epuck_driver epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'` - cpp: - Bluetooth: `roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='B4:E6:2D:EB:9C:4F' cam_en:='true'` - WiFi: `roslaunch epuck_driver_cpp epuck2_controller.launch epuck2_address:='192.168.1.20' cam_en:='true'` Then with the Python ROS node you need to open another terminal and issue the command `rosrun image_view image_view image:=/camera` that will open a window with the e-puck2 camera image. With the cpp ROS node the image is visualized directly in the Rviz window (on the right). When using the Bluetooth ROS node, by default the image is greyscale and its size is 160x2, but you can change the image parameters in the launch script. Instead when using the WiFi node, the image is RGB565 and its size is fixed to 160x120 (you can't change it). ## Multiple robots Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Multiple_robots There is a lunch script file designed to run up to 4 robots simultaneously, you can find it in `~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck2.launch`. Here is an example to run 2 robots: `roslaunch epuck_driver_cpp multi_epuck2.launch robot_addr0:='192.168.1.21' robot_addr1:='192.168.1.23'` After issueing the command, rviz will be opened showing the values of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm. Beware that this launch script is available only in the WiFi branch, but it can be used as a starting point also for the Bluetooth communication. ## Troubleshooting Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Troubleshooting ### Robot state publisher Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Robot_state_publisher If you get an error similar to the following when you start a node with roslaunch: ``` ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x) ``` Then you need to change the launch file from: ``` ``` To: ``` ``` This is due to the fact that `state_publisher` was a deprecated alias for the node named `robot_state_publisher` (see ). # Tracking Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Tracking Some experiments are done with the [SwisTrack software](https://en.wikibooks.org/wiki/SwisTrack) in order to be able to track the e-puck2 robots through a color marker placed on top of the robots. The requirements are the following: - e-puck robots equipped with a color marker attached on top of the robot; beware that there should be a white border of about 1 cm to avoid wrong detection (marker merging). The colors marker were printed with a laser printer. - USB webcam with a resolution of at least 640x480. In our tests we used the `Trust SpotLight Pro`. - Windows OS: the SwisTrack pre-compiled package was built to run in Windows. Moreover the controller example depends on Windows libraries. *Anyway it's important to notice that SwisTrack is multiplatform and that the controller code can be ported to Linux.* - An arena with uniform light conditions to make the detection more robust. ## Controller example Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Controller_example In this example we exploit the *SwisTrack* blobs detection feature in order to detect the color markers on top of the robots and then track these blob with a *Nearest Neighbour tracking* algorithm. The *SwisTrack* application get an image from the USB camera, then applies some conversions and thresholding before applying the blobs detection and finally tracks these blobs. All the data, like the blob's positions, are published to the network (TCP). The controller is a separate application that receives the data from SwisTrack through the network and opens a Bluetooth connection with each robot in order to remote control them. In the example, the informations received are printed in the terminal while moving the robots around (obstacles avoidance). The following schema shows the connections schema: ![tracking-schema.png](https://www.gctronic.com/doc/images/0/06/tracking-schema.png) Follow these steps to run the example: - program all the e-puck2 robots with the last factory firmware (see section [Firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update)) and put the selector in position 3 - pair the robots with the computer, refer to section [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth) - the controller example is based on the [C++ remote library](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#C.2B.2B_remote_library), so download it - download the controller example by issueing the following command: `git clone https://github.com/e-puck2/e-puck2_tracking_example`. When building the example, make sure that both the library and the example are in the same directory - download the pre-compiled [SwisTrack software](https://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip) and extract it. The *SwisTrack* executable can be found in `SwisTrackEnvironment/SwisTrack - Release.exe` - prepare the arena: place the USB camera on the roof pointing towards the robots. Download the [markers](https://projects.gctronic.com/epuck2/tracking/e-puck2-tracking-markers.pdf) and attach one of them on top of each robot. - download the [configuration files package](https://projects.gctronic.com/epuck2/tracking/swistrack-conf.zip) for *SwisTrack* and extract it. Run the *SwisTrack* executable and open the configuration file called `epuck2.swistrack`. All the components to accomplish the tracking of **2 robots** should be loaded automatically. If needed you can tune the various components to improve the blobs detection in your environment or for tracking more robots. - Run the controller example: at the beginning you must enter the Bluetooth UART port numbers for the 2 robots. Then the robots will be moved slightly in order to identify which robot belong to which blob. Then the controller loop is started sending motion commands to the robots for doing obstacles avoidance and printing the data received from SwisTrack in the terminal. The following image shows the example running: ![tracking-epuck2.png](https://www.gctronic.com/doc/images/4/43/tracking-epuck2.png) # Matlab Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Matlab A Matlab interface is available in the following repository . This interface was developed for the e-puck version 1 robot but it is compatible also with e-puck version 2 robot since it is based on the [advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol). # Micropython Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Micropython A Micropython custom build is available for e-puck2 robots. Follow these steps to get started: 1. Update to the last radio module firmware, refer to [Radio module - firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) 2. Put the selector in position 3 3. Connect the USB cable to the robot and turn it on 4. Open a terminal or a Python IDE (e.g. [Thonny](https://thonny.org/)) to access REPL. Use the "e-puck2 Serial Monitor" port (refer to [Finding the USB serial ports used](https://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used)). 5. If you cannot access REPL, power cycle the robot. In case you are using Thonny then you can simply try restarting the backend. When the robot is connected to Bluetooth then the Micropython environment is disabled, instead the classic [asercom protocol](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Bluetooth_and_USB) mode is enabled. Beware that the RAM available for Python scripts is limited to about 10KB for e-puck 2.0 and e-puck 2.1; e-puck 2.2 and later versions are equipped with additional 2 MB of PSRAM, useful e.g. for storing large sensors buffers. At the moment the Micropython environment can be used only through the USB cable. Libraries included in the Micropython custom build: - e-puck2: simplified API to control the e-puck2 robot - ulab: powerful, high-performance numerical library designed specifically for Micropython ## Micropython API for e-puck2 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Micropython_API_for_e-puck2 The epuck2 module provides functions for interacting with the e-puck2 robot hardware. Refer to the [Micropython API reference for e-puck2](http://www.gctronic.com/doc/index.php?title=Micropython_API_reference). ## Micropython examples Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Micropython_examples 1. [Obstacle avoidance](https://projects.gctronic.com/epuck2/micropython/example-obstacle-avoid.py): obstacle avoidance using the 4 front proximity sensors 2. [Monitor](https://projects.gctronic.com/epuck2/micropython/example-monitor.py): show all the sensors values. If you are using Thonny: : 1. Plug the cable and turn on the robot 2. Open Thonny and select the correct serial port (e-puck2 Serial Monitor) 3. Start the example. The shell shows the output from the robot. 4. Now select `Local Python` from the list of available ports. This will disconnect Thonny but let the script keep running 5. Open a terminal program (e.g. Minicom) by selecting the same port of step 2. Now the output should be well aligned and readable. 1. [Christmas](https://projects.gctronic.com/epuck2/micropython/example-christmas.py): advanced example showing the usage of various sensors and actuators 2. [Get microphones data](https://projects.gctronic.com/epuck2/micropython/get_mic_data_csv.py): example showing how to get microphones sampling data and save them to csv. 3. [Locate sound](https://projects.gctronic.com/epuck2/micropython/locate_sound_ulab.py): advanced example showing the processing of audio data: it detects the frequency of the emitted tone, then follow the source of the audio (based on ulab Micropython library) ## Visual Studio Code and LLM Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Visual_Studio_Code_and_LLM This chapter explains how to set up a complete MicroPython development environment for the e-puck2 in Visual Studio Code, how to add an AI coding assistant (GitHub Copilot or Claude) that already knows the e-puck2 API, and how to use it to write a first program: obstacle avoidance with light effects. The AI assistant is meant as a helper, not as a replacement for understanding: the generated code must be read, tested on the real robot and tuned. The example at the end shows how. ### Requirements Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Requirements - [Visual Studio Code](https://code.visualstudio.com/) - [Python 3.9 or later](https://www.python.org/downloads/) (only needed on the PC, to run the `mpremote` tool) - The starter project: [epuck2_micropython_vscode_starter.zip](https://projects.gctronic.com/epuck2/micropython/epuck2_micropython_vscode_starter.zip) - Optional, for the AI assistant: a free [GitHub account](https://github.com/signup) or subscription ### Visual Studio Code setup Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Visual_Studio_Code_setup #### Install the tools Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Install_the_tools 1. Install [Visual Studio Code](https://code.visualstudio.com/). 2. Install [Python 3](https://www.python.org/downloads/) (on Windows enable *Add python.exe to PATH* during the installation). 3. Install [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html), the official MicroPython tool used to run files, copy files and open the REPL. Open a terminal and type: ``` pip install mpremote ``` Check the installation with `mpremote --version`. #### VSCode Extensions Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#VSCode_Extensions | Extension | Identifier | Purpose | | --- | --- | --- | | Python | `ms-python.python` | Python language support | | Pylance | `ms-python.vscode-pylance` | Autocompletion and error highlighting; uses the `epuck2` stubs of the starter project | | GitHub Copilot Chat | `GitHub.copilot-chat` | AI chat and agent mode of VS Code, used with your Anthropic API key or with Copilot Free (see below) | | Tasks | `actboy168.tasks` | Shows the e-puck2 commands as buttons in the status bar | | Claude Code *(optional)* | `anthropic.claude-code` | Official Claude extension, requires a paid Claude plan (Pro or higher) or an API key | No MicroPython-specific extension is needed: the communication with the robot is handled by `mpremote` through the tasks of the starter project, which works the same way on every operating system. #### Open the starter project Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Open_the_starter_project 1. Download and unzip [epuck2_micropython_vscode_starter.zip](https://projects.gctronic.com/epuck2/micropython/epuck2_micropython_vscode_starter.zip). 2. In VS Code choose `File > Open Folder...` and select the `epuck2_micropython_vscode_starter` folder, the one that directly contains the `.vscode` folder (some unzip tools create a second folder with the same name around it). 3. If asked, confirm that you trust the authors of the folder: tasks and settings are disabled in Restricted Mode. 4. Install the recommended extensions: open the Extensions view (`Ctrl+Shift+X`), type `@recommended` in the search box and click `Install` on each extension listed under **Workspace Recommendations**. Alternatively, install them from a terminal: ``` code --install-extension ms-python.python code --install-extension ms-python.vscode-pylance code --install-extension GitHub.copilot-chat code --install-extension actboy168.tasks ``` The project contains: ``` epuck2_micropython_vscode_starter/ ├── .vscode/ │ ├── extensions.json recommended extensions │ ├── settings.json serial port and autocompletion settings │ └── tasks.json run / upload / stop / REPL tasks ├── .claude/skills/epuck2-micropython/ │ └── SKILL.md e-puck2 API reference for the AI assistant ├── typings/ │ └── epuck2.pyi autocompletion for the epuck2 module ├── tools/ │ └── epuck2_tool.py helper used by the tasks (run, stop the robot on Ctrl+C) ├── keybindings-epuck2.json optional keyboard shortcuts └── examples/ └── proximity_monitor.py prints the sensor values to choose thresholds ``` #### Configure the serial port Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Configure_the_serial_port : 1. Open `.vscode/settings.json` and write the "e-puck2 Serial Monitor" port (refer to [Finding the USB serial ports used](https://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used)) in `epuck2.port`, for example: ``` "epuck2.port": "COM5", // Windows "epuck2.port": "/dev/ttyACM1", // Linux ``` : 2. Run the task `e-puck2: REPL` (`Terminal > Run Task...`) and press Enter: the MicroPython prompt `>>>` appears if the port is correct. If nothing happens, try another port. Exit the REPL with `Ctrl+X`. The task `e-puck2: List serial ports` can be run to list all the serial ports available in the system. #### Commands Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Commands The commands for the robot are VS Code tasks. They act on the file currently open in the editor and can be started in three ways: - with the **buttons in the status bar** at the bottom of the window (provided by the *Tasks* extension) - with the **keyboard shortcuts** (see below) - from `Terminal > Run Task...` | Button | Task | Shortcut | What it does | | --- | --- | --- | --- | | Run | e-puck2: Run current file | *Ctrl+Shift+B* | Runs the open file on the robot without copying it; the output of `print()` appears in the terminal. Press *Ctrl+C* in this terminal to interrupt the program: the robot is then stopped automatically (motors, LEDs and sound off). | | Upload | e-puck2: Upload as main.py | *Ctrl+Shift+Alt+U* | Copies the open file on the robot as `main.py`, so that it starts automatically at power on. | | Stop | e-puck2: Stop robot | *Ctrl+Shift+Alt+S* | Interrupts any program running on the robot (for example `main.py`), stops the motors and sound and switches off all LEDs. It cannot be used while *Run* is active, because the serial port is busy: use *Ctrl+C* there. | | REPL | e-puck2: REPL | *Ctrl+Shift+Alt+T* | Opens the interactive MicroPython prompt (exit with *Ctrl+X*). | | Files | e-puck2: List files on robot | *Ctrl+Shift+Alt+L* | Lists the files stored on the robot. | | Remove main.py | e-puck2: Remove main.py | - | Deletes the startup program. | | Ports | e-puck2: List serial ports | - | Lists the available serial ports. | ##### Keyboard shortcuts Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Keyboard_shortcuts `Ctrl+Shift+B` (`Cmd+Shift+B` on macOS) works out of the box. VS Code does not load other keyboard shortcuts from a project folder, so they must be added once to your user settings: 1. Open the Command Palette (`Ctrl+Shift+P`) and run `Preferences: Open Keyboard Shortcuts (JSON)`. 2. Copy the entries of `keybindings-epuck2.json` (from the starter project) inside the square brackets of the file, then save. On macOS `Alt` is the `Option` key. You can change the keys as you like; avoid combinations with only `Ctrl+Alt`, which on many European keyboards is the same as `AltGr` and is needed to type characters like `@`, `#` or `[`. #### First test Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#First_test Create a file `hello.py` and save it with the following content and press `Ctrl+Shift+B`: ``` import epuck2 print("API version:", epuck2.get_api_version()) print("Battery:", epuck2.get_battery()) print("Proximity:", epuck2.get_proximity()) epuck2.set_rgb(0, 0, 0, 50) ``` The values are printed in the terminal and the front-right RGB LED turns blue. While typing `epuck2.` the editor shows the available functions with their description. ### AI assistant in VS Code Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#AI_assistant_in_VS_Code #### Which option Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Which_option | # | Option | Cost | Model | Notes | | --- | --- | --- | --- | --- | | 1 | **VS Code chat with Copilot Free** | Free (monthly usage limits) | *Auto* | **Recommended to start**. Only a free GitHub account is needed. The model is chosen automatically by Copilot and cannot be selected. | | 2 | **Claude Code** extension with a Claude plan | Claude Pro or higher | Claude (Sonnet, Opus, Haiku) | For users who already have a Claude subscription: the most capable agent. | | 3 | **VS Code chat with your Anthropic API key** | No subscription, pay per use | Claude Haiku 4.5 or any other Claude model | To use a specific Claude model without a subscription; requires prepaid API credit. | The e-puck2 skill works with all three options. Plans and model availability refer to September 2026 and can change. #### The e-puck2 skill Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#The_e-puck2_skill General-purpose AI models do not know the `epuck2` Micropython module: without help they guess function names or you have to paste the whole API reference in every conversation, which wastes tokens and quickly consumes the limits of the free plans. The starter project includes a *skill*, `.claude/skills/epuck2-micropython/SKILL.md`: a compact file (about 1,800 tokens) with: - all functions of the `epuck2` module with parameters, ranges and return values - the position of sensors and actuators of the robot - the index table of [get_all_sensors()](https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_all_sensors()) - coding rules for the robot (stop the motors on exit, clamp speeds, tunable constants at the top, loop period, English comments) - a minimal obstacle avoidance example Skills follow the open [Agent Skills](https://agentskills.io) standard, so the same file works with both the VS Code chat and Claude Code, which find it in the `.claude/skills` folder of the open project. The skill is **never loaded automatically**: you activate it yourself by starting your message with the command **`/epuck2-micropython`**. This way it uses tokens only in the conversations where you actually program the robot, and you always know when the e-puck2 knowledge is active. Once activated, it stays available for the rest of the conversation; in a new conversation, activate it again. The file can be edited to add your own rules. #### Option 1: Copilot Free Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Option_1:_Copilot_Free 1. Open the Chat view (`View > Chat` or `Ctrl+Alt+I`) and sign in with your GitHub account; if you have no Copilot plan, choose **Copilot Free**. 2. In the chat input select the **Agent** mode; the model is set to **Auto**. 3. Type `/` in the chat input and check that **epuck2-micropython** appears in the list of commands. #### Option 2: Claude Code with a Claude plan Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Option_2:_Claude_Code_with_a_Claude_plan 1. Install the *Claude Code* extension (`anthropic.claude-code`) from the Extensions view and sign in with your Claude account (Pro plan or higher). 2. Open the Claude Code panel with the project folder open and type `/`: **epuck2-micropython** appears in the list of commands. #### Option 3: Anthropic API key Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Option_3:_Anthropic_API_key 1. Create an account on the [Claude Console](https://console.anthropic.com), buy a small amount of prepaid credit and create an API key. You pay only for what you use; Claude Haiku 4.5 is the cheapest model and a session like the example below costs only a few cents. 2. In VS Code open the Chat view (`View > Chat` or `Ctrl+Alt+I`). 3. Open the model picker at the bottom of the chat input and choose **Manage Models...** (or run `Chat: Manage Language Models` from the Command Palette). 4. Select the provider **Anthropic**, paste your API key and enable **Claude Haiku 4.5**. 5. In the chat input select the **Agent** mode and the model **Claude Haiku 4.5**. 6. Type `/` in the chat input and check that **epuck2-micropython** appears in the list of commands. The same API key can also be used with the Claude Code extension instead of a Claude plan. Keep your API key private: VS Code stores it in the operating system keychain, never write it in the project files. ### Example: obstacle avoidance with light effects Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Example:_obstacle_avoidance_with_light_effects #### The prompt Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#The_prompt Open the chat (Agent mode, or the Claude Code panel) and send the following message. The first line activates the e-puck2 skill. ``` /epuck2-micropython Write examples/obstacle_avoidance_lights.py for the e-puck2 in MicroPython. Requirements: - press the user button to start, press it again to stop (motors, sound and all LEDs off) - implement an obstacles avoidance behavior: steering proportional to front proximity sensors - if an obstacle is straight ahead, rotate in place away from the closer side - each RGB LED shows the closest obstacle in its quadrant: green = free, yellow = near, red = very near - the red LED on the side of the obstacle turns on; body LED on while rotating in place - short beep when the robot starts rotating in place - all speeds, gains and thresholds as constants at the top Then explain the steering formula and which constants I should tune. ``` The prompt is precise on the behaviour but leaves the implementation to the model. Thanks to the skill activated with `/epuck2-micropython`, the model uses the right functions, LED indices and value ranges without reading the full documentation. #### Check, run and tune Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Check,_run_and_tune Before running the generated code: - Read it and compare it with the explanation: which sensors decide the steering? What happens when `prox[6] + prox[7]` is bigger than `prox[0] + prox[1]`? - Check that the motors are stopped when the program ends (`try/finally`) and that speeds are limited to -1000..1000. ##### Measure the proximity values Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Measure_the_proximity_values The thresholds in the generated code are only guesses: the proximity values depend on the robot, on the colour of the obstacles and on the ambient light. Measure them first, with the motors off: 1. Open `examples/proximity_monitor.py` and start it with **Run** (`Ctrl+Shift+B`). Every 0.2 s it prints one line with the 8 proximity values and the ToF distance: ``` P0 P1 P2 P3 P4 P5 P6 P7 | ToF (mm) 38 45 31 29 40 36 52 41 | 812 ``` 1. Hold an obstacle (for example a piece of the arena wall) in front of the robot and move it closer and farther. Note the values of P0 and P7 with nothing around, at the distance where the robot should start to react, and very close. 2. Stop the monitor with `Ctrl+C` in the terminal. 3. Open your `examples/obstacle_avoidance_lights.py` and write the measured values in the threshold constants at the top of the file. ##### Run and tune Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Run_and_tune 1. Put the robot on the floor in an arena, open `examples/obstacle_avoidance_lights.py` and start it with **Run**; press the user button of the robot to start moving. 2. Observe the behavior, then stop the program with `Ctrl+C` in the terminal: the robot is stopped automatically. 3. Change the constants and run again: each **Run** sends the current version of the file, nothing else is needed. Try the base speed and the steering gain: what happens with a gain that is too high? And too low? 4. When you are satisfied, use **Upload** to save it as `main.py` so that it starts at power on. If the robot misbehaves, describe the observed behavior to the assistant (for example "it turns towards the obstacle instead of away from it") instead of just asking to "fix it": the diagnosis is part of the exercise. #### Debugging exercise: the robot gets stuck Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Debugging_exercise:_the_robot_gets_stuck This is the code [obstacle_avoidance_lights_first_attempt.py](https://projects.gctronic.com/epuck2/micropython/obstacle_avoidance_lights_first_attempt.py) we obtained the first time with Copilot *Auto* and the prompt above, without any change. To try it, copy it into a new file of the project, for example `debug_exercise.py`, and run it. It looks correct and it runs, but on the real robot something goes wrong: when an obstacle is straight ahead, the robot starts rotating to one side, then to the other side, and keeps switching forever, beeping at every change, without ever getting away. Find the cause before looking at the solution: - Place the robot in front of a wall and observe: towards which side does it rotate first? Is it away from the closer side, as requested? - Put a `print()` of `front_left`, `front_right` and `rotate_dir` in the loop and watch how they change while the robot rotates. - Read the comments in the rotation branch and check them against the motor speeds: which wheel goes forward and which backward? | Hint | | --- | | The robot rotates clockwise (to the right) when the **left** wheel goes forward and the right wheel backward. Compare this with the signs of `left_speed` and `right_speed` when `rotate_dir = 1`, which the comment calls "right turn". | | Solution | | --- | | With `rotate_dir = 1` the code sets `left_speed = -ROTATE_SPEED` and `right_speed = +ROTATE_SPEED`: the robot rotates to the **left**, not to the right as the comment says. So it turns **towards** the obstacle instead of away from it. While it turns towards the obstacle, the obstacle moves from the front-left to the front-right sensors, `front_right` becomes bigger than `front_left` and the direction is reversed; then the same happens on the other side. The error in the sign creates a positive feedback around the centre: the robot oscillates forever (a live-lock). The fix is to swap the two signs: ``` left_speed = rotate_dir * ROTATE_SPEED # rotate_dir = 1: left wheel forward right_speed = -rotate_dir * ROTATE_SPEED # -> clockwise, turn right ``` A more robust version also chooses the direction **once** when the obstacle is detected and keeps it until the front is free, instead of deciding again at every cycle; a lower threshold to stop rotating (hysteresis) avoids switching back and forth because of sensor noise: ``` if rotate_dir == 0 and front_total >= ROTATE_IN_PLACE_THRESHOLD: rotate_dir = 1 if front_left > front_right else -1 # decide once elif rotate_dir != 0 and front_total < FRONT_FREE_THRESHOLD: rotate_dir = 0 # way is free again ``` Lessons learned: - Comments written by the model can be wrong: check them against the code, and the code against the robot. - Look for the other small issues: the comment on `steering` has the same wrong sign (a positive value makes the robot turn right), and the `elif front_total > FRONT_BLOCK_THRESHOLD` branch does exactly the same as the `else` branch. - Describing the symptom precisely to the assistant ("when an obstacle is straight ahead it rotates left and right forever") gives much better answers than "it doesn't work". | #### Ideas for further exercises Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Ideas_for_further_exercises - Use the ToF sensor (`get_distance()`) to slow down smoothly in front of an obstacle. - Choose the behaviour with the selector (`get_selector()`): avoidance, wall following, follow an object. - Clap to start and stop the robot using `get_mic_volume()`. - Detect when the robot is lifted using the accelerometer and stop the motors. ### Troubleshooting Link: https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Troubleshooting_2 | Problem | Solution | | --- | --- | | `mpremote` is not recognized | Python is not in the PATH: reinstall Python enabling *Add python.exe to PATH*, or run `python -m pip install mpremote`. | | *could not enter raw repl* or no `>>>` prompt | Wrong port (try another one), selector not in position 3, or the port is used by another program (close any serial terminal). | | Access denied to the serial port (Linux) | `sudo adduser $USER dialout`, then log out and in again. | | The robot keeps moving after a program ends or is interrupted | The main microcontroller keeps the last motor, LED and sound commands. Run the task *e-puck2: Stop robot*; in your programs always stop the motors in a `finally` block. | | *epuck2_tool.py requires Python 3.7* or *AttributeError* in `epuck2_tool.py` | The tasks start the helper with `python3` (Linux, macOS) or `python` (Windows): make sure this command runs Python 3 (check with `python --version`). Also make sure the file open in the editor is your MicroPython program, not the helper. | | *e-puck2: Stop robot* fails with a port error | The port is used by `Run current file` or the REPL: press `Ctrl+C` in that terminal (or `Ctrl+X` in the REPL) first. | | The e-puck2 tasks are missing in `Run Task...` | The opened folder is not the one containing `.vscode` (check for a nested `epuck2_micropython_vscode_starter` folder), or the folder is in Restricted Mode: trust it from the `Restricted Mode` indicator in the status bar. | | Red underlines on `import epuck2` | Open the whole `epuck2_micropython_vscode_starter` folder (not a single file) so that the `typings` folder is used. | | `/epuck2-micropython` is not in the command list | Open the whole `epuck2_micropython_vscode_starter` folder (`File > Open Folder...`), not a single file. | | The generated code uses functions that do not exist | The skill was not activated: start the message with `/epuck2-micropython`. | | Copilot shows only *Auto* in the model picker | Expected with Copilot Free: manual model selection requires a paid Copilot plan or your own API key (option 3). | --- # Advanced sercom protocol Source: https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol Last edited: 2026-02-06T07:21:04Z The *advanced sercom* is a serial protocol used to get sensors values from the robot and set its actuators states. There are two modes of communication that are ASCII mode and BINARY mode; the command value identifies the current mode, if it is a positive value then the request is ASCII, otherwise it is BINARY. They differ in that the BINARY mode uses the minimal number of bytes to exchange data, whereas the ASCII mode presents the data in a readable way. Moreover with the BINARY mode many requests can be sent to the robot at the same time, for example by issueing `[-'A'][-'N'][0]` we can get both the accelerometer and proximity values (sequence terminated by a null character). Beware that the commands are case sensitive. ASCII mode commands are terminated by a newline, BINARY mode commands are terminated by a null character. The available commands in ASCII mode are listed below: | Command | Description | Return value | | --- | --- | --- | | `A` | get accelerometer axes values | `a,x,y,z` | | `B,#` | set body led state: 0=off, 1=on, 2=inverse | `b` | | `b` | get battery state: 1=ok, 0=low (e-puck HWRev < 1.3) get battery raw and percentage (e-puck HWRev 1.3 and 2) | `b,#` (e-puck HWRev < 1.3) `b,# (#%)` (e-puck HWRev 1.3 and 2) | | `C` | get selector position | `c,#` | | `D,#,#` | set motors speed (left=[-1000...1000], right=[-1000...1000]) | `d` | | `E` | get motors speed | `e,left,right` | | `F,#` | set front led state: 0=0ff, 1=on, 2=inverse | `f` | | `G` | get IR receiver data | `g IR check : 0x#, address : 0x#, data : 0x#` | | `g` | get gyro 3 axes values (only available with e-puck HWRev 1.3 and 2) | `g,x,y,z` | | `H` | print help | | | `I` | get camera parameters | `i,mode,width,height,zoom,x,y` | | `J,#,#,#,#,#,#` | set camera parameters: mode(0=grayscale, 1=rgb565), width=[1...640], height=[1...480], zoom=[1,2,4,8], x=[1...640], y=[1...480] The total image size must not exceed 4056 bytes. | `j` | | `K` | calibrate proximity sensors | `k` | | `L,#,#` | set led state: led number, state (0=0ff, 1=on, 2=inverse) | `l` | | `M` | get floor sensors values (only available with [floor sensors extension](http://www.gctronic.com/doc/index.php/Others_Extensions#Ground_sensors) and [cliff extension]) | `m,#,#,#,#,#` the first 3 values are from floor sensors extension (left, center, right), the last two values are from cliff extension (right, left) | | `N` | get proximity sensors values | `n,#,#,#,#,#,#,#,#,#,#` the last two values are returned only if using the [gumstix extension](http://www.gctronic.com/doc/index.php/Overo_Extension) and refer to the two [long range proximity sensors](http://www.gctronic.com/doc/index.php/Overo_Extension#Long_range_proximity_sensors) mounted on the extension | | `O` | get ambient light sensors values | `o,#,#,#,#,#,#,#,#,#,#` the last two values are returned only if using the [gumstix extension](http://www.gctronic.com/doc/index.php/Overo_Extension) and refer to the two [long range proximity sensors](http://www.gctronic.com/doc/index.php/Overo_Extension#Long_range_proximity_sensors) mounted on the extension | | `P,#,#` | set motors steps values (left, right) | `p` | | `Q` | get motors steps values | `q,left,right` | | `R` | reset robot | | | `S` | stop the robot and turn off its leds | `s` | | `T,#` | play sound: 1-5 (sound id), others values (stop sound) | `t` | | `t` | get temperature (only available with e-puck HWRev 1.3 and 2) | `t,#` | | `U` | get microphones amplitude values | `u,#,#,#` | | `V` | get protocol version | `v,Version 1.2.2 August 2008 GCtronic` `HW version: #` | | `W,#,#,#` | write I2C message (mod, register, value) | `w` | | `Y,#,#` | read I2C register (mod, regsiter) | `y,value` | The available commands in BINARY mode are listed below: | Command | Description | Return value | | --- | --- | --- | | `[-a]` | get accelerometer axes values | `[X_LSB][X_MSB][Y_LSB][Y_MSB][Z_LSB][Z_MSB]` | | `[-A]` | get acceleration values | `[A_LSB][A_1][A_2][A_MSB][O_LSB][O_1][O_2][O_MSB][I_LSB][I_1][I_2][I_MSB]` A=acceleration, O=orientation, I=inclination | | `[-b]` | get battery state: 1=ok, 0=low (e-puck HWRev < 1.3) get battery percentage (e-puck HWRev 1.3 and 2) | `[STATE][0]` (e-puck HWRev < 1.3) `[PERCENT_LSB][PERCENT_MSB]` | | `[-D][LEFT_LSB][LEFT_MSB][RIGHT_LSB][RIGHT_MSB]` | set motors speed (left=[-1000...1000], right=[-1000...1000]) | | | `[-E]` | get motors speed | `[LEFT_LSB][LEFT_MSB][RIGHT_LSB][RIGHT_MSB]` | | `[-g]` | get gyro 3 axes values (only available with e-puck HWRev 1.3 and 2) | `[X_LSB][X_MSB][Y_LSB][Y_MSB][Z_LSB][Z_MSB]` | | `[-I]` | get camera image | `[mode][width][height][...cam data...]` header: `mode, width, height` are 1 byte each. in color mode `cam data` are in RGB565 format. | | `[-L][LED_NUM][STATE]` | set led state: led number (0-7=leds, 8=body, 9=front), state (0=0ff, 1=on, 2=inverse) | | | `[-M]` | get floor sensors values (only available with [floor sensors extension](http://www.gctronic.com/doc/index.php/Others_Extensions#Ground_sensors) and [cliff extension]) | `[F0_LSB][F0_MSB][F1_LSB][F1_MSB][F2_LSB][F2_MSB][C0_LSB][C0_MSB][C1_LSB][C1_MSB]` the first 3 values are from floor sensors extension, the last two values are from cliff extension | | `[-N]` | get proximity sensors values | `[P0_LSB][P0_MSB][P1_LSB][P1_MSB][P2_LSB][P2_MSB][P3_LSB][P3_MSB][P4_LSB][P4_MSB][P5_LSB][P5_MSB][P6_LSB][P6_MSB][P7_LSB][P7_MSB][P8_LSB][P8_MSB][P9_LSB][P9_MSB]` the last two values (P8, P9) are returned only if using the [gumstix extension](http://www.gctronic.com/doc/index.php/Overo_Extension) and refer to the two [long range proximity sensors](http://www.gctronic.com/doc/index.php/Overo_Extension#Long_range_proximity_sensors) mounted on the extension | | `[-O]` | get ambient light sensors values | `[P0_LSB][P0_MSB][P1_LSB][P1_MSB][P2_LSB][P2_MSB][P3_LSB][P3_MSB][P4_LSB][P4_MSB][P5_LSB][P5_MSB][P6_LSB][P6_MSB][P7_LSB][P7_MSB][P8_LSB][P8_MSB][P9_LSB][P9_MSB]` the last two values are returned only if using the [gumstix extension](http://www.gctronic.com/doc/index.php/Overo_Extension) and refer to the two [long range proximity sensors](http://www.gctronic.com/doc/index.php/Overo_Extension#Long_range_proximity_sensors) mounted on the extension | | `[-P][LEFT_LSB][LEFT_MSB][RIGHT_LSB][RIGHT_MSB]` | set motors steps values (left, right) | | | `[-Q]` | get motors steps values | `[LEFT_LSB][LEFT_MSB][RIGHT_LSB][RIGHT_MSB]` | | `[-t]` | get temperature (only available with e-puck HWRev 1.3 and 2) | `[TEMP]` | | `[-u]` | get microphones amplitude values | `[MIC0_LSB][MIC0_MSB][MIC1_LSB][MIC1_MSB][MIC2_LSB][MIC2_MSB]` | | `[-U]` | get microphones sampling buffer | e-puck1.x format:`[...buffer of 600 bytes...][SCAN_ID]` e-puck2 format: interleaved right, left, back, front microphones; 160 samples (16 bit) for each microphone; 10 ms of data (16 KHz sampling); `[R0,L0,B0,F0,...,R159,L159,B159,F159]`. Total buffer size is 1280 bytes. | | `[-W][MOD][REG][VALUE]` | write I2C message (mod, register, value) | | | `[-w][R0][R1][R2][R3][R4][R5][R6][R7][B0][B1][B2][B3][B4][B5][B6][B7][G0][G1][G2][G3][G4][G5][G6][G7][R8][B8][G8][IR0][IR1][IR2][IR3][IR4][IR5][IR6][IR7]` | set LEDs and IRs state of the [RGB extension]; Rx=Bx=Gx=[0...128]; IRx=[0=off, 1=on] | | | `[-Y][MOD][REG]` | read I2C register (mod, regsiter) | `[value]` | --- # Micropython API reference Source: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference Last edited: 2026-02-19T11:19:36Z The following figures show the main components offered by the e-puck2 robot and where they are physically placed: ![epuck2_components_position.png](https://www.gctronic.com/doc/images/b/b2/epuck2_components_position.png) # Functions Summary Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#Functions_Summary epuck2 Module Functions | Method | Parameters | Description | Returns | | --- | --- | --- | --- | | `epuck2.get_api_version()` | None | Returns the current e-puck2 API version. | `str` | | `epuck2.set_rgb()` | `led, r, g, b` | Set a single RGB LED (LED 2, 4, 6, or 8). | `None` | | `epuck2.set_all_rgb()` | `r2, g2, b2 ... r8, g8, b8` | Set all four RGB LEDs at once (12 params). | `None` | | `epuck2.set_leds()` | `bitmask: int` | Set the standard Red LEDs using a bitmask. | `None` | | `epuck2.play_sound()` | `sound_id: int` | Play an onboard sound effect. | `None` | | `epuck2.play_freq()` | `freq: int` | Play frequency (100 to 10000, 0=stop) | `None` | | `epuck2.set_motors_speed()` | `left, right` | Set motor speeds (-1000 to 1000). | `None` | | `epuck2.set_all_actuators()` | `list` | Set all actuators (motors, LEDs, sound) at once. | `None` | | `epuck2.get_proximity()` | None | Get values from the 8 IR proximity sensors. | `list[8]` | | `epuck2.get_distance()` | None | Get ToF distance in mm. | `int` | | `epuck2.get_mic_volume()` | None | Get volume from the 4 microphones. | `list[4]` | | `epuck2.get_acc_raw()` | None | Get accelerometer raw axes (X, Y, Z). | `list[3]` | | `epuck2.get_gyro_raw()` | None | Get gyroscope raw axes (X, Y, Z). | `list[3]` | | `epuck2.get_battery()` | None | Get raw battery level. | `int` | | `epuck2.get_selector()` | None | Get rotary selector position (0-15). | `int` | | `epuck2.button_pressed()` | None | Get user button state. | `bool` | | `epuck2.sd_available()` | None | Check if Micro SD card is present. | `bool` | | `epuck2.get_tv_remote()` | None | Get IR remote data (RC5). | `int` | | `epuck2.get_all_sensors()` | None | Get all sensor data in one call. | `list[49]` | | `epuck2.get_mic_data()` | `buffer` | Get 4 microphones data | `bool (True on success)` | # General System Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#General_System ## `epuck2.get_api_version()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_api_version() Returns the API version as a string (e.g., "XX.XX"). ``` import epuck2 print(epuck2.get_api_version()) ``` ## `epuck2.get_battery()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_battery() Get the raw battery voltage value. **Returns:** Integer representing the raw battery level. ## `epuck2.get_selector()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_selector() Get the position of the physical rotary selector switch on top of the robot. **Returns:** Integer between **0** and **15**. ## `epuck2.button_pressed()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.button_pressed() Check the state of the user button. **Returns:** `True` if pressed, `False` otherwise. ## `epuck2.sd_available()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.sd_available() Check if a Micro SD card is inserted and mountable. **Returns:** `True` if available, `False` otherwise. # Actuators (Motors, LEDs, Sound) Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#Actuators_(Motors,_LEDs,_Sound) ## `epuck2.set_motors_speed(left, right)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.set_motors_speed(left,_right) Set the speed of the left and right motors. **Parameters:** - `left` (`int`): Speed of left motor (**-1000** to **1000**). - `right` (`int`): Speed of right motor (**-1000** to **1000**). ``` import epuck2 epuck2.set_motors_speed(500, -500) # Spin in place ``` ## `epuck2.set_leds(value)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.set_leds(value) Set the state (on, off) of the standard red LEDs using a bitmask integer. **Parameters:** - `value` (`int`): - Bit 0: LED 1 - Bit 1: LED 3 - Bit 2: LED 5 - Bit 3: LED 7 - Bit 4: Body LED - Bit 5: Front LED ``` # Turn on LED 1 (1) and Front LED (32) -> 1 + 32 = 33 (0x21) epuck2.set_leds(33) ``` ## `epuck2.set_rgb(led, red, green, blue)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.set_rgb(led,_red,_green,_blue) Set the intensity of a specific RGB LED. **Parameters:** - `led` (`int`): 0=LED2, 1=LED4, 2=LED6, 3=LED8. - `red, green, blue` (`int`): Intensity 0-100. ``` # Set LED 2 (Index 0) to half-intensity blue import epuck2 epuck2.set_rgb(0, 0, 0, 50) ``` ## `epuck2.set_all_rgb(r2, g2, b2, ... r8, g8, b8)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.set_all_rgb(r2,_g2,_b2,_..._r8,_g8,_b8) Set all four RGB LEDs simultaneously. **Parameters:** 12 integers (0-100) representing R, G, B for LED 2, 4, 6, and 8 respectively. ``` # Set LED 2 to Red (100, 0, 0) and LED 4 to Green (0, 100, 0). Other LEDs are off. import epuck2 epuck2.set_all_rgb(100, 0, 0, # LED 2 0, 100, 0, # LED 4 0, 0, 0, # LED 6 0, 0, 0) # LED 8 ``` ## `epuck2.play_sound(id)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.play_sound(id) Play onboard sound. **Parameters:** - `id` (`int`): - 0x01: Mario - 0x02: Underworld - 0x04: Star Wars - 0x08: 4KHz Tone - 0x10: 10KHz Tone - 0x20: Stop Sound - 0x40: Christmas song ## `epuck2.play_freq(value)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.play_freq(value) Play a tone with a certain frequency given as parameter. **Parameters:** - `value` (`int`): frequency given in the range between 100 Hz and 10000 Hz. 0 for stopping. ``` # Play 500 Hz, then 2000 Hz, then stop audio. import epuck2 import time while 1: epuck2.play_freq(500) time.sleep(2) epuck2.play_freq(2000) time.sleep(2) epuck2.play_freq(0) break ``` # Sensors Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#Sensors ## `epuck2.get_proximity()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_proximity() Get the proximity sensor values. Higher value = closer object. **Returns:** List of 8 integers (Prox0 to Prox7). ``` import epuck2 prox_values = epuck2.get_proximity() # prox_values[0] is sensor Prox0, prox_values[7] is sensor Prox7 print(prox_values) ``` ## `epuck2.get_distance()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_distance() Get distance from the front Time of Flight (ToF) sensor. **Returns:** Integer in millimeters (0 to 2000). ## `epuck2.get_mic_volume()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_mic_volume() Get microphone volume levels [0..4095]. **Returns:** List of 4 integers: `[Mic0 (right), Mic1 (left), Mic2 (back), Mic3 (front)]`. ## `epuck2.get_acc_raw()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_acc_raw() Get raw accelerometer values (±2g). **Returns:** List of 3 integers: `[X, Y, Z]`. Range [-1500..1500]. ## `epuck2.get_gyro_raw()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_gyro_raw() Get raw gyroscope values (±250dps). **Returns:** List of 3 integers: `[X, Y, Z]`. Range [-32768..32767]. ## `epuck2.get_tv_remote()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_tv_remote() Get the TV remote data (RC5 protocol). **Returns:** Integer data field. ## `epuck2.get_mic_data(buffer)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_mic_data(buffer) Get the 4 microphones sampling data: 160 samples for each microphone, 16 bits per sample, 10 ms of data (16 KHz sampling rate). **Parameters:** - `buffer`: interleaved microphones data: right, left, back, front [R0,L0,B0,F0,...,R159,L159,B159,F159]. The buffer total size is 1280 bytes. **Returns:** True on success, False on fail ``` # Get mic data import epuck2 mic_buffer = bytearray(1280) success = epuck2.get_mic_data(mic_buffer) if not success: print("Failed to acquire mic data.") ``` # Advanced bulk functions Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#Advanced_bulk_functions ## `epuck2.set_all_actuators(args...)` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.set_all_actuators(args...) Set all actuators in one call. Requires 17 arguments. - `Arg 0`: 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) - `Arg 1-2`: Left Motor, Right Motor - `Arg 3`: Standard LEDs bitmask - Bit 0: LED 1 - Bit 1: LED 3 - Bit 2: LED 5 - Bit 3: LED 7 - Bit 4: Body LED - Bit 5: Front LED - `Arg 4-15`: RGB LEDs (R,G,B for LED 2,4,6,8) - `Arg 16`: Sound ID - 0x01: Mario - 0x02: Underworld - 0x04: Star Wars - 0x08: 4KHz Tone - 0x10: 10KHz Tone - 0x20: Stop Sound - 0x40: Christmas song ## `epuck2.get_all_sensors()` Link: https://www.gctronic.com/doc/index.php?title=Micropython_API_reference#epuck2.get_all_sensors() Get all sensors values at once. Returns a list of 49 elements: | Idx | Name | Description | | --- | --- | --- | | 0-2 | Accel X, Y, Z | Raw values between -1500 and 1500, resolution is +-2g | | 3 | Acceleration magnitude | Between 0.0 and about 2600.0 (~3.46 g) | | 4 | Orientation | between 0.0 and 360.0 degrees | | 5 | Inclination | between 0.0 and 90.0 degrees (when tilted in any direction) | | 6-8 | Gyro X, Y, Z | Raw values between -32768 and 32767, resolution is +-250dps | | 9-11 | Magnetometer | X, Y, Z, range is +-4912.0 uT (magnetic flux density expressed in micro Tesla) | | 12 | Temperature | Celsius | | 13-20 | Proximity | Proximity IR sensors 0-7, between 0 (no objects detected) and 4095 (object near the sensor) | | 21-28 | Ambient | Ambient Light 0-7, between 0 (strong light) and 4095 (dark) | | 29 | Distance | ToF (mm) | | 30-33 | Mics | Volume 0-3 between 0 and 4095 | | 34-35 | Motors steps | Left, Right Motor steps (1000 steps per wheel revolution) | | 36 | Battery | Raw value | | 37 | Micro SD | State, 1 if the micro SD is present and can be read/write, 0 otherwise | | 38-40 | Remote | Toggle, Address, Data (RC5 protocol) | | 41 | Selector | Position 0-15 | | 42-44 | Ground Proximity (extension) | Sensors 0-2 between 0 (no surface at all or not reflective surface e.g. black) and 1023 (very reflective surface e.g. white) | | 45-47 | Ground Ambient (extension) | Ambient 0-2 between 0 (strong light) and 1023 (dark) | | 48 | Button | 1=pressed, 0=released | --- # e-puck2 robot side development Source: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development Last edited: 2026-02-19T11:14:56Z [e-puck2 main wiki](http://www.gctronic.com/doc/index.php?title=e-puck2) # Introduction Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Introduction The `C programming` language is used to develop code for the main microcontroller of the e-puck2 robot. The [ChibiOS](http://www.chibios.org) 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. Before starting to code, you need to install the developing environment and its dependencies, all the steps are documented afterwards. 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. 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. # Installation of the e-puck2 environment Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Installation_of_the_e-puck2_environment `Eclipse_e-puck2` 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**. ## Installation for Windows Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Installation_for_Windows ### Java 8 32bits Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Java_8_32bits This section can be ignored if Java version >= 8 32bits is already installed on your computer. To verify you already installed Java, you can open `Programs and Features` from the `control panel` and search for a `AdoptOpenJDK JDK with Hotspot xxx` install. If this entry isn't present, then you need to install it: 1. Go to [OpenJDK download page](https://adoptopenjdk.net/releases.html) and download the `OpenJDK 8 (LTS) HotSpot for Windows x86 JDK` (take the installer, aka. `.msi` file) or you can directly download it from [OpenJDK8U-jdk_x86-32_windows_hotspot_8u422b05.msi](https://projects.gctronic.com/epuck2/OpenJDK8U-jdk_x86-32_windows_hotspot_8u422b05.msi). 2. Run the downloaded installer and follow its instructions to proceed with the installation of OpenJDK 32bits. : ![openjdk-windows.png](https://www.gctronic.com/doc/images/9/98/openjdk-windows.png) : *OpenJDK download page* ### Eclipse_e-puck2 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Eclipse_e-puck2 1. Download the [Eclipse_e-puck2 package for windows](https://github.com/e-puck2/Create_Eclipse_e-puck2/releases/download/29_jan_2020/Eclipse_e-puck2_Win32_29_jan_2020.zip). 2. 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 . 3. You can now run the `Eclipse_e-puck2.exe` to launch Eclipse. 4. You can create a shortcut to `Eclipse_e-puck2.exe` and place it anywhere if you want. : ![Eclipse_e-puck2_Folder_Windows.png](https://www.gctronic.com/doc/images/5/50/Eclipse_e-puck2_Folder_Windows.png) : *Eclipse_e-puck2 folder obtained after extraction* **Important things to avoid :** : 1. The path to the `Eclipse_e-puck2` folder must contain zero space. : Example : : `C:\epfl_stuff\Eclipse_e-puck2` OK : `C:\epfl stuff\Eclipse_e-puck2` NOT OK : 2. You must not put `Eclipse_e-puck2` folder into `Program Files (x86)`. Otherwise the compilation when using Eclipse will not work. : 3. The file’s structure in the `Eclipse_e-puck2` folder must remain the same. It means no file inside this folder must be moved to another place. ### Configuring the PATH variable Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Configuring_the_PATH_variable The `PATH` 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 `arm-none-eabi` toolchain provided inside the `Eclipse_e-puck2` package, you have to add it to the `PATH` variable to be able to call it inside a terminal window. To set the `PATH` variable you need to issue the following command: `set PATH=your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin;%PATH%` 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 `PATH` variable. If you want to set the `PATH` variable permanently, then go to `Control panel` => `System` => `Advanced system settings` => `Environment variables`. A list of variables defined for the user is shown, double click on the `PATH` variable (from the user variables list) and add at the end `;your_installation_path\Eclipse_e-puck2\Tools\gcc-arm-none-eabi-7-2017-q4-major-win32\bin`, then click `OK` three times. Note : The `arm-none-eabi` version can differ from the one given in this example. It could be needed to adapt the path to the correct version. ## Installation for Linux Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Installation_for_Linux ### Java 8 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Java_8 This section can be ignored if Java is already installed on your computer. To verify whether it is installed or not you can type the following command into a terminal window: `update-java-alternatives -l`. If Java is installed, you will get some information about it, otherwise the command will be unknown. You need to have `Java 1.8.xxxx` listed to be able to run `Eclipse_e-puck2`. Type the following commands in a terminal session to install Java SDK: ``` sudo add-apt-repository ppa:openjdk-r/ppa sudo apt-get update sudo apt-get install openjdk-8-jre ``` ### Eclipse_e-puck2 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Eclipse_e-puck2_2 1. Install `make` (probably you already have it installed) by issueing the command: `sudo apt-get install make` 2. Download the Eclipse_e-puck2 package for Linux [32bits](https://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Linux_11_apr_2018_32bits.tar.gz) / [64bits](https://github.com/e-puck2/Create_Eclipse_e-puck2/releases/download/14_aug_2020/Eclipse_e-puck2_Linux64_14_aug_2020.tar.xz). Pay attention to the 32bits or 64bits version. If unsure which Linux version you have, enter the following comand `uname -a` in the terminal window and look for `i686` (32bit) or `x86_64` (64 bit). 3. Extract the downloaded file to the location you want (can take time): `tar -zxvf package_name.tar.gz` 4. You can now run the `Eclipse_e-puck2` executable to launch Eclipse. : ![Eclipse_e-puck2_Folder_Linux.png](https://www.gctronic.com/doc/images/d/d9/Eclipse_e-puck2_Folder_Linux.png) : *Eclipse_e-puck2 folder obtained after extraction* Note : The icon of the `Eclipse_e-puck2` executable will appear after the first launch of the program. **Important things to avoid :** : 1. You cannot create a Link to the `Eclipse_e-puck2` executable because otherwise the program will think its location is where the Link is and it will not find the resources located in the `Eclipse_e-puck2` folder. : 2. The path to the `Eclipse_e-puck2` folder must contain zero space. : Example : : `/home/student/epfl_stuff/Eclipse_e-puck2` OK : `/home/student/epfl stuff/Eclipse_e-puck2` NOT OK : 3. The file’s structure in the `Eclipse_e-puck2` folder must remain the same. It means no file inside this folder must be moved to another place. ### Configuring the PATH variable Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Configuring_the_PATH_variable_2 The `PATH` 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 `arm-none-eabi` toolchain provided inside the `Eclipse_e-puck2` package, you have to add it to the `PATH` variable to be able to call it inside a terminal window. To set the `PATH` variable you need to issue the following command: `export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH` 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 `PATH` variable. If you want to set the `PATH` variable permanently, then you need to set it in the `.profile` file by issuing the command: `echo 'export PATH=your_installation_path/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH' >> ~/.profile` Close and reopen the terminal before using your newly set environment variable. Note : The `arm-none-eabi` 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 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Installation_for_Mac ### Command Line Tools Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Command_Line_Tools To compile on Mac with `Eclipse_e-puck2`, it is necessary to have the `Command Line Tools` installed. It is a bundle of many commonly used tools. You can install it by typing the following command in a terminal window: `xcode-select --install`. 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 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Java_8_2 This section can be ignored if Java is already installed on your computer. 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: `/usr/libexec/java_home -V` You need to have `AdoptOpenJDK 8` listed to be able to run `Eclipse_e-puck2`. 1. Go to [OpenJDK download page](https://adoptopenjdk.net/releases.html) and download the `OpenJDK 8 (LTS) HotSpot for MacOS x64 JDK` (take the installer, aka. `.pkg` file). 2. Open the `.pkg` file downloaded and follow the instructions to proceed with the installation of OpenJDK. : ![openjdk-mac.png](https://www.gctronic.com/doc/images/2/2a/openjdk-mac.png) : *OpenJDK download page* ### Eclipse_e-puck2 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Eclipse_e-puck2_3 : 1. Download the [Eclipse_e-puck2 package for Mac](https://projects.gctronic.com/epuck2/Eclipse_e-puck2/Eclipse_e-puck2_Mac_03.21.dmg). : 2. Open the `.dmg` file downloaded (confirm opening if a warning message appear) and *drag and drop* the `Eclipse_e-puck2.app` into the `Applications` folder : Note: you can place the `Eclipse_e-puck2.app` anywhere, as long as the full path to it doesn’t contain any space, if you don’t want it to be in `Applications`. : 3. You can create an Alias to `Eclipse_e-puck2.app` and place it anywhere if you want. ### First launch and Gatekeeper Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#First_launch_and_Gatekeeper It’s very likely that `Gatekeeper` (one of the protections of Mac OS) will prevent you to launch `Eclipse_e-puck2.app` because it isn’t signed from a known developer. If you can’t run the program because of a warning of the system, press `OK` and try to launch it by right clicking on it and choosing `open` in the contextual menu (may be slow to open the first time). If `Unable to open "Eclipse_e-puck2.app" because this app comes from an unidentified developer.` or if `"Eclipse.app" is corrupted and cannot be opened. You should place this item in the Trash.` appears after executing the app the first time, it is needed to disable temporarily `Gatekeeper`. To do so : : 1. Go to `System Preferences->security and privacy->General` and authorize downloaded application from `Anywhere`. : : ![security_tab_mac.png](https://www.gctronic.com/doc/images/0/0e/security_tab_mac.png) : *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. : `sudo spctl --master-disable` : 2. Now you can try to run the application and it should work. : 3. If Eclipse opened successfully, it is time to reactivate `Gatekeeper`. Simply set back the setting of `Gatekeeper`. : For the ones who needed to type a command to disable `Gatekeeper`, here is the command to reactivate it. : `sudo spctl --master-enable` This procedure is only needed the first time. After that `Gatekeeper` 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 `Gatekeeper`. **Important things to avoid :** : 1. The path to the `Eclipse_e-puck2.app` must contain zero space. : Example : : `/home/student/epfl_stuff/Eclipse_e-puck2` OK : `/home/student/epfl stuff/Eclipse_e-puck2` NOT OK : 2. The file’s structure in the `Eclipse_e-puck2.app` must remain the same. It means no file inside this app must be moved to another place. ### Configuring the PATH variable Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Configuring_the_PATH_variable_3 The `PATH` 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 `arm-none-eabi` toolchain provided inside the `Eclipse_e-puck2` package, you have to add it to the `PATH` variable to be able to call it inside a terminal window. To set the `PATH` variable you need to issue the following command: `export PATH=your_installation_path/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH` If you put the `Eclipse_e-puck2.app` into the `Applications` folder then the exact command would be: `export PATH=/Applications/Eclipse_e-puck2.app/Contents/Eclipse_e-puck2/Tools/gcc-arm-none-eabi-7-2017-q4-major/bin:$PATH` 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 `PATH` variable. If you want to set the `PATH` variable permanently, then you need to set it in the `.bash_profile` file by issuing the command: `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` Close and reopen the terminal before using your newly set environment variable. Note : The `arm-none-eabi` 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 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#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 and follow the installation instructions (default configuration is ok) - Linux: issue the command `sudo apt-get install git` - Mac: issue the command `brew install git` The source code can downloaded with the command: `git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git` The command must be issued in `Git bash` 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. A snapshot of the repository can be downloaded from [e-puck2_main-processor_snapshot_17.03.20.zip](https://projects.gctronic.com/epuck2/e-puck2_main-processor_snapshot_17.03.20_1f56587.zip). # Creating a project Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Creating_a_project ## Main microcontroller factory firmware project Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#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: : 1 Run Eclipse and then select `File->New->Makefile Project with Existing Code`. : ![e-puck2-dev3-1.png](https://www.gctronic.com/doc/images/7/73/e-puck2-dev3-1.png) : 2 Next click on the `Browse` button and choose the project folder of the git repository downloaded previously (should be named `e-puck2_main-processor`) and set a project name (otherwise you can keep the one created by Eclipse). Choose `None` for the the toolchain. : 3 Click on the `Finish` button and the project is added to Eclipse. : ![e-puck2-dev3-2.png](https://www.gctronic.com/doc/images/4/4d/e-puck2-dev3-2.png) : 4 Build the project by selecting one directory of the project from the left panel and then `Project->Build Project`. ## Project template Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Project_template The main microcontroller factory firmware project can also be used as a library to build your own project on top of it. To accomplish that, you have to copy the folder `Project_template`, contained in the `e-puck2_main-processor` project, and place it in the same directory of the `e-puck2_main-processor` project; you can of course rename the folder to the name you want (e.g. `myproject`). You must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - myproject Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder of your project (e.g. `myproject`) and set a project name (otherwise you can keep the one created by Eclipse). Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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 (`.c`) to the project you need to add them also in the `makefile`, in the `CSRC` definition. All the headers files (`.h`) located next to the `makefile` are automatically included in the compilation, but if you need to place them into folders, you have to specify these folders in the `makefile`, in the `INCDIR` definition. The same is needed for any desired `.h` files from other external folders. In the `makefile` you can also set the name of your project. This `makefile` uses the main makefile of the `e-puck2_main-processor` project. This means you can add custom commands to the `makefile` but it should not interfere with the main makefile. # Configuring the Debugger's settings Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Configuring_the_Debugger%27s_settings `Eclipse_e-puck2` contains everything needed to compile, program and debug the e-puck2. The only settings to configure with a new project are located under the `Debug Configurations` icon of Eclipse (you can also find it on `Run->Debug Configurations`). : ![Debug_configuration.png](https://www.gctronic.com/doc/images/3/36/Debug_configuration.png) Once in the settings, select `Generic Blackmagic Probe` preset on the left panel. Then you need to configure two things : 1. In the `main` 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 `Browse...` and `Search Project...` buttons. If nothing is appearing when you press `Search Project...` then you must enter the `.elf` file name by hand, which can be found in your project `build` folder (e.g. `build/e-puck2_main-processor.elf`). 2. In the `Startup` 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. [See how to find it](http://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used). : - For Windows, it will be `\\.\COMX`, `X` being the port number. - For Linux, it will be `/dev/ttyACMX`, `X` being the port number - For Mac, it will be `/dev/cu.usbmodemXXXXX`, `XXXXX` being the port number. - You can also type `${COM_PORT}` instead of the com port in order to use the variable `COM_PORT` for the debug configuration. To change the value of this variable, go to the `main` tab again, click on the `Variables...` button and click on the `Edit Variables...` button. The opened window will let you edit the value of the variable. Using the variable `COM_PORT` 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 `COM_PORT` 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. : ![e-puck2-debug.jpg](https://www.gctronic.com/doc/images/0/05/e-puck2-debug.jpg) Now you should be able to use the debugger with Eclipse. Notice that the settings are saved in the project folder in a file with extension `.launch`. If you want, you can rename this file (e.g. `Debug_project_template.launch`) with the name you want for the debug configuration of your project. # Running a debugging session Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#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 [Main microcontroller: firmware update](http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update). To start a session follow the next steps: 1. Connect the robot to the computer and turn it on 2. From Eclipse, launch the debug configuration previously set: from the menu `Run->Debug configurations...`, select the configuration and click on the `Debug` button. Alternatively you can directly select your configuration from the debugger drop-down menu. :![e-puck2-debug2.png](https://www.gctronic.com/doc/images/9/9b/e-puck2-debug2.png) 3. When the debugging session is started, Eclipse will change the view to the `Debug perspective`. Right-click on the main process and select `Restart` to restart the program from the beginning ![e-puck2-debug3.png](https://www.gctronic.com/doc/images/2/26/e-puck2-debug3.png) 4. Click on the `Resume` 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 `Terminate` button and click on the `C/C++ perspective` button. ![e-puck2-debug4.png](https://www.gctronic.com/doc/images/3/37/e-puck2-debug4.png) ## Adding breakpoints Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Adding_breakpoints ## Watch variables Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Watch_variables ## Analyze microcontroller registers content Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Analyze_microcontroller_registers_content When a debugging session is started, the microcontroller's registers state can be inspected by clicking on the `EmbSys Registers` tab on the top right side of the `Debug perspective`. ![e-puck2-debug5.png](https://www.gctronic.com/doc/images/e/ed/e-puck2-debug5.png) ## Bluetooth debugging session Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Bluetooth_debugging_session It is possible to run a debugging session remotely thorugh Bluetooth following these steps: 1. change the programmer's mode to `mode 1` with the command `monitor select_mode 1`, for more informations refer to [e-puck2 programmer development](https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development), chapter `Configuring the Programmer's settings` 2. pair the robot with the computer 3. in the debugger's settings, setup the port with the `Bluetooth channel 1, GDB port` name, for more informations refer to [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth) 4. start the debugging session and the Bluetooth connection will be established automatically; now you can program/debug the robot remotely Beware that GDB over the Bluetooth connection of the e-puck2 is much slower than with USB and it doesn't work with Windows due to GDB limitations on this OS. # Local communication Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Local_communication Local range infrared communication between e-puck2 robots can be achieved using the infrared sensors of the robots to transmit and receive information. The communication system is multiplexed with the proximity sensing system commonly used on the robots, thus it is possible to both communicate and avoid obstacles. The implementation is based on the [libIrcom](http://www.e-puck.org/index.php?option=com_content&view=article&id=32&Itemid=28) library developed for the e-puck version 1 robots and it keeps retro-compatibility. This means that an e-puck version 1 is able to communicate with an e-puck version 2, so you can still use your e-puck version 1 robots together with e-puck version 2 to form a bigger fleet of robots for your experiments. Moreover the API is the same, thus the code developed for the e-puck version 1 can be used easily also with the e-puck version 2. Here are some details about the current implementation of the local communication module: - messages are encoded using a frequency modulation that permits usage in a wide range of light conditions - the module allows communications at a rate of up to 30 bytes per seconds (maximum theoretical throughput) - support half-duplex communication - use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; the sensors update frequency is at most 5 Hz - messages can be detected at a distance of about 7 cm (good reception), and even up to 12-13 cm (sparse reception) - messages are stored in a queue (up to 20 messages) and can be retrieved at any time, unless they are overwritten when the queue is full The local communication module is integrated in the factory firmware, so if you want to have a look at the code refer to section [Get the source code](https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Get_the_source_code). A simple exmaple exploiting the local communication can be found in the factory firmware. Put the selector in position 9 and connect the USB cable to the robot: the messages received will be printed in the terminal while the robot continuously send messages to other robots (transceiver behavior). The body led is toggled at each message reception. If an higher throughput and a longer communication distance are required, there is the [range and bearing extension](http://www.gctronic.com/doc/index.php/Others_Extensions#Range_and_bearing) designed for this purpose. ## Synchronize example Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Synchronize_example This is a more advanced example exploiting the local communication. Basically the robots programmed with this demo will eventually orient themselves in the same direction, this is accomplished by exchanging data locally between them. The same example is also available for e-puck version 1 robots (see [libIrcom](http://www.e-puck.org/index.php?option=com_content&view=article&id=32&Itemid=28)), so you can test it with a mix of robots. The pre-built firmware is available here [e-puck2_example_synchronize.elf (10.12.19)](https://projects.gctronic.com/epuck2/e-puck2_example_synchronize_10.12.19_734d1f7.elf). ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Usage When the robot is turned on, it starts exchanging information with other robots and try to align with them. Beware that the selector position is taken as the id of the robot, so you need to place the selector in a different position for each robot. Basically you need to put the selector in an unused position, turn on the robot and place it near the others. The robots will eventually align in the same direction. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_example_synchronize.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_example_synchronize` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_example_synchronize Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_example_synchronize`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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). ## Master-slave example Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Master-slave_example For this example two robots equipped with the [ground sensors extension](https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors) are needed: one acts as a master (transmitter) and the other as a slave (receiver). The master send a command (1 byte) to the slave indicating the current color of its RGB LEDs and the slave when receives the command, interpret it and set its RGB LEDs color to the same color of the master. The ground sensors extension is used to move the robots along a black line in order to follow a desired path. The pre-built firmware is available here [e-puck2_example_master_slave.elf (03.03.20)](https://projects.gctronic.com/epuck2/e-puck2_example_master_slave_03.03.20_00311f3.elf). ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Usage_2 Program the two robots with this demo and set the selector to position 0 for one robot (master) and position 1 (any position but zero would be ok) for the other (slave). Print this [master-slave-path.pdf](https://projects.gctronic.com/epuck2/master-slave-path.pdf) and place the master on one side and the slave in the other side. Both robots will move back and forth and when they encounter each other, the master will send its RGB LEDs state to the slave that will reflect the same state on its own RGB LEDs. You can try different paths and also add more robots with slighly modifications to the code, this is only a starting point. Beware that the robots will detect each other thanks to the proximity sensors values and they start to exchange data only when they're facing each other. This behavior can be changed by continuously exchanging data, in this way you can play also with different distances between the robot's path. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building_2 First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_example_master_slave.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_example_master_slave` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_example_master_slave Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_example_master_slave`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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). # Example projects Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Example_projects ## Digital Signal Processing (DSP) and wav playback Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Digital_Signal_Processing_(DSP)_and_wav_playback In this example the [CMSIS-DSP](http://www.keil.com/pack/doc/CMSIS/DSP/html/index.html) 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. The pre-built firmware is available here [e-puck2_example_dsp.elf (05.10.18)](https://projects.gctronic.com/epuck2/e-puck2_example_dsp_05.10.18_3aa8b81.elf). ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Usage_3 There are basically two demos in this example, one run on selector position 0 and the other in selector position 1. 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. 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. 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 `0.wav`, for proximity 1 it will be played `1.wav` and so on till proximity 7 with `7.wav`. All the wav files you need are stored in the `wav` 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 `0.wav` to `7.wav` and they must be 16 KHz, mono. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building_3 First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_example_dsp.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_example_dsp` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_example_dsp Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_example_dsp`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#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. Moreover it applies a pitch scaling algorithm to the data before playing it from the micro SD. The pitch scale processing is based on the SOLA algorithm and a simple implementation is available from the following link . Have a look at this site bacause it has a good explanation of the algorithm. The pre-built firmware is available here [e-puck2_example_pitch_scale.elf (07.11.18)](https://projects.gctronic.com/epuck2/e-puck2_example_pitch_scale_07.11.18_26d16f0.elf). ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Usage_4 The example requires a micro SD (FAT32) inserted in the robot. 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. You can choose whether to get an higher or lower pitch by changing the `TIME_SCALE` parameter in `sola.c`: - if you want to get an higher pitch, then change `TIME_SCALE` to a value > 1.0 - if you want to get a lower pitch, then change the `TIME_SCALE` to a value < 1.0 Of course, if the parameter is changed, you need to rebuild the project and reflash the robot. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building_4 First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_example_pitch_scale.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_example_pitch_scale` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_example_pitch_scale Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_example_pitch_scale`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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). ## C++ Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#C%2B%2B A basic example showing how to integrate C++ code in your project is available in the following repository: . The example demonstrates simple usage of a class and for range loops. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building_5 First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_cpp.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_cpp` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_cpp Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_cpp`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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). ## Bluetooth echo Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Bluetooth_echo The aim of this example is to show how to exchange data between the robot and the computer through a Bluetooth connection. The project implements a simple echo behavior, that is what is received by the robot is sent back to the computer. ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Building_6 First of all download the source code with the command: `git clone https://github.com/e-puck2/e-puck2_example_bluetooth_echo.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. Place the cloned repo folder `e-puck2_example_bluetooth_echo` in the same directory of the `e-puck2_main-processor` project; you must end up with the following directory tree: - e-puck2 - e-puck2_main-processor - e-puck2_example_bluetooth_echo Then you can add this project in Eclipse by following the next steps: 1. Run Eclipse and then select `File->New->Makefile Project with Existing Code`. 2. Next click on the `Browse` button and choose the project folder `e-puck2_example_bluetooth_echo`. Choose `None` for the the toolchain. 3. Click on the `Finish` button and the project is added to Eclipse. 4. Select the project root folder and go to `Project->Properties->C/C++ General->Preprocessor Include Paths, Macros etc->Providers` and check `CDT Cross GCC Built-in Compiler Settings`. Then in the textbox below, write `arm-none-eabi-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"`. 5. Create a linked folder inside your project that links to the `e-puck2_main-processor` library. This allows Eclipse to index the declarations and implementations of the functions and variables in the code of the library. 1. Select the project root folder and go to `File->New->Folder`. 2. Check `Advanced >>` on the bottom. 3. Choose `Link to alternate location (Linked Folder)`. 4. Type `PROJECT_LOC/../e-puck2_main-processor` and click the `Finish` button. 6. Build the project by selecting one file of the project from the left panel and then `Project->Build Project`. The result of the compilation will appear in the `build` folder in your project folder. 7. After you compile the project, select the project root folder and go to `Project->C/C++ Index->Rebuild` 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). ## Ball detection Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Ball_detection Pierre Oppliger and WIlliam Galand, during their semester project at EPFL, were able to let the e-puck2 robot reliably recognize a ball independently of light conditions. This is a step towards an e-puck2 football soccer player. For more information about the project (French) and source code, have a look at the repository . # Firmware update using factory bootloader Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Firmware_update_using_factory_bootloader ## Factory firmware Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Factory_firmware The pre-built firmware is available here [main microcontroller factory firmware.bin (05.02.26)](https://projects.gctronic.com/epuck2/e-puck2_main-processor_05.02.26_3f17433.bin); it is also available in dfu format here [main microcontroller factory firmware.dfu (05.02.26)](https://projects.gctronic.com/epuck2/e-puck2_main-processor_05.02.26_3f17433.dfu). ## Firmware update Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Firmware_update This procedure should be used only if the normal firmware update steps described in the section [Main microcontroller: firmware update](http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) don't work. This is a recovery procedure. The main 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 first connecting the USB cable, then pressing the button called `407 boot` while turning on the robot. The button is located near the left wheel, on the bottom side of the electronic board, see the photo below. : : ![F407-dfu.jpg](https://www.gctronic.com/doc/images/7/7e/F407-dfu.jpg) : *Location of the button to put the main microcontroller into DFU* The main microcontroller will be recognized as `STM Device in DFU Mode` 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 `libusbK` driver for the DFU device. Follow the same procedure as explained in section [Installing the USB drivers](http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_USB_drivers) using `libusbK` driver instead of `USB Serial (CDC)`. If you still have problems, try to install the drivers you can find in `C:\Program Files (x86)\STMicroelectronics\Software\DfuSe v3.0.6\Bin\Driver`. ### Linux/Mac Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Linux/Mac In order to update the main microcontroller firmware you need an utility called `dfu-util`, it should be already installed from section [Installing the dependencies for firmwares updates](http://www.gctronic.com/doc/index.php?title=e-puck2#Installing_the_dependencies_for_firmwares_updates). To uplaod the firmware, issue the following command: `sudo dfu-util -d 0483:df11 -a 0 -s 0x08000000 -D your_firmware.bin` (the name of the bin file must be changed accordingly). ### Windows Link: https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development#Windows Start the `DfuSe` application (previously installed from section [Installing the dependencies for firmwares updates](http://www.gctronic.com/doc/index.php?title=e-puck2#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 `choose` and then locating the file with `dfu` extension, as shown in figure 2. Now click on the `upgrade` button, a warning message will be shown, confirm the action by clicking on `yes` 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. | [1] | [2] | [3] | [4] | | --- | --- | --- | --- | | dfu1.png | dfu2_f407.png | dfu3.png | dfu4.png | --- # e-puck2 programmer development Source: https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development Last edited: 2020-06-17T05:58:24Z [e-puck2 main wiki](http://www.gctronic.com/doc/index.php?title=e-puck2) # Get the source code Link: https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development#Get_the_source_code The programmer firmware source code can be downloaded with the command: `git clone --recursive https://github.com/e-puck2/e-puck2-programmer` ## Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development#Building In order to build the firmware you need the `arm-none-eabi` toolchain installed. Then you can issue the following commands from the `src` directory of the repo root: `make clean` `make` The result is a bin file named `e-puck2_programmer.bin` that you can find in the `src/build` directory. # Configuring the Programmer's settings Link: https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development#Configuring_the_Programmer%27s_settings The on-board programmer of the e-puck2 is based on the [Blackmagic probe open source project](https://github.com/blacksphere/blackmagic/wiki) firmware. Some functionalities has been added on top of the original project to be able to control some functions of the robot, for example the power on or power off. To access to the available commands of the programmer, it is needed to connect to the programmer with a GDB console. To do so, you have to type the following command in a terminal window with the com port used by the '*e-puck2 GDB Server* port of your e-puck2 : ``` arm-none-eabi-gdb target extended-remote your_gdb_com_port ``` Once connected to the programmer with GDB, you can type ``` monitor help ``` or ``` mon help ``` to print the available commands of the programmer. One command in particular is useful, which is `mon select_mode`. It is used to select in which mode the **e-puck2 Serial Monitor** com port will work. mode 1 = the serial monitor is connected to the UART port of the main processor mode 2 = the serial monitor is connected to the UART of the ESP32 mode 3 = the serial monitor works as a Aseba CAN to USB translator The choice made for the mode is the only setting that is stored in a flash zone of the programmer, which means the choice is remembered, even if the robot is completely turned off. Note : in mode 1 and 3, GDB can be used over the bluetooth connection of the e-puck2. But it is much slower than with USB and it doesn't work with Windows due to GDB limitations on this OS. By being connected with GDB, you can also use the standard GDB command to program and debug the main processor of the e-puck2. --- # e-puck2 radio module development Source: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development Last edited: 2026-02-19T10:32:13Z [e-puck2 main wiki](http://www.gctronic.com/doc/index.php?title=e-puck2) # Introduction Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Introduction Espressif provides the [Espressif IoT Development Framework](https://github.com/espressif/esp-idf) (ESP-IDF for short), that is a framework for developing applications based on the Espressif ESP32 chip. The firmwares developed for the e-puck2 radio module are based on this framework. The software development framework provided by Espressif is intended for rapidly developing Internet of Things (IoT) applications, with Wi-Fi, Bluetooth, flexible power management and other advanced system features. Users can develop applications in Windows, Linux and MacOS based on ESP-IDF. The `C programming` language is used to develop code for the radio module of the e-puck2 robot and the ESP-IDF includes the FreeRTOS real time operating system. # Development environment Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Development_environment In order to build the firmware you need to install the toolchain for your OS, refer to . Once installed you can issue the command `make flash` from the directory `Projects\ESP32_E-Puck_2` to build the firmware. For more information have a look at . ## Debugging Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Debugging You can debug your code by printing some information on the serial port from your code, then from the PC you can read these information by opening the `Serial Monitor` port with a terminal program (have a look at the chapter [Finding the USB serial ports used](https://www.gctronic.com/doc/index.php?title=e-puck2#Finding_the_USB_serial_ports_used) to know what ports are availables). # Get the source code Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Get_the_source_code The radio module firmware source code can be downloaded with the command: `git clone --recursive https://github.com/e-puck2/esp-idf.git` ## WiFi Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#WiFi The radio module wifi firmware source code can be downloaded with the command: `git clone -b wifi --recursive https://github.com/e-puck2/esp-idf.git` ## BLE Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#BLE The module BLE firmware source code can be downloaded with the command: `git clone -b ble_spp_asercom --recursive https://github.com/e-puck2/esp-idf.git` ## Micropython Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Micropython The module Micropython firmware source code can be download from the repo Build instructions are available in the repository readme. # Communication with main microcontroller Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Communication_with_main_microcontroller The radio module and the main microcontroller are connected via 2 channels: UART and SPI. SPI is dedicated solely for exchanging the images captured by the main microcontroller, the UART channel instead is used to receive all sensors data and send commands. The UART communication protocol is based on the [advanced sercom protocol](http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol). The following figure shows the sensors packet received from the main microcontroller via UART. The packet size is 104 bytes. For more information about the values of each field refer to the [WiFi communication protocol section](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2): ![packet-format-robot-to-pc.jpg](https://www.gctronic.com/doc/images/5/5b/packet-format-robot-to-pc.jpg) The following figure shows the packet format to send to the main microcontroller via UART. For more information about the values of each field refer to the [WiFi communication protocol section](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2): ![packet-format-esp-to-f407.png](https://www.gctronic.com/doc/images/1/12/packet-format-esp-to-f407.png) ## Implementation Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Implementation Refer to the [WiFi branch](https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#WiFi) of the radio module firmware as implementation reference. The UART communication is implemented in the `uart_e-puck2.c` (separated task). First of all you need to initialize the channel with `uart_init();`, then you can exchange data by using the functions `uart_set_actuators_state` and `uart_get_data_ptr` to respectively send commands to the robot and receive sensors information. # Example projects Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Example_projects ## Mesh network Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Mesh_network The ESP32 radio module available in the e-puck2 robot lets you build a mesh network by using the latest version of the ESP-IDF framework. This example shows some of the features of the mesh network such as self-organization and self-healing and the network is configured with a fixed root node, this lets you build a mesh network without the need of an external router. This means that the robots can build a network and communicate between each other without the need of external devices. For more information on the mesh network implementation please visit . ### Preparation Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Preparation For running the demo you need at least 2 robots, but the more robots you have, the better. For each e-puck2 robot you need to program the radio module with the following firmware [e-puck2_mesh.zip (24.08.21)](https://projects.gctronic.com/epuck2/e-puck2_mesh_24.08.21_b6963a7.zip), refer to section [Radio module - Firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) for more information on how to flash the radio module. You can then place the robots wherever you want (at a reasonable distance), they will connect to each other. ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Usage There are 2 roles available for the demo, the root node and non-root node (can be parent/leaf nodes). Each role is chosen by using the user button (placed on the top of the robot, in the back side, near the speaker, have a look at ): if the button is pressed while turning on the robot then this the root node, otherwise this a non-root node. Beware to have only one root. Once the robots are turned on, they will build a network by themselves and the root node will broadcast on/off commands. The robot's color represents the network layer: pink=layer1, yellow=layer2, red=layer3, blue=layer4, white=disconnected. The network parameters configured in this example are: max childs=2, max layers=5 You can have a look at the following video as an example: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) It's worth noting that the connection to a parent node is based primarily on a RSSI threshold, basically if the parent has a lower RSSI than the threshold then it is discarded; by default this threshold is `-85`. By tuning the RSSI thresholds you can for example experimenting the mesh network in a tight space or you can also implement local communication by exploiting the multicast features offered by the mesh network implementation (e.g. send to nodes that are only distant at most 1 layer). The following video shows a 3 layers mesh network in about 30 cm: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Building In order to build the radio module firmware, follow these steps: 1. install the toolchain for your OS, refer to 2. clone the `ESP-IDF` (ESP32 framework) repository by issueing the command `git clone --recursive https://github.com/espressif/esp-idf.git` 3. clone the e-puck2-mesh example repository into the `examples` directory of the `ESP-IDF` by issueing the command `git clone https://github.com/e-puck2/e-puck2_mesh.git` 4. move to the directory `esp-idf/examples/e-puck2_mesh` and issue the command `idf.py build` to build the project, beware that you need to set up the environment variables (refer to [step-4-set-up-the-environment-variables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#step-4-set-up-the-environment-variables)). If you want you can change the mesh parameters (e.g. max layers, max childs, ...) by issueing `idf.py menuconfig` before building. 5. once the project is built, take the files `build/e-puck2_mesh.bin`, `build/bootloader/bootloader.bin` and `build/partition-table/partition-table.bin` and follow the instructions in the following link [Radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names ## COVID-19 Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#COVID-19 We implemented some basic concepts of local infection transmission and proximity tracing exploiting Bluetooth 4 on our robot e-puck2. The goal is to provide an open source framework and to visualize the positive effect of proximity tracing APP within a pandemic such as COVID-19. Such a simulation and demonstration can be extended by the community and we do not pretend that this initial effort is scientifically valid. However already with the initial parameters it becomes clear that self-quarantine triggered by a proximity tracing APP is beneficial. We implemented a simplified version of the [DP-3T protocol](https://github.com/DP-3T) (no actual code used from this repo).The following image shows a general overview of the architecture: ![general-architecture.png](https://www.gctronic.com/doc/images/0/0f/general-architecture.png) We use Bluetooth for both proximity tracing, as in reality, and infectivity, that is encoded in the advertisement packet together with the robot ID. The proximity of a robot is detected using the BLE signal strength. A computer is designed for acting as the DP-3T server, listening for incoming WiFi connections (TCP) from the robots and maintaining the list of infected robots. No privacy handling is involved. Here is a list of interesting features exploited from the robot capabilities: - simultaneous BLE scanning and advertising - BLE and WiFi cohexistence - proximity detection through BLE signal strength (RSSI) ### Preparation Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Preparation_2 For running the demo you need a computer acting as the server and at least 3 robots, even if the more robots you have, the better. For each e-puck2 robot you need to: - program the main microcontroller with the [factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) - program the radio module with the following firmware [esp32_covid.zip (20.05.20)](https://projects.gctronic.com/epuck2/esp32_covid_20.05.20_e8dbf14.zip), refer to section [Radio module - Firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) for more information on how to flash the radio module On the computer you need to install Python 3 in order to run the server script that you can download from here [server.py](https://github.com/e-puck2/COVID-19/blob/master/dp3t_server/server.py). Prepare an arena big enough to contain all the robots that will move around avoiding obstacles once turned on. ### Usage Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Usage_2 There are 3 roles available for the simulation; each role is chosen by using the selector position: - patient zero: this is the robot that will start the infection spread by starting being contagious; this is thought to be only one robot; selector position 0 - DP-3T actor: one or more robots; selector position 15(F) - no DP-3T actor: one or more robots; any selector position, but 15 and 0 For running the demo follow these steps: 1. Run the Python script on the computer 2. Take the robot chosen to be the patient zero; put the selector in position 15(F) then turn it on (the robot must be turned on with the selector in position 15(F)); after start, the top front LED will turn on for 3 seconds, during this period you need to select the role, in this case place the selector in position 0; then the LED will turn off and the robot will start moving around avoiding obstacles 3. Take the robot chosen to be a DP-3T actor; put the selector in position 15(F) then turn it on (the robot must be turned on with the selector in position 15(F)); after start, the top front LED will turn on for 3 seconds, during this period you need to select the role, in this case keep the selector in position 15(F); then the LED will turn off and the robot will start moving around avoiding obstacles. The robot will connect also to the server, beware that the server IP address is hard-coded in the software (192.168.1.8), thus if your server has a different IP address then you need to rebuild the firmware, refer to section [COVID19 - Building](https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Building) 4. Take the robot chosen to be a no-DP-3T actor; put the selector in position 15(F) then turn it on (the robot must be turned on with the selector in position 15(F)); after start, the top front LED will turn on for 3 seconds, during this period you need to select the role, in this case put the selector in position e.g. 14(E); then the LED will turn off and the robot will start moving around avoiding obstacles 5. Repeat step 3 and 4 for all the robots you want to use for each role Now have fun seeing how the simulation evolves. You can have a look at the following video as an example: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) The following state diagrams illustrate the details of the simulation; you can analyze them to deeply understand what is happening for each role. ![dp3t-simplified-general-schema.png](https://www.gctronic.com/doc/images/0/05/dp3t-simplified-general-schema.png) ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Building_2 In order to build the radio module firmware, follow these steps: 1. install the toolchain for your OS, refer to 2. clone the `ESP-IDF` (ESP32 framework) repository by issueing the command `git clone --recursive https://github.com/espressif/esp-idf.git` 3. clone the COVID-19 example repository into the `examples` directory of the `ESP-IDF` by issueing the command `git clone https://github.com/e-puck2/COVID-19.git` 4. move to the directory `esp-idf/examples/COVID-19/esp32_covid` and issue the command `idf.py build` to build the project, beware that you need to set up the environment variables (refer to [step-4-set-up-the-environment-variables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#step-4-set-up-the-environment-variables)) 5. once the project is built, take the files `build/esp32_covid.bin`, `build/bootloader/bootloader.bin` and `build/partition-table/partition-table.bin` and follow the instructions in the following link [Radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names ## Controlling the robot Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Controlling_the_robot This is an example project that shows how to communicate with the main microcontroller in order to change the actuators state and receive sensors data. Basically the robot is pivot rotated by 180 degrees by exploiting the data received from the gyroscope. This is a project thought to be used as a starting point. ### Preparation Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Preparation_3 For running the demo you need to: - program the main microcontroller with the [factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) and place the selector in position 15(F) - program the radio module with the following firmware [esp32_robot_control.zip (26.03.25)](https://projects.gctronic.com/epuck2/esp32_robot_control_26.03.25_47d23a0.zip), refer to section [Radio module - Firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) for more information on how to flash the radio module ### Building Link: https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#Building_3 In order to build the projet, follow these steps: 1. Get the ESP32 software development environment, refer to 1. clone the `ESP-IDF` (ESP32 framework) repository by issueing the command `git clone --recursive https://github.com/espressif/esp-idf.git` 2. set up the tools: `cd ~/esp/esp-idf` 3. set up the environment variables (refer to [step-4-set-up-the-environment-variables](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#get-started-set-up-env)) 2. clone the `esp32_robot_control` example repository by issueing the command `git clone https://github.com/e-puck2/esp32_robot_control.git` 3. move to the project directory `esp32_robot_control` and issue the command `idf.py build` to build the project 4. once the project is built, take the files `build/esp32_robot_control.bin`, `build/bootloader/bootloader.bin` and `build/partition-table/partition-table.bin` and follow the instructions in the following link [Radio module firmware update](https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names 1. Alternatively you can issue `idf.py -p /dev/ttyACM1 flash -b 115200` The example was tested to be working with esp-idf 5.2: 1. `git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git esp-idf_5.2` 2. `cd ~/esp/esp-idf_5.2` 3. `./install.sh esp32` 4. `. $HOME/esp/esp-idf_5.2/export.sh` 5. move to your desired directory and issue `git clone https://github.com/e-puck2/esp32_robot_control` 6. `cd esp32_robot_control/` 7. `idf.py build` 8. connect the robot, turn it on and then issue `idf.py -p /dev/ttyACM1 flash -b 115200` --- # e-puck2 mobile phone development Source: https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development Last edited: 2026-02-19T10:28:08Z [e-puck2 main wiki](http://www.gctronic.com/doc/index.php?title=e-puck2) # Robot configuration Link: https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#Robot_configuration For working with Bluetooth Low Energy, the main microcontroller must be programmed with the factory firmware and radio module must be programmed with a dedicated firmware (not the factory ones): - for the main microcontroller, refer to section [main microcontroller firmware update](http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update) - [radio module ble firmware (12.12.18)](https://projects.gctronic.com/epuck2/esp32-firmware-ble_12.12.18_bb3bd7e.zip), for information on how to update the firmware refer to section [radio module firmware update](http://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2) Put the selector in position 15(F). Section [Connecting to the BLE](http://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#Connecting_to_the_BLE) gives step by step instructions on how to accomplish your first BLE connection with the robot. # Connecting to the BLE Link: https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#Connecting_to_the_BLE A minimal mobile application for both Android and iOS platforms was implemented as a starting point for further development. The built Android application can be downloaded from [e-puck2-android-ble.apk](https://projects.gctronic.com/epuck2/e-puck2-android-ble.apk). This application lets you connect to the robot and once connected, the phone receives the proximity sensors data and you can also send motion commands to the robot. Follow these steps to connect to the robot: 1. Turn on the robot, it will start advertising as `E-PUCK2_BLESPP`. 2. Install the application in your phone and turn on Bluetooth (beware that your phone must support Bluetooth 4) 3. Open the application `e-puck2 monitor BLE` and click on the `Connect` button; the robot should appear in the list of discoverable devices as shown in the following figure 4. Select the robot and the connection will be established. If it doesn't work the first time, retry once more; if you still have connection problems try by switching off and on again the Bluetooth 5. Now you will receive the sensors data and you can pilot the robot as shown in the following figure ![e-puck2-ble-app1.png](https://www.gctronic.com/doc/images/9/9b/e-puck2-ble-app1.png) ![e-puck2-ble-app2.png](https://www.gctronic.com/doc/images/b/b4/e-puck2-ble-app2.png) # Get the source code Link: https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#Get_the_source_code The main microcontroller firmware source code can be downloaded with the command: `git clone --recursive https://github.com/e-puck2/e-puck2_main-processor.git` The radio module ble firmware source code can be downloaded with the command: `git clone --recursive -b ble_spp https://github.com/e-puck2/esp-idf.git esp-idf_ble` The Android application source code can be downloaded from the following link [e-puck2_ble_monitor.zip](https://projects.gctronic.com/epuck2/e-puck2_ble_monitor.zip). It's an `Android Studio` project. The iOS application source code can be downloaded from the following link [epuck2_ble_monitor_ios.zip](https://projects.gctronic.com/epuck2/epuck2_ble_monitor_ios.zip). ======================================================================== TOPIC: e-puck1 Documentation for the first e-puck robot version (e-puck1). Do not apply this information to e-puck2 and do not apply information regarding e-puck2 to e-puck1. ======================================================================== # E-Puck Source: https://www.gctronic.com/doc/index.php?title=E-Puck Last edited: 2026-07-22T13:29:50Z # Hardware Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Hardware ## Revisions Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Revisions There are three hardware revisions: - HWRev 1.1: models from 0 to 1499 - HWRev 1.2: models from 1500 on, production of June 2008 - HWRev 1.3: models from 3320 on, production August 2014 The following table summarizes the differences between revisions: | | Camera | Bluetooth | Accelerometer | Microphone | | --- | --- | --- | --- | --- | | HWRev 1.1 | PixelPlus PO3030 (VGA) | LMX9820 Bluetooth 1.1 | MMA7260 3-axes analog acclerometer | SiSonic SP0103NC3-3 | | HWRev 1.2 | PixelPlus PO6030 (VGA) | LMX9838 Bluetooth 2.0 | MMA7260 3-axes analog acclerometer | SiSonic SPM0208HD5 | | HWRev 1.3 | PixelPlus PO8030 (VGA) | LMX9838 Bluetooth 2.0 | LSM330 3-axes digital (I2C) acclerometer + 3-axes gyroscope | SiSonic SPU0414HR5H-SB | The updated e-puck library handles automatically the various hardware revisions in order to be compatible with the existing standard software. ### Camera Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Camera The orientation of the camera is different in each hardware revision and also in the case of HWRev 1.1 the same camera model can be oriented differently, here is an image that shows the different cameras and related orientation: ![epuck-cameras.jpg](https://www.gctronic.com/doc/images/c/ca/epuck-cameras.jpg) The e-puck library configures the camera in order to get the right orientation for all situations except when it is rotated by 90 degrees. In order to let the user distinguish the current camera mounted on the robot and in case it is rotated by 90 degrees apply the related processing, the EEPROM is modified based on the camera model mounted on the robot and its orientation. This modification follow these rules: the modification apply only to the last word of the EEPROM, at address 0x7FFFFE; bits 14 and 15 are used to indicate the rotation (11=no rotation, 01=90 degrees, 10=-90 degrees, 00=180 degrees), bits 12 and 13 are used to indicate the camera model (11=PO3030, 10=PO6030, 01=PO8030). The possible values for the EEPROM are thus: - 0xFFFF (0xFFF1111): PO3030 with no rotation - 0xFFFE (0xFFF1110): PO3030 turned by -90 degrees - 0xFFF9 (0xFFF1000): PO6030 turned by 180 degrees - 0xFFF7 (0xFFF0111): PO8030 with no rotation The following example illustrates how to read this word: ``` #include /*read HW version from the eeprom (last word)*/ int HWversion=0xFFFF; int temp = 0; temp = ReadEE(0x7F,0xFFFE,&HWversion, 1); ``` This project ([src](https://projects.gctronic.com/E-Puck/writeEEPROMsrc.zip)) is an example on how to write the last word of the EEPROM. Beware that not all robots are shipped with the EEPROM programmed as specified previously. It is up to the user to check this modification by simply using the advanced sercom demo (selector in position 3) and requesting the version (command `v`); the hardware version returned by the command corresponds to the value of the last word of the EEPROM. ### Accelerometer Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Accelerometer The actual accelerometer mounted on the robot is automatically detected by the library at startup. The values ranges of the digital accelerometer are different from the analog accelerometer, but the library scale them to be similar in order to be compatible with the existing demos. The orientation of the accelerometer is shown below, the x axis points left, the y axis points forward and z points upward: ![epuck-acc-directions.png](https://www.gctronic.com/doc/images/9/99/epuck-acc-directions.png) For users playing with e-puck HWRev1.3 and gumstix extension refer to section [Accelerometer and gyroscope (e-puck_HWRev_1.3)](https://www.gctronic.com/doc/index.php/Overo_Extension#Accelerometer_and_gyroscope_.28e-puck_HWRev_1.3.29). ### Microphone Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Microphone From HWRev 1.3 the microphone sensitivity resulted a little bit different from the previous hardware revision; some empirical tests show that the difference is about ±15% so beware to adapt the thresholds in your applications if you need. ### Gyroscope Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Gyroscope The gyroscope is available from HWRev 1.3. The orientation of the gyro is shown below, the x axis points forward, the y axis points left and the z axis points upward: ![epuck-gyro-directions.png](https://www.gctronic.com/doc/images/f/f7/epuck-gyro-directions.png) For users playing with e-puck HWRev1.3 and gumstix extension refer to section [Accelerometer and gyroscope (e-puck_HWRev_1.3)](https://www.gctronic.com/doc/index.php/Overo_Extension#Accelerometer_and_gyroscope_.28e-puck_HWRev_1.3.29). ## Specifications Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Specifications The hardware specifications are valid for all e-puck models, except when explicitly specified with an hardware revision. - **Microcontroller**: Microchip dsPIC30F6014A - [dsPIC30F6011A/6012A/6013A/6014A Data Sheet](https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F6011A-6012A-6013A-6014A.pdf) - [dsPIC30F Family Reference Manual](https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F-family-reference-manual.pdf) - [dsPIC30F/33F Programmer's Reference Manual](https://projects.gctronic.com/E-Puck/docs/dsPIC30F/dsPIC30F_Programmers_reference_manual.pdf) - **Camera**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=5&Itemid=14) - **HWRev 1.1**: PixelPlus PO3030K CMOS image sensor, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/Camera/PO3030K.pdf), no IR cut filter - **HWRev 1.2**: PixelPlus PO6030K CMOS image sensor, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/Camera/PO6030K.pdf), no IR cut filter - **HWRev 1.3**: PixelPlus PO8030D CMOS image sensor, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/Camera/PO8030D.pdf), no IR cut filter - **Bluetooth**: - **HWRev 1.1**: National Semiconductor LMX9820A Bluetooth Serial Port Module, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/BT/lmx9820.pdf), [Software User Guide](https://projects.gctronic.com/E-Puck/docs/BT/lmx9820-sw-user-guide.pdf) - **HWRev 1.2 and 1.3**: Texas Instruments LMX9838 Bluetooth Serial Port Module, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/BT/lmx9838.pdf), [Software User Guide](https://projects.gctronic.com/E-Puck/docs/BT/lmx9838-sw-user-guide.pdf) - **Microphone**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=19&Itemid=11) - **HWRev 1.1**: Silicon Labs Si3000 Voice Codec, [Knowles Acoustics SiSonic SP0103NC3-3 microphone with integrated amplifier](https://projects.gctronic.com/E-Puck/docs/Audio/SP0103NC3.pdf) - **HWRev 1.2**: [Knowles Acoustics SiSonic amplified mini microphone SPM0208HD5](https://projects.gctronic.com/E-Puck/docs/Audio/SPM0208HD5.pdf) - **HWRev 1.3**: [Knowles Acoustics SiSonic amplified mini microphone SPU0414HR5H-SB](https://projects.gctronic.com/E-Puck/docs/Audio/SPU0414HR5H-SB.pdf) - **Optical sensors**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=22&Itemid=13) - Vishay Semiconductors Reflective Optical Sensor [Data Sheet](https://projects.gctronic.com/elisa3/tcrt1000.pdf) - **Accelerometer**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=21&Itemid=12) - **HWRev 1.1 and 1.2**: Freescale Semiconductor MMA7260Q three axis accelerometer, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/Accelerometer/MMA7260Q-Rev1.pdf) - **HWRev 1.3**: STMicroelectronics LSM330 3D accelerometer and 3D gyroscope, [Data Sheet](https://projects.gctronic.com/E-Puck/docs/acc+gyro/LSM330.pdf) - **Motors**: [details](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=7&Itemid=9) ## Serial communication Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Serial_communication The communication between the robot and the computer can be also handled with a serial cable; the serial connector position on the robot, the related cable and the electric schema are shown on the following figures. ![E-puck-serial-connector.jpg](https://www.gctronic.com/doc/images/1/1a/E-puck-serial-connector.jpg) ![serial-cable-shop.jpg](https://www.gctronic.com/doc/images/1/15/serial-cable-shop.jpg) ![RS232_connector_EJumper.gif](https://www.gctronic.com/doc/images/f/f0/RS232_connector_EJumper.gif) In order to communicate with the robot through a serial line, the robot firmware must be implemented using the functions of the UART2 instead the one of UART1 (BT). All the functions implemented for the UART1 are also available for the UART2, so it's only a matter of changing the function call names. Anyway the [standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) contains already a mode that communicates over serial line selecting position 11; in this mode you can configure the BT. ## I2C communication Link: https://www.gctronic.com/doc/index.php?title=E-Puck#I2C_communication The camera, the ground sensors extension, the accelerometer (e-puck HWRev 1.3 only) and the gyro (e-puck HWRev 1.3 only) are connected to the I2C bus as slave devices (the microcontroller is the master). The `y` command of the [Advanced sercom protocol.](http://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol) can be used to read the registers values of these sensors. For instance you can read the camera id with the following commands: `y,220,0` and `y,220,1` that return respectively `128=0x80` and `48=0x30` (id=8030). In the same way you can read any register with the general command `y,220,REG_ADDR`. For the accelerometer you must use `60` as device address (`y,60,REG_ADDR`) and for the gyro you must use `212` (`y,212,REG_ADDR`). The device address value to be used with the `y` is obtained by shifting by one position left the I2C 7-bit address of the device, for example the camera 7-bit address is `0x6E`, by shifting one position left we get `0xDC=220`. ## Batteries Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Batteries ### Battery from 2016 (last quarter) on Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Battery_from_2016_(last_quarter)_on The new batteries of 2016 are bit heavier (38g) but a bit more powerful (1800 mAh). The look is similar to the previous batteries and they are of course compatible with the robot and the charger. Take care when inserting the battery in the robot to not scratch the plastic sticker. You would need to apply a bit more force than before when inserting and removing the battery. The battery is covered with a plastic protection in order to avoid any possible short circuit during inserting/removing of the battery. The battery can be inserted only in one way: the side where the plastic protection do not cover completely the battery "top" must be towards the ground. **DO NOT REMOVE THE BLACK PLASTIC PROTECTION!** ![battery-epuck-2016.jpg](https://www.gctronic.com/doc/images/8/8f/battery-epuck-2016.jpg) ![battery-epuck-2016-2.jpg](https://www.gctronic.com/doc/images/d/d2/battery-epuck-2016-2.jpg) ![battery-epuck-2016-3.jpg](https://www.gctronic.com/doc/images/8/81/battery-epuck-2016-3.jpg) This battery doesn't fit perfectly in older chargers, but it can be inserted anyway in the charger in order to make a good contact and charge it; when the contact is ok you will see the led turned on. ![batt2016-charger-side.jpg](https://www.gctronic.com/doc/images/a/a7/batt2016-charger-side.jpg) ![batt2016-charger-top.jpg](https://www.gctronic.com/doc/images/2/26/batt2016-charger-top.jpg) ### Battery from 2013 to 2016 Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Battery_from_2013_to_2016 The new batteries of 2013 are lighter (33g) and a bit more powerful (1600 mAh). The look is different but they are of course compatible with the robot and the charger. Take care when inserting the battery in the robot to not scratch the plastic sticker. Is not a safety issue but keep them nice as in the beginning ;-). The battery is covered with a plastic protection in order to avoid any possible short circuit during inserting/removing of the battery. **DO NOT REMOVE THE PLASTIC PROTECTION!** ![battery-epuck-new1.jpg](https://www.gctronic.com/doc/images/9/97/battery-epuck-new1.jpg) ![battery-epuck-new2.jpg](https://www.gctronic.com/doc/images/3/38/battery-epuck-new2.jpg) ### Battery up to 2012 Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Battery_up_to_2012 The robots delivered in 2012 had a small difference regarding the battery; the type of battery is always the same but the mechanics of the positive pin is slightly different from one version to the other. The version with the black plastic cover comes out a bit more then the version with the brown cardboard cover. ![Batt-covers.jpg](https://www.gctronic.com/doc/images/b/b2/Batt-covers.jpg) The e-puck contact has been slightly modified to have a better contact with both versions as shown in the following figure; see the [Contact-modification.pdf](https://projects.gctronic.com/E-Puck/docs/contact-modification.pdf) document to get more information on how to apply this modification. ![Battery-contact.jpg](https://www.gctronic.com/doc/images/b/bb/Battery-contact.jpg) The charger makes contact with both versions, as illustrated below. ![Batt-charger.jpg](https://www.gctronic.com/doc/images/9/97/Batt-charger.jpg) The positive pin has the tendency to get a bit oxidated and might need to be scratched a bit for a perfect connection. ### Charger circuit diagram Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Charger_circuit_diagram The circuit diagram of the e-puck charger is available on the following link [charger-circuit-diagram.png](https://www.gctronic.com/doc/images/charger-circuit-diagram.png). # Software Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Software ## Getting started Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Getting_started The robot is shipped with a standard firmware that let you immediately interact with the robot, follow these steps: 1) put the robot selector in position 3 2) turn on the robot and pair it with the computer: - if you're running Linux use the system bluetooth manager to pair the robot with the computer and then issue the command *sudo rfcomm bind /dev/rfcomm0 10:00:E8:C5:61:C9*, where *10:00:E8:C5:61:C9* is the BT mac address of the robot - if you're running Windows there is a detailed guide from the [e-puck.org tutorials](https://e-puck.gctronic.com/index.php?option=com_phocadownload&view=category&id=5:tutorials&Itemid=38), here is a direct link to the guide [BTboot epuck gettingstarted](https://projects.gctronic.com/E-Puck/BTboot-epuck-gettingstarted.pdf) (refer to chapter 2.3, page 6) 3) execute a terminal program (e.g. minicom for Linux or teraterm for Windows) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/rfcomm0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No" 4) type *h+ENTER* and you'll be prompted with a menu that contains all the commands you can issue to the robot, for instance you can retrieve the sensors values or turn on the leds ## Library Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Library The embedded software running on the e-puck is continuously extended and managed in the following git repo . The repo comprises a complete library to work with all the sensors mounted on the e-puck and is the basis for many demos. You can download the library documentation form the following link [e-puck-library.pdf](https://projects.gctronic.com/E-Puck/e-puck-library.pdf). The content of the repo is the following: - library: this is the low level library of the e-puck - program: - "Bluetooth mirror": interact with the Bluetooth chip through serial cable - "BTCom": basically it is the "asercom" implementation, refer to [Advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol) - EPFL demo project: some nice demos bundled in one project, such as sound source location, obstacle avoidance and color blob detection (red and green). Some of these demos are included in the GCtronic standard firmware. - GCtronic standard firmware project, refer to section [Standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) - tool: - computer-side and e-puck side bootloader - matlab interface/monitor for e-puck - C++ interface/monitor for e-puck In order to download a snapshot of the repo, go to the page and then click on the green botton named `Clone or download` and select `Download ZIP` as shonw in the following figure. ![e-puck-snapshot.png](https://www.gctronic.com/doc/images/b/b0/e-puck-snapshot.png) ### Structure Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Structure As previously mentioned the git repository includes a library to which many demos are linked. Only updates to this library that will be useful to others people and/or correct errors should be commited; some demos of this wiki makes changes to the library for the solely purpose of running the demo and thus they aren't commited to the repo. In order to separate the original e-puck library from what is modified in the library for the current demo, all the projects (created with MPLAB) share the same structure, that is they have to be placed within the *program* folder of the repository and must contain only the files of the library (and their dependencies) that have been modified. An example of this structure is shown afterwards: - e-puck-library - library - a_d - bluetooth - ... - program - project1 - a_d - e_prox.c - project2 - ... - tool The library folder basically never change (unless bug fixes or new features for all users are developed). All the projects have a reference to this library folder in their build options. If some library files are modified for the current project, they are inlcuded in the project folder following the same structure of the original library, as shown for *project1*. In order to build the project you then need to add all the modified library files from the project directory and all the others files from the main library folder. Not all files are always needed, it depends on the features that are used; for instance if the camera isn't used, the related library file could be omitted from the project saving memory space. ## Standard firmware Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Standard_firmware The robot is initially programmed with a firmware that includes many demos that could be started based on the selector position: - Selector position 0: Shock detection. Look at runaccelerometer.h for more information. - Selector position 1: Detect the sound source. Look at rundetectsound.h for more information. - Selector position 2: Follow the wall. Look at runwallfollow.h for more information. - Selector position 3: [Advanced sercom protocol.](http://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol) - Selector positoin 4: Let the robot move in a square path (using either odometry or gyroscope). - Selector position 5: Sensor "feedback display". - Selector position 6: Camera points to light. - Selector position 7: Act like the ASL RS232 - I2C translator. - Selector position 8: Show the ground direction. Look at rungrounddirection.h for more information. - Selector position 9: Show the rotation rates of the gyroscope axes. Look at the rungyroscope.h for more information. - Selector position 10: This position is used to work with the gumstix extension. - Selector position 11: Bluetooth configuration (serial communication). - Selector position 12: Global test (serial communication). - Selector position 13: Uart1 to uart2 transponder. - Selector position 14: Follow what is detected by the two front proximities detectors. Look at runbreitenberg_adv.h for more information. - Selector position 15: Simple dust cleaner behaviour. The pre-built fimrware is available from [DemoGCtronic-complete.hex](https://projects.gctronic.com/E-Puck/DemoGCtronic-complete/DemoGCtronic-complete-4bba145.hex). You can have a look at the source code from the following link ; beware that the project is actually included in the e-puck library repository, refer to section [Library](https://www.gctronic.com/doc/index.php?title=E-Puck#Library) to download it. ### Project building Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Project_building In order to build the project you need to install the MPLAB X IDE and related compiler, refer to section [Programming: MPLAB X](https://www.gctronic.com/doc/index.php?title=E-Puck#MPLAB_X). The standard firmware project is based on the e-puck library (refer to [Library](https://www.gctronic.com/doc/index.php?title=E-Puck#Library) section). To build the project follow these steps: 1) download and extract the e-puck library repository (refer to section [Library](https://www.gctronic.com/doc/index.php?title=E-Puck#Library)), let say in the folder `e-puck-library`; you should have the following situation: - e-puck-library - library - program - ... - DemoGCtronic-complete - tool 2) Open MPLAB X, then click `File=>Open Project` and select the project file `demoGCtronic.X` you can find in `e-puck-library\program\DemoGCtronic-complete`. If you're asked to upgrade the project to the current IDE version, click `yes` to confirm. 3) Right click on the project name (on the left panel) and select `Properties` as shown in the following figure: ![e-puck-project-build1.png](https://www.gctronic.com/doc/images/7/70/e-puck-project-build1.png) 4) Select the `XC16` compiler from the `Compiler Toolchain` section and then click `OK` as shown in the following figure: ![e-puck-project-build2.png](https://www.gctronic.com/doc/images/2/27/e-puck-project-build2.png) 5) Open the project properties once more (right click on project name and then select `Properites`), a new configuration will be available for the XC16 compiler. On the left panel select `xc16-gcc`, then on the right specify `Memory model` and verify that the `Code model` is set to `Large`. Confirm with `OK` as shown in the following figure: ![e-puck-project-build3.png](https://www.gctronic.com/doc/images/6/6c/e-puck-project-build3.png) 6) Now you can build the project by clicking on the `Build project` button (hammer icon on the top) or by pressing `F11`; if all is working you should end up with a successfully built firmware as shown in the following figure: ![e-puck-project-build4.png](https://www.gctronic.com/doc/images/f/f0/e-puck-project-build4.png) ## Programming Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Programming ### MPLAB X Link: https://www.gctronic.com/doc/index.php?title=E-Puck#MPLAB_X If you are interested in development of embedded applications, you should firstly choose an adequate development environment. One of the most known IDE is the `MPLAB Integrated Development Environment` that you could download for free from the Microchip site; Microchip offers also the C compiler for free. One big advantage of this IDE is that it is multiplatform (Windows, Linux, Mac) and also the compiler is available for each platform. To work with the e-puck software you need to: - download and install the [MPLAB X IDE](https://www.microchip.com/mplab/mplab-x-ide); during installation select also `MPLAB IPE` to be installed, it is a nice utility to have - download and install the [compiler](https://www.microchip.com/mplab/compilers), it must be the `MPLAB XC16` (supports all 16-bit PIC MCUs and dsPICs) Useful information related to the compiler can be found in the [MPLAB XC16 C compiler user's guide](https://projects.gctronic.com/E-Puck/docs/Programming/MPLAB_XC16_C_compiler_users_guide.pdf). ### Aseba Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Aseba Aseba is a set of tools which allow novices to program robots easily and efficiently, refere to for more information. Here is the page with the basic information needed to start working with Aseba and the e-puck robot . You can download an MPLAB X project based on the git repo in the following link [aseba.zip](https://projects.gctronic.com/E-Puck/aseba.zip); place it in the "e-puck-library/program" folder (refer to section for more information on how to build). You can download the last aseba firmware for the e-puck from the following link [aseba-target-epuck.hex](https://projects.gctronic.com/E-Puck/aseba-target-epuck.hex). Beware that at the moment the only bootloader capable of uploading the *aseba-target-epuck.hex* to the robot is the Linux version. ### Python Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Python Python is a widely used programming language supported by a large and comprehensive standard library. A Python library is available enabling the remote control of the e-puck robot, read the sensors values, control the motors while running the heavy processes on a computer. You can start playing with the e-puck and Python by downloading the [e-puck python package](https://projects.gctronic.com/E-Puck/epuck-python.zip), it contains: - [Python 2.6.6](https://www.python.org/download/releases/2.6.6/) - [Python setup tools](https://pypi.python.org/pypi/setuptools) - e-puck Python library: [source](https://github.com/mmartinortiz/pyePuck) - e-puck Python library dependencies: [pybluez](https://github.com/karulis/pybluez), [Python imaging library](https://pillow.readthedocs.io/en/stable/) - some examples (refers to [examples](https://github.com/mmartinortiz/pyePuck/tree/master/examples)) Follow these steps to install Python and run your first Python example (this instructions are for Windows but the procedure should be similar also for Linux and Mac OS): 1. Install Python (the executable *python-2.6.6.msi* is in the *Python2.6* directory) 2. Install the Python setup tools by running the script *ez_setup.py* you find in the *Python2.6* directory: 1. issue the command *python ez_setup.py* in a terminal 2. alternatively you can download an IDE that will help you in programming, run and debug your code; a valid IDE is called [PyCharm](https://www.jetbrains.com/pycharm/) 3. Install e-puck Python library dependencies: 1. install pybluez by issueing the command *python setup.py install* in a terminal (be sure to be in the *dependencies\pybluez-master* directory) 2. install the PIL library by executing *PIL-1.1.7.win32-py2.6.exe* you find in the *dependencies* directory 4. Program the e-puck with the last [standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) and put the selector in position 3 5. Configure the Bluetooth connection with the e-puck in the computer (add Bluetooth device and insert its pin) 1. when you add the e-puck robot as Bluetooth device, right click on the device and choose property; in the "Bluetooth" tab you'll find the mac address (something like 10:00:e8:c5:61:c9). Copy this address since you'll need it to connect to the robot when running the Python scripts 6. In the *examples* directory you'll find the e-puck library *ePuck.py* and 3 examples *braitenberg.py*, *line_follower.py*, *photo_taker.py* 1. the *ePuck.py* file must be placed in the same directory as your script 2. to run an example issue the command *python script_name.py mac_address*, where *script_name* is either *braitenberg* or *line_follower* or *photo_taker* and *mac_address* is the address that you previously annotate (e.g. *10:00:e8:c5:61:c9*) ## PC interface Link: https://www.gctronic.com/doc/index.php?title=E-Puck#PC_interface An interface running on a computer and connecting to the e-puck through bluetooth based on the advanced sercom protocol (selector 3) was developed; from this interface it's possible to have information about all the sensors, receive camera images and control the leds and motors. The source code is available from the following links: - Multiplatform version 3.0 ([Monitor3.0 source code](https://projects.gctronic.com/E-Puck/Monitor/MultiPlatformMonitorSrc1.8.zip)); the application is a Qt project, so the compilation may be handled easily with [Qt Creator](https://www.qt.io/product/development-tools); alternatively [qmake](https://doc.qt.io/qt-6/qmake-manual.html) can be used. The following executables are compiled dynamically, so the [Qt library (4.5.0 or higher)](https://www.qt.io/download) must be installed in the system in order to run them: - [Linux executable](https://www.gctronic.com/doc/images/EPuckMonitor): before running the executable, type "chmod +x file" - [MacOS executable](https://www.gctronic.com/doc/images/EPuckMonitor.app.zip) - [Windows executable (+ dlls); tested on Windows XP, Windows Vista, Windows 7, Windows 10](https://www.gctronic.com/doc/images/EPuckMonitorWin.zip) ![Monitor3.0.jpg](https://www.gctronic.com/doc/images/4/45/Monitor3.0.jpg) Since the last version comprises a basic OpenGL representation of the e-puck you will need also the OpenGL extension libraries in order to compile the project; these should be included in the Qt SDK, but if you encounter problems refers to [qtopengl](https://doc.qt.io/qt-6/qtopengl-index.html); basically you need to download manually the OpenGL libraries: GLX (Linux), CGL (MacOS), WGL (Windows). Once the project is built dynamically, some errors about missing dll may be thrown; one of these missing libraries could be the [mingwm10.dll](https://projects.gctronic.com/E-Puck/Monitor/mingwm10.dll). Others could be related to Qt. To solve the problem you need either to build the project statically, or to register the libraries on the system, or to manually include all the dll with the executable. ## Connecting to multiple robots Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Connecting_to_multiple_robots A Python example is available for e-puck2 in the following section [PC side development: Connecting to multiple robots](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_multiple_robots). This example is compatible also with the e-puck1 robot. ## Examples Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Examples ### Basic demos Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Basic_demos The following set of simple programs for the e-puck has an increasing degree of complexity, from very basic LED blinking up to motor control depending on sensor input; it's a good starting point for beginner users. The first demos do not use interrupts and keep to a minimum the use of the library. You can download the set of these demos from this link [BasicDemos.zip](https://www.gctronic.com/doc/images/BasicDemos.zip). A list of these basic programs is listed below: - demo0: very simple LEDs blinking - demo1: LEDs blinking (pause with timer) - demo2: selector reading + LEDs - demo3: send selector position via Bluetooth (simplified method) - demo4: proximity reading with interrupts + LEDs - demo5: proximity reading with interrupts + LEDs + send values via BT (assembler version with interrupt and buffer) - demo6: motor speed controlled depending on front proximity sensor values Compilation: the demos can be edited and compiled using MPLAB IDE (windows), clicking directly on the project file. The demos should be compiled with MPLAB-C30 on all operating systems. The compiled .hex file is downloaded to the e-puck robot via Bluetooth using for example tinyBootloader. ### Audio recording Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Audio_recording This demo program ([hex file](https://projects.gctronic.com/E-Puck/DemoGCtronic-recording/DemoGCtronic-recording.hex), [MPLAB project](https://projects.gctronic.com/E-Puck/DemoGCtronic-recording/DemoGCtronic-recording.zip)) let the e-puck recording for about two seconds whatever you like and then reproduces it infinitely. The program starts with a led animation (flow) and then turns all leds on for about two seconds, this is the moment for recording; note that only the right micro (mic0) is used. It's possible also to choose the volume/amplification of the reproduction using the selector (from 1 to 16). ### Still images Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Still_images This demo program is optimized to let the robot handle images with resolution up to 640x480 pixels (the maximum reachable by the camera); after acquisition, the robot sends the images to a computer through bluetooth. This zip [ImageReceiverBT.zip](https://projects.gctronic.com/E-Puck/ImageReceiverBT.zip) contains both the program for the robot (hex file) and the application for the computer (Windows platform). The selector of the robot must be in position 3. You can find the sources for the application running on the computer side from this link [ImageReceiverBTsrc.rar](https://projects.gctronic.com/E-Puck/ImageReceiverBTsrc.rar). You can find the MPLAB project for the application running on the robot from this link [DemoGCtronic-vga-images.zip](https://projects.gctronic.com/E-Puck/DemoGCtronic-vga-images.zip). ### Robots Collective Behavior Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Robots_Collective_Behavior This is a Bachelor project developed by Jean-Roch Lauper at the [University of Fribourg](https://www.unifr.ch/). The project's focus is on collective behaviors as well as on the use of sound to communicate between robots; moreover there are demos to interact with the robot through sensors and play with sound. The code is available on [Github](https://github.com/jrlauper/jrl_epuck). Demo videos are available on [Youtube](https://www.youtube.com/playlist?list=PLrscHgSUZPdr38tirAsB4_4Q93khKP9Rv). ## Bootloader Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Bootloader - Windows: [Tiny Bootloader v1.10.6](https://projects.gctronic.com/E-Puck/TinyBld_1_10_6_pc_beta.zip) or [Tiny Multi Bootloader+](https://sourceforge.net/projects/tinypicbootload/) - Linux: [epuck-bootloader-linux.zip](https://projects.gctronic.com/E-Puck/epuck-bootloader-linux.zip) - requirements: `sudo apt-get install libbluetooth-dev` - Mac OS: - actually it is a Perl script, thus in principle it could be used also in Linux and Windows - after pairing with the robot, you should issuing a command similar to `./epuckupload -f firmware.hex /dev/tty.e-puck_3675-COM1` and then press the reset button on the robot ## Others tools Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Others_tools From the official e-puck site you can find information about others software tools available for the e-puck robot in the following link . ### Local communication Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Local_communication An example of such tools is the [libIrcom](https://e-puck.gctronic.com/index.php?option=com_content&view=article&id=32&Itemid=28), a local communication library exploiting the proximity sensors placed around the robot to modulate infrareds. If an higher throughput and longer communication distance are required, there is the [range and bearing extension](https://www.gctronic.com/doc/index.php/Others_Extensions#Range_and_bearing) designed for this purpose. # ROS Link: https://www.gctronic.com/doc/index.php?title=E-Puck#ROS This chapter explains how to use ROS with the e-puck robots; basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. Both Pyhton and cpp versions are implemented to give the user the possibility to choose its preferred programming language. Here is a general schema: ![epuck-ros-schema.png](https://www.gctronic.com/doc/images/9/9c/epuck-ros-schema.png) *Click to enlarge* First of all you need to install and configure ROS, refer to for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [virtual machine](https://www.gctronic.com/doc/index.php/E-Puck#Virtual_machine); this is the preferred way. : - This tutorial is based on ROS Hydro. - If you downloaded the pre-installed VM you can go directly to section [Running the ROS node](https://www.gctronic.com/doc/index.php/E-Puck#Running_the_ROS_node). The ROS epuck driver was initially developed by the [Verlab Laboratory at Universidade Federal de Minas Gerais](https://www.verlab.dcc.ufmg.br/), the related code can be found in the following repository . It is based on [rospy](https://wiki.ros.org/rospy) (Python). We extended the initial driver to support all the e-puck sensors, the code can be found in the following repository . Starting from the work done with the ROS epuck driver for python, we developed another ROS node based on roscpp that has the same functionalities; the code can be found in the following repository . ## Initial configuration Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Initial_configuration The following steps need to be done only once after installing ROS: : 1. If not already done, create a catkin workspace, refer to . Basically you need to issue the following commands: ``` mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd ~/catkin_ws/ catkin_make source devel/setup.bash ``` : 2. You will need to add the line `source ~/catkin_ws/devel/setup.bash` to your .bashrc in order to automatically have access to the ROS commands when the system is started : 3. Clone the ROS epuck driver repo: - if you are working with Python: from ; you'll have a directory named epuck_driver that is the repo local copy - if you are working with cpp: from ; you'll have a directory named epuck_driver_cpp that is the repo local copy : 4. Copy the repo directory epuck_driver or epuck_driver_cpp (this is the actual ros package) inside the catkin workspace source folder (~/catkin_ws/src) : 5. Install the dependencies: - Python: - The ROS epuck driver is based on the e-puck Python library that requires some dependencies: - install the Python setup tools: `sudo apt-get install python-setuptools` - install the Python image library: `sudo apt-get install python-imaging` - install pybluez: - download [pybluez](https://github.com/karulis/pybluez) and extract it - install pybluez dependencies: `sudo apt-get install libbluetooth-dev` - go to the pybluez directory and issue the command `python setup.py install` - cpp: - install the library used to communicate with Bluetooth: `sudo apt-get install libbluetooth-dev` : 6. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make`, there shouldn't be errors : 7. Program the e-puck with the last [standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) and put the selector in position 3 ## Running the ROS node Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Running_the_ROS_node First of all get the last version of the ROS epuck driver from github: - Python: clone the repo and copy the epuck_driver directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src) - cpp: clone the repo and copy the epuck_driver_cpp directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src) Finally build the driver by opening a terminal and issueing the command `catkin_make` from within the catkin workspace directory (e.g. ~/catkin_ws). If you're using Pyhton make sure the node is marked as executable by opening a terminal and issueing the following command from within the catkin workspace directory (e.g. ~/catkin_ws): `chmod +x ./src/epuck_driver/scripts/epuck_driver.py`. Now you can finally start the ROS node, for this purposes there are two launch scripts (based on [roslaunch](https://wiki.ros.org/roslaunch)), one for working with a single robot and the other to work with multiple robots. Before actually starting the node you need to configure the e-puck robot as Bluetooth device in the system and copy its mac address (this will be needed when launching the ROS node); if you want to work with multiple robots you need to add all of them as Bluetooth devices in the system and copy all the mac addresses. The procedure to add a Bluetooth device is: 1. Go to System Settings (left panel has a link) 2. Click on Bluetooth 3. Click on the + sign in the bottom left of the window to start the procedure 4. Turn on the robot and click continue, now the search is started and after a little while the robot should appear on the list of found devices 5. Click on PIN Options..., select Cutom PIN, enter the correct robot PIN (robot id) and click Close 6. Now click Continue and the robot will be paired 7. To know the mac address of a paired robot, go to System Settings, Bluetooth and select the robot; once selected you'll see in the right side the related mac address The ROS e-puck driver based on roscpp has the possibility to automatically search for the robots, so you don't need to specify the mac address but you need to pass only the robot id; pay attention that you still need to pair the robot to the computer as explained in the previous steps. Anyway is recommended to specify the mac address to speed up and facilitate the connection (especially with multiple robots). First thing to do before launching the script file is running the roscore, open another terminal tab and issue the command roscore. ### Single robot Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Single_robot Open a terminal and issue the following command: - Python: `roslaunch epuck_driver epuck_controller.launch epuck_address:='10:00:E8:C5:61:C9'`. - cpp: `roslaunch epuck_driver_cpp epuck_controller.launch epuck_id:='3000' epuck_address:='10:00:E8:C5:61:C9'`. 10:00:E8:C5:61:C9 is the e-puck Bluetooth mac address and 3000 is the e-puck id (number on the case). If all is going well you'll see the robot make a blink meaning it is connected and ready to exchange data (the blink is done only when using the Python ROS driver) and [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the informations gathered from the topics published by the epuck driver node. The following graph shows all the topics published by the epuck driver node (Pyhton): ![rosgraph-single-robot.png](https://www.gctronic.com/doc/images/5/5d/rosgraph-single-robot.png) ![epuck-ros-single-robot.png](https://www.gctronic.com/doc/images/0/0c/epuck-ros-single-robot.png) **Cpp ROS driver** The cpp ROS driver launch script is configured also to run the [gmapping (SLAM)](https://wiki.ros.org/gmapping) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Multiple robots Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Multiple_robots The script is designed to work with 4 e-puck robots and you need to modify the script in order to use the correct Bluetooth mac addresses: - open the file ~/catkin_ws/src/epuck_driver/launch/multi_epuck.launch (Python) or ~/catkin_ws/src/epuck_driver_cpp/launch/multi_epuck.launch (cpp) - on top of the file you'll see a list of 4 e-puck addresses, change their values accordingly Now you can start the node by issueing the following command in a terminal: - Python: `roslaunch epuck_driver multi_epuck.launch` - cpp: `roslaunch epuck_driver_cpp multi_epuck.launch` If all is going well you'll see the robots make a blink meaning they are connected and ready to exchange data (the blink is done only when using the Python ROS driver) and [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the proximity and odometry of all the 4 robots; it is assumed that the robots are placed in a square (each robot in each corner) of 20 cm. In order to move the robots you can either use a TV remote or you can directly use ROS by publishing velocities commands by issueing the following command: `rostopic pub -1 /epuck_robot_0/mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'` - this command will move the *first* e-puck with a linear velocity of 1 rotation per second (robot moves straight) - only the *x* component of the linear velocity and the *z* component of the angular velocity are used - for more information on the *Twist* message refer to ![roscpp_4robots.png](https://www.gctronic.com/doc/images/e/ed/roscpp_4robots.png) *Click to enlarge* ### Visualize the camera image Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Visualize_the_camera_image In order to visualize the image through ROS you need to use the launch script for a single robot with an additional parameter cam_en as follows: - Python: `roslaunch epuck_driver epuck_controller.launch epuck_address:='10:00:E8:C5:61:C9' cam_en:='true'` - cpp: `roslaunch epuck_driver_cpp epuck_controller.launch epuck_id:='3000' epuck_address:='10:00:E8:C5:61:C9' cam_en:='true'` Then with the Python ROS driver you need to open another terminal and issue the command `rosrun image_view image_view image:=/camera` that will open a window wiht the e-puck camera image. With the cpp ROS driver the image is visualized directly in the rviz window (on the right), as shown in the following image: ![roscpp_1robot.png](https://www.gctronic.com/doc/images/f/f3/roscpp_1robot.png) *Click to enlarge* ## Virtual machine Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Virtual_machine To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and e-puck. You can download the image as *open virtualization format* from the following link ROS-Hydro-12.04.ova (contact us to have access to this VM), based on the VM from ; you can then use [VirtualBox](https://www.virtualbox.org/) (together with the VirtualBox Extension Pack) to import the file and automatically create the virtual machine. Some details about the system: - user: gctronic, pw: gctronic - Ubuntu 12.04.4 LTS (32 bits) - ROS Hydro installed - PyCharm: Python IDE used to extend the rospy e-puck driver; when you open the IDE it will open a project pointing to the ROS e-puck driver so you can immediately start diving into the code - [Webots](https://www.cyberbotics.com/) 8.0.5 is installed (last version available for 32 bits linux) - [git-cola](https://git-cola.github.io/) (git interface) is installed - the catkin workspace is placed in the desktop If you encounter problems related to network adapters not recognized when booting the imported virtual machine then you need to follow these steps: 1. close VirtualBox 2. go to the directory C:\Users\YOUR_USER\VirtualBox VMs\ROS Hydro - 12.04 3. open the file ROS Hydro - 12.04.vbox with a text editor, remove all the content of the . 2. Create a catkin workspace as explained in section [Initial configuration](https://www.gctronic.com/doc/index.php/E-Puck#Initial_configuration) if you didn't already done 3. Copy the directory nodes from WEBOTS_MODULES_PATH/projects/languages/ros/ (e.g. /home/viki/.local/share/Cyberbotics/Webots/8.2/projects/languages/ros/) to the catkin workspace source folder (e.g. ~/catkin_ws/src) 4. Copy the directory srv from WEBOTS_MODULES_PATH/projects/default/controllers/ros/include (e.g. /home/viki/.local/share/Cyberbotics/Webots/8.2/projects/default/controllers/ros/include) to the nodes package just copied (e.g. ~/catkin_ws/src/nodes) 5. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make` 6. Open another terminal and start ROS by typing `roscore` 7. Start Webots and open the ROS e-puck example: File => Open Sample World => languages => ros => e-puck_line.wbt and play it 8. Now from the terminal positioned to the catkin workspace issue the command `rosrun nodes e-puck_line 60`, where 60 is the duration in seconds; you should see the e-puck follow the line in the simulator For more information have a look at the Readme you can find in WEBOTS_MODULES_PATH/projects/languages/ros/nodes (e.g. /home/viki/.local/share/Cyberbotics/Webots/8.2/projects/languages/ros/nodes) or refer to the Webots user guide chapter [Using ROS](https://cyberbotics.com/doc/guide/using-ros). **The EDU license is valid to play with Webots and ROS (PRO license not required).** ### Webots ROS SLAM with e-puck Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Webots_ROS_SLAM_with_e-puck This example shows how to use the [gmapping (SLAM)](https://wiki.ros.org/gmapping) package of ROS to let the e-puck robot construct a map of the simulated environment; the map is visualized in real-time directly in the rviz window. Here are the steps to run the demo: 1. download the code from the following link [webots-ros-slam.zip](https://projects.gctronic.com/E-Puck/ROS/webots-ros-slam.zip) and extract the zip 2. copy the source file nodes/src/e-puck_line_slam.cpp to the catkin workspace folder of the Webots nodes (e.g. ~/catkin_ws/src/nodes/src) 3. copy the folders nodes/config, nodes/launch and nodes/urdf to the catkin workspace folder of the Webots nodes (e.g. ~/catkin_ws/src/nodes/) 4. copy the files nodes/CMakeLists.txt and package.xml to the catkin workspace folder of the Webots nodes (e.g. ~/catkin_ws/src/nodes/) by substituting the current ones 5. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make` 6. Open another terminal and start ROS by typing `roscore` 7. Start Webots and open worlds/e-puck_line_slam.wbt: File => Open World => look for the directory containing e-puck_line_slam.wbt and play it 8. Now from the terminal positioned to the catkin workspace issue the command `roslaunch nodes epuck_controller.launch` Here is a video: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Webots ROS and OpenCV with e-puck Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Webots_ROS_and_OpenCV_with_e-puck This example shows how to integrate [OpenCV](https://opencv.org/) with ROS to let the e-puck robot detect and follow a ball in the simulated environment. Here are the steps to run the demo: 1. download the code from the following link [webots-ros-opencv.zip](https://projects.gctronic.com/E-Puck/ROS/webots-ros-opencv.zip) and extract the zip 2. copy the source file nodes/src/e-puck_opencv.cpp to the catkin workspace folder of the Webots nodes (e.g. ~/catkin_ws/src/nodes/src) 3. copy the files nodes/CMakeLists.txt and package.xml to the catkin workspace folder of the Webots nodes (e.g. ~/catkin_ws/src/nodes/) by substituting the current ones 4. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make` 5. Open another terminal and start ROS by typing `roscore` 6. Start Webots and open worlds/e-puck_opencv.wbt: File => Open World => look for the directory containing e-puck_opencv.wbt and play it 7. Now from the terminal positioned to the catkin workspace issue the command `rosrun nodes e-puck_opencv 20 140 0 0 150 255 255`, where : : - 20 is the duration in seconds - 140, 0, 0 are the min H, S and V respectively of the blob to detect - 150, 255, 255 are the max H, S and V respectively of the blob to detect ## E-puck gumstix extension Link: https://www.gctronic.com/doc/index.php?title=E-Puck#E-puck_gumstix_extension For more information on how to use ROS with the e-puck gumstix extension refer to section . # Test and Results Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Test_and_Results ## Bluetooth Communication Testing - PC to robot Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Bluetooth_Communication_Testing_-_PC_to_robot Some tests were performed in order to analyze the bluetooth speed between a computer and the e-puck; the following three experiments were executed sending the same total amount of data but differently subdivided: - 19200 packets of 6 bytes each sent from computer to e-puck: about 65 seconds ([BTspeed.zip](https://www.gctronic.com/doc/images/BTspeed.zip)) - 2560 packets of 45 bytes each sent from computer to e-puck: about 20 seconds ([BTspeedPackets.zip](https://www.gctronic.com/doc/images/BTspeedPackets.zip)) - 1 packet of 115200 bytes sent from computer to e-puck: about 10 seconds ([BTspeedFile.zip](https://www.gctronic.com/doc/images/BTspeedFile.zip)) Explanation: dividing a packet in small chunk of data (such as a single command) introduces pauses generated by the Bluetooth device of the PC. The mean measured delay time between a packet and the other is about 3 ms, but could be as high as 20 ms. Sending the packet in one single block like in the third experiment, has no pauses and thus needs exactly the theoretical time of 10 seconds for the channel at 115'200 Baud. ## Bluetooth Communication Testing - robot to robot Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Bluetooth_Communication_Testing_-_robot_to_robot Some tests were performed also to analyze the maximum speed reachable between two robots using direct communication, that is one acting as the master and the other as the slave. The Bluetooth 2.0 specification asserts 1 Mbit/s air data rate, but in practice with the Bluetooth protocol overhead the usable bandwidth is lower; moreover in our case there are others two facts to take in consideration: 1. the communication between the robot and the BT chip is configured to be at 115200 bps 2. the buffer handling system of the BT chip is capable of receive at maximum 200 packets per second (refers to [UART buffer AN.pdf](https://projects.gctronic.com/E-Puck/docs/BT/SB_UART_AN.pdf)) From the tests the resulting throughput is **18 Kb/s**, sending a total of 41000 bytes with 41 bytes for each packet and waiting the response from the chip before sending the next packet; moving the slave device several meters away from the master influences the communication speed, that slows down. The sources (MPLAB project) of the firmware used for this test can be downloaded from the following link [DemoGCtronic-BT.zip](https://projects.gctronic.com/E-Puck/DemoGCtronic-BT.zip) (master=selector position 9, slave=selector position 4). There is an additional example that shows how to establish a direct Bluetooth link between two e-pucks. This firmware is intended to be programmed on the master robot (selector 0); the master will send commands using the "asercom protocol" to a slave robot, that is the first robot found during the search, in order to turn on its leds in sequence. The slave robot is intended to be programmed with the [standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) (selector position 3). You can download the MPLAB X project from here [DemoGCtronic-BT-asercom.zip](https://projects.gctronic.com/E-Puck/DemoGCtronic-BT-asercom.zip); in order to build refer to section [Project_building](https://www.gctronic.com/doc/index.php/E-Puck#Project_building). The Bluetooth library was extended to build this demo, you can download it from here [bluetooth.zip](https://projects.gctronic.com/E-Puck/bluetooth.zip); this library must replace the one included in the e-puck library in order to build the project. There are various modes available on this demo, depending on the selector position: - 0: search for an e-puck1 or e-puck2 and connect to the first one found, then send some commands to it through the [advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol) - 1: receiver mode (template) - 2: connect directly to an e-puck1 (no search is accomplished) and then send some commands to it - 3: connect directly to an e-puck2 (no search is accomplished) and then send some commands to it ## e-puck balancing Link: https://www.gctronic.com/doc/index.php?title=E-Puck#e-puck_balancing The users can transform the e-puck in a self balancing robot by applying some mechanical modifications as shown in the following figure. Here are the 3d models of the [wheel tyre extension](https://projects.gctronic.com/E-Puck/balance/WheelExtensionD52.STL) and [spacer](https://projects.gctronic.com/E-Puck/balance/Spacer28mm.STL). For more information on the assembly please contact us. ![epuck-balance.jpg](https://www.gctronic.com/doc/images/5/5c/epuck-balance.jpg) *Click to enlarge* Here is a video of the e-puck trying to self balance; this is only a starting point to demonstrate the feasiblity, so you can take the [code (MPLAB X project)](https://projects.gctronic.com/E-Puck/balance/DemoGCtronic-balance.zip) and improve it. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## e-puck and Arduino Link: https://www.gctronic.com/doc/index.php?title=E-Puck#e-puck_and_Arduino The [Arduino](https://www.arduino.cc/) boards are used widely in the hobby community and you can extend the functionalities of a board by using the so called *shields*; there are tons of shields like WiFi, SD reader/writer, battery, XBee, GSM, speech recognition, rfid, ... there is a shield for everything (almost). For these reasons we decided to connect an Arduino to the e-puck robot. I2C is used to communicate between the e-puck (master) and the Arduino (slave), this is the easiest way to get both a communication channel and the power from the e-puck thanks to an already available connector on the robot. The connector is placed on the bottom side of the e-puck main pcb as shown in the following figures: ![epuck-arduino-connector2.jpg](https://www.gctronic.com/doc/images/a/a6/epuck-arduino-connector2.jpg) *Click to enlarge* ![epuck-arduino-connector3.jpg](https://www.gctronic.com/doc/images/d/d3/epuck-arduino-connector3.jpg) *Click to enlarge* The following figure shows the schema to connect the e-puck to the Arduino Uno board; you can follow the same schema to connect to other Arduino boards paying attention to the related pinout. Power and voltage considerations: in this configuration, the e-puck battery (LiPo 3.7Volt) powers directly also the Arduino board to its 5 Volt line. This is ok for the tested demos but it might be limiting in some rare cases. Let us know your goals and experiments to get support. The I2C lines are simply protected with 2 series resistors in order to limit any excessive current into the PIC. ![epuck-arduino-schema.png](https://www.gctronic.com/doc/images/2/20/epuck-arduino-schema.png) *Click to enlarge* Here is a video of a demo in which you can control the e-puck with your voice; the e-puck is connected to an [Arduino Uno](https://www.arduino.cc/en/Main/ArduinoBoardUno) that is extended with an [Easy VR shield](https://www.veear.eu/) for speech recognition. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) The source code of the demo is available in the following links: [MPLAB project](https://projects.gctronic.com/E-Puck/arduino/DemoGCtronic-arduino.zip) for the e-puck, [Arduino IDE (1.6.6) project](https://projects.gctronic.com/E-Puck/arduino/epuck_arduino.zip) for the Arduino Uno board (you'll need the Easy VR Arduino library to build the project). A test project that works without any shield is available in the following link [Arduino IDE (1.6.6) test project](https://projects.gctronic.com/E-Puck/arduino/epuck_arduino_test.zip), this demo rotates continuously the robot right and left. It works with the same robot firmware as the previous demo. We designed a support in order to mechanically attaching the Arduino board on top of the e-puck robot as shown in the following figure. ![epuck-arduino-support.jpg](https://www.gctronic.com/doc/images/8/8d/epuck-arduino-support.jpg) *Click to enlarge* Here is the [support 3D model](https://projects.gctronic.com/E-Puck/arduino/SuppArduinoONE_V2.STL) that you can print with your 3d printer. Alternatively you can purchase an "e-puck arduino set" from the [shop](https://www.gctronic.com/shop.php#e-puck%20accessories). # Known problems Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Known_problems ## Re-flashing the bootloader on e-puck Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Re-flashing_the_bootloader_on_e-puck In some cases it was reported that the internal bootloader on e-puck was corrupted due to a malfunction of the last code upload. In those cases the bootloader ([DemoGCtronic-complete-4bba145+bootloader.hex](https://projects.gctronic.com/E-Puck/DemoGCtronic-complete/DemoGCtronic-complete-4bba145+bootloader.hex)) has to be re-flashed on the robot via cable (see figure) with ICD2 or ICD3 and MPLAB IDE or compatible HW and SW. See the procedure ([Instruction re-program bootloader.pdf](https://projects.gctronic.com/E-Puck/KnownProblems/Instruction-re-program-bootloader-e-puck.pdf)) and in case of need contact info[at]gctronic.com. ![E-puck_prog_cable1.jpg](https://www.gctronic.com/doc/images/a/a4/E-puck_prog_cable1.jpg) ![epuckICDProgConn.png](https://www.gctronic.com/doc/images/c/cf/epuckICDProgConn.png) ## Uncorrect/unknown bluetooth PIN code Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Uncorrect/unknown_bluetooth_PIN_code In a couple of rare cases it was reported that the PIN code of the Bluetooth chip was not anymore the usual one (same as e-puck number). It seems that the issue is linked to trials of robot to robot direct communication. One robot could have picked up the PIN of the other one, so you could try that PIN to get access to the robot. Another possibility is to try the default pin number 0000. In order to restore the name and pin number of the robot you can either make a program specifically for this purpose (1) or use the standard firmware but you would need the serial cable (2): 1. the e-puck library contains the functions to interact with the BT chip and change all its configurations including pin number and friendly name; for a code example refer to the example [DemoBTConfiguration.zip](https://projects.gctronic.com/E-Puck/DemoBTConfiguration-rev119.zip), that simply rewrite the pin and friendly name (change only the pin number in the code, the friendly name will be changed accordingly). Another source of insipiration is the [Standard_firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware), the part of the code related to selector 11. In case the chip isn't responding be sure it is in *command mode* (use the function `e_bt_exit_tranparent_mode`). 2. program the robot with the [Standard_firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) and put the selector in position 11. Connect the serial cable to the robot as shown in section [Serial_communication](https://www.gctronic.com/doc/index.php/E-Puck#Serial_communication) and to the computer (you would need an USB to serial adapter); open the port using this configuration 115200n8. Once the communication channel is opened type the command `H+enter` to get the help. You can get the serial cable from the [shop](https://www.gctronic.com/shop.php#e-puck%20accessories). ## Battery isolation (for battery up to 2012) Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Battery_isolation_(for_battery_up_to_2012) You should be careful when inserting and removing the battery of the e-puck in the robot or in the charger. Otherwise in the long run your battery will eventually lose its front isolator (plastic of cardboard), causing a possible short circuit. If you are already in this situation, you could try placing some isolation tape on the battery, as illustrated in the following figure. The correct procedure to insert and remove the batteries can be found in the following document [Change-batteries.pdf](https://projects.gctronic.com/E-Puck/docs/CambiareBatte-puck.pdf). Basically you need to fully push in the battery compressing the springs before tilting the battery in the final position. ![Battery.jpg](https://www.gctronic.com/doc/images/3/30/Battery.jpg) ## Bluetooth and MacBook Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Bluetooth_and_MacBook Some users experienced problems in connecting to the robot via Bluetooth using MacBook; using an usb BT dongle solved the problem most of the time. Some users instead experienced distance problems with the internal BT chip of the MacBook, that is the robot should be kept within 1.5 meters otherwise the connection is lost/slows down. ## Memory protection Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Memory_protection The dsPIC processor has the possibility to protect the program memory at various levels through the configuration bits; in principle these protections can be eliminated erasing completely the memory, anyway in some cases it was reported that this procedure fails, leading to a situation in which the "memory protection" still blocks and the robot cannot be programmed anymore. Thus it is advisable to avoid playing with code protection unless strictly necessary. In principle the procedure to reset the configuration bits eliminating the protection is: 1. Open the MPLAB project and connect the programming cable to the robot 2. Select "Programmer => Select Programmer => MPLAB ICD3" 3. Select "Programmer => Settings": in the "Program Memory" tab select "Manually select memories and ranges" and check all options, click also on full program memory range 4. In the "Power" tab set the voltage to 5.5 V and check the option "Power target circuit from MPLAB ICD 3" 5. Select "Programmer => Erase Flash Device"; erase should give no errors 6. Power cycle the robot (unplug and plug again the programming cable); now the configuration bits are reset and program memory is cleared completely; it's possible to upload a new program selecting "Programmer => Program" **Note that this procedure works only with the ICD3 that is capable of supplying 5V to the processor**. ## Proximity noise Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Proximity_noise It was noticed that the proximity 0 and proximity 7 are subject to noise, in particular the value returned from these two sensors can vary up to 30 (the variation of the others is in the range of 2-3). This noise is coming from the camera clock, thus as a workaround the camera can be turned off if this noise causes problems. ## ICD2 programmer Link: https://www.gctronic.com/doc/index.php?title=E-Puck#ICD2_programmer The Microchip ICD2 programmer P/N 10-00319 isn't supported on 64-bit OS. ## Upload failed Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Upload_failed If the robot was programmed with a firmware in which the Bluetooth is used to write continuously data to the computer, then you can experience problems in uploading a new firmware to the robot. To solve the problem you should try resetting the robot continuously during the connection to the robot when you are uploading a new firmware, basically you should reset the robot (press and release the button continuously) until the connection led turn on, then stop resetting; with a bit of luck you should be able to upload it. ## Speed precision at very low speed Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Speed_precision_at_very_low_speed The e-puck motors are step motors. To save energy, the motor phases/steps at low speed are not energized all the time but just partially. This might affect the speed precision at speed below 200. If one has specific needs at that low speed and want the single steps to be more energetic, then the `TRESHV` and `MAXV` constants in the file `\motor_led\advance_one_timer\e_motors.c` within the e-puck library need to be adapted (decrease their value). Alternatively the power save feature can be completely disabled by commenting the `POWERSAVE` constant. ## Mail archive Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Mail_archive You can have a look at a mail archive (February 2007 - December 2016) regarding the e-puck robot from the following link . In this archive you can find problems encountered by users and related solutions. ## Bluetooth slowdown in Ubuntu Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Bluetooth_slowdown_in_Ubuntu If you experience a slowdown using the Bluetooth in Ubuntu try removing the package `modemmanager` with the following command: `sudo apt-get remove modemmanager` # Links Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Links # Videos Link: https://www.gctronic.com/doc/index.php?title=E-Puck#Videos [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ======================================================================== TOPIC: pi-puck Pi-puck extension, compatible with both e-puck and e-puck2. Check which robot a statement refers to. ======================================================================== # Pi-puck Source: https://www.gctronic.com/doc/index.php?title=Pi-puck Last edited: 2026-02-19T13:18:53Z # Hardware Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Hardware ## Overview Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Overview ![pipuck-overview.jpg](https://www.gctronic.com/doc/images/f/f4/pipuck-overview.jpg) Features: - Raspberry Pi Zero W or Zero 2 W 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 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#I2C_bus 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: ![i2c-buses.png](https://www.gctronic.com/doc/images/8/82/i2c-buses.png) 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. # Getting started Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Getting_started This introductory section explains the minimal procedures needed to work with the Raspberry Pi Zero W / Zero 2 W mounted on the Pi-puck extension board and gives a general overview of the available basic demos and scripts shipped with the system flashed on the micro SD. More advanced demos are described in the following separate sections (e.g. ROS), but the steps documented here are fundamental, so be sure to fully understand them. The extension is mostly an interface between the e-puck robot and the Raspberry Pi, so you can exploit the computational power of a Linux machine to extend the robot capabilities. In most cases, the Pi-puck extension will be attached to the robot, but it's interesting to note that it can be used also alone when the interaction with the robot isn't required. The following sections assume the full configuration (robot + extension), unless otherwise stated. ## Requirements Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements The robot must be programmed with a special firmware in order to communicate via I2C bus with the Raspberry Pi mounted on the Pi-puck extension. The same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the Raspberry Pi. Since the Raspberry Pi acts as I2C master, these devices will not be anymore reachable directly from the robot main microcontroller that will act instead as I2C slave. ### e-puck version 1 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#e-puck_version_1 The e-puck version 1 robot must be programmed with the following firmware [pi-puck-e-puck1.hex](https://raw.githubusercontent.com/yorkrobotlab/pi-puck/master/e-puck1/pi-puck-e-puck1.hex). ### e-puck version 2 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#e-puck_version_2 The e-puck version 2 robot must be programmed with the following firmware [e-puck2_main-processor_extension.elf (07.06.19)](https://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_extension_b346841_07.06.19.elf) and the selector must be placed in position 10(A). The source code is available in the `gumstix` branch of the repo `https://github.com/e-puck2/e-puck2_main-processor`. ## Turn on/off the extension Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Turn_on/off_the_extension To turn on the extension you need to press the `auxON` button as shown in the follwoing figure; this will turn on also the robot (if not already turned on). Similarly, if you turn on the robot then also the extension will turn on automatically. ![pipuck_btn_on_off.jpg](https://www.gctronic.com/doc/images/1/11/pipuck_btn_on_off.jpg) To turn off the Pi-puck you need to press and hold the `auxON` button for 2 seconds; this will initiate the power down procedure. Beware that by turning off the robot, the extension will not be turned off automatically if it is powered from another source like the micro usb cable or a secondary battery. You need to use its power off button to switch it off. Instead if there is no other power source, then by turning off the robot also the extension will be turned off (not cleanly). ## Console mode Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Console_mode The Pi-puck extension board comes with a pre-configured system ready to run without any additional configuration. In order to access the system from a PC in console mode, the following steps must be performed: 1. connect a micro USB cable from the PC to the extension module. If needed, the drivers are available in the following link [USB to UART bridge drivers](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) ![pipuck_usb.png](https://www.gctronic.com/doc/images/5/52/pipuck_usb.png) 2. execute a terminal program and configure the connection with 115200-8N1 (baudrate, 8 bits, no flow control). The serial device is the one created when the extension is connected to the computer 3. switch on the robot (the extension will turn on automatically); now the terminal should display the Raspberry Pi booting information. If the robot isn't present, then you can directly power on the extension board with the related button 4. login with `user = pi`, `password = raspberry` ## Battery charge Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Battery_charge You can either charge the robot battery or the additional battery connected to the Pi-puck extension or both the batteries by simply plugging the micro USB cable. The following figure shows the connector for the additional battery. ![pipuck_battery.jpg](https://www.gctronic.com/doc/images/3/3e/pipuck_battery.jpg) 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: ![pipuck-charger-robot.jpg](https://www.gctronic.com/doc/images/2/24/pipuck-charger-robot.jpg) ![pipuck_contacts.jpg](https://www.gctronic.com/doc/images/7/7f/pipuck_contacts.jpg) ## Reset button Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#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: ![pipuck_reset.png](https://www.gctronic.com/doc/images/1/1f/pipuck_reset.png) # How to communicate with the robot and its sensors Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#How_to_communicate_with_the_robot_and_its_sensors ## Communicate with the e-puck version 1 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_e-puck_version_1 Refer to the repo . ## Communicate with the e-puck version 2 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_e-puck_version_2 An example showing how to exchange data between the robot and the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/e-puck2/`. You can build the program with the command `gcc e-puck2_test.c -o e-puck2_test`. Now you can run the program by issueing `./e-puck2_test`; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz. The same example is also available in Python, you can run it by issueing `python3 e-puck2_test.py`. ### Packet format Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Packet_format Extension to robot packet format, 20 bytes payload (the number in the parenthesis represents the bytes for each field): | Left speed (2) | Right speed (2) | Speaker (1) | LED1, LED3, LED5, LED7 (1) | LED2 RGB (3) | LED4 RGB (3) | LED6 RGB (3) | LED8 RGB (3) | Settings (1) | Checksum (1) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | - Left, right speed: [-2000 ... 2000] - Speaker: 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): | 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 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_IMU ### e-puck version 1 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#e-puck_version_1_2 An example written in C showing how to read data from the IMU (LSM330) mounted on e-puck version 1.3 is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/e-puck1/`. You can build the program with the command `gcc e-puck1_imu.c -o e-puck1_imu`. Now you can run the program by issueing `./e-puck1_imu` and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal. ### e-puck version 2 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#e-puck_version_2_2 An example showing how to read data from the IMU (MPU-9250) is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/e-puck2/`. You can build the program with the command `gcc e-puck2_imu.c -o e-puck2_imu`. Now you can run the program by issueing `./e-puck2_imu` and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal. The same example is also available in Python, you can run it by issueing `python3 e-puck2_imu.py`. ## Communicate with the ToF sensor Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_ToF_sensor The Time of Flight sensor is available only on the e-puck version 2 robot. First of all you need to verify that the VL53L0X Python package is installed with the following command: `python3 -c "import VL53L0X"`. If the command returns nothing you're ready to go, otherwise if you receive an `ImportError` then you need to install the package with the command: `pip3 install git+https://github.com/gctronic/VL53L0X_rasp_python`. A Python example showing how to read data from the ToF sensor is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/e-puck2/`. You can run the example by issueing `python3 VL53L0X_example.py` (this is the example that you can find in the repository ). ## Capture an image Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Capture_an_image The robot camera is connected to the Pi-puck extension as a USB camera, so you can access it very easily. An example showing how to capture an image from the robot's camera using OpenCV is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/snapshot/`. You can build the program with the command `g++ $(pkg-config --libs --cflags opencv) -ljpeg -o snapshot snapshot.cpp`. Now you can run the program by issueing `./snapshot`; this will save a VGA image (JPEG) named `image01.jpg` to disk. The program can accept the following parameters: `-d DEVICE_ID` to specify the input video device from which to capture an image, by default is `0` (`/dev/video0`). This is useful when working also with the [Omnivision V3](http://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3) extension that crates another video device; in this case you need to specify `-d 1` to capture from the robot camera. `-n NUM` to specify how many images to capture (1-99), by default is 1 `-v` to enable verbose mode (print some debug information) Beware that in this demo the acquisition rate is fixed to 5 Hz, but the camera supports up to **15 FPS**. The same example is also available in Python, you can run it by issueing `python snapshot.py`. ## Communicate with the ground sensors extension Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_ground_sensors_extension Both e-puck version 1 and e-puck version 2 support the [ground sensors extension](https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors). This extension is attached to the I2C bus and can be read directly from the Pi-puck. An example written in C showing how to read data from the ground sensors extension is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/ground-sensor/`. You can build the program with the command `gcc groundsensor.c -o groundsensor`. Now you can run the program by issueing `./groundsensor`; this demo will print the sensors data on the terminal. The same example is also available in Python, you can run it by issueing `python3 groundsensor.py`. ## Communicate with the range and bearing extension Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_range_and_bearing_extension Both e-puck version 1 and e-puck version 2 support the [range and bearing extension](https://www.gctronic.com/doc/index.php?title=Others_Extensions#Range_and_bearing). This extension is attached to the I2C bus and can be read directly from the Pi-puck. An example written in C showing how to start playing with the range and bearing extension is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/randb/`. You need two boards: one is the transmitter (run `randb_tx`) and the other is the receiver (run `randb_rx`). The receiver will print the data received from the transmitter. You can build the programs with the command `gcc randb_tx.c -o randb_tx` and `gcc randb_rx.c -o randb_rx`. The same example is also available in Python, you can run it by issueing `python3 randb_tx.py` and `python3 randb_rx.py`. For best performances you need also to take in consideration the interference given by the time of flight and proximity sensors (see ). ## Wireless remote control Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Wireless_remote_control 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: 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-puck version 2 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-puck version 2 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: ![wireless-remote-control-options.png](https://www.gctronic.com/doc/images/3/37/wireless-remote-control-options.png) # How to work with the Pi-puck Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#How_to_work_with_the_Pi-puck ## Demos and scripts update Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Demos_and_scripts_update First of all you should update to the last version of the demos and scripts released with the system that you can use to start playing with the Pi-puck extension and the robot. To update the repository follow these steps: 1. go to the directory `/home/pi/Pi-puck` 2. issue the command `git pull` Then to update some configurations of the system: 1. go to the directory `/home/pi/Pi-puck/system` 2. issue the command `./update.sh`; the system will reboot. You can find the Pi-puck repository here . ## Audio recording Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Audio_recording Use the `arecord` utility to record audio from the onboard microphone. The following example shows how to record an audio of 2 seconds (`-d` parameter) and save it to a wav file (`test.wav`): `arecord -Dmic_mono -c1 -r16000 -fS32_LE -twav -d2 test.wav` You can also specify a rate of 48 KHz with `-r48000` ## Audio play Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Audio_play Use `aplay` to play `wav` files and `mplayer` to play `mp3` files. ## Battery reading Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Battery_reading A Python example showing how to measure both the battery of the robot and the battery of the Pi-puck extension is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/battery/`. You can start reading the batteries values by issueing `python read-battery.py`.; this demo will print the batteries values (given in Volts) on the terminal. An additional Python example is provided in the same directory showing how to detect when the robot is in charge: this is a basic demo in which the robot goes forward and stop only when it is in charge, it can be used as a starting point for more advanced examples. To run this demo issue the commands `sudo pigpiod` and then `python3 goto-charge.py`. ## WiFi configuration Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#WiFi_configuration Specify your network configuration in the file `/etc/wpa_supplicant/wpa_supplicant-wlan0.conf`. Example: ``` ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 country=CH network={ ssid="MySSID" psk="9h74as3xWfjd" } ``` You can have more than one `network` parameter to support more networks. For more information about *wpa_supplicant* refer to . Once the configuration is done, you can also connect to the Pi-puck with `SSH`. If you are working in Windows you can use [PuTTY](https://www.putty.org/). ### How to know your IP address Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#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 `ip a`; 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 `nmap`. For example you can search all connected devices in your network with the following command: `nmap 192.168.1.*`. Beware that you need to specify the subnet based on your network configuration. From the command's result you need to look for the hostname `raspberrypi`. If you are working in Windows you can use the [Zenmap](https://nmap.org/zenmap/) application. ## File transfer Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#File_transfer ### USB cable Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#USB_cable You can transfer files via USB cable between the computer and the Pi-puck extension by using on of the `zmodem` protocol. The `lrzsz` package is pre-installed in the system, thus you can use the `sx` and `rx` utilities to respectevely send files to the computer and receive files from the computer. Example of sending a file to the computer using the `Minicom` terminal program: 1. in the Pi-puck console type `sx --zmodem fliename.ext`. The transfer should start automatically and you'll find the file in the home directory. Example of receiving a file from the computer using the `Minicom` terminal program: 1. in the Pi-puck console type `rx -Z` 2. to start the transfer type the sequence `CTRL+A+S`, then chose `zmodem` and select the file you want to send with the `spacebar`. Finally press `enter` to start the transfer. ### WiFi Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#WiFi The Pi-puck extension supports `SSH` connections. To exchange files between the Pi-puck and the computer, the `scp` tool (secure copy) can be used. An example of transferring a file from the Pi-puck to the computer is the following: `scp pi@192.168.1.20:/home/pi/example.txt example.txt` If you are working in Windows you can use [PuTTY](https://www.putty.org/). ## Image streaming Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Image_streaming ## Bluetooth LE Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Bluetooth_LE An example of a *BLE uart service* is available in the Pi-puck repository; you can find it in the directory `/home/pi/Pi-puck/ble/`. To start the service you need to type: `python uart_peripheral.py`. Then you can use the *e-puck2-android-ble app* you can find in chapter [Connecting to the BLE](https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development#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 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Operating_system ## Raspberry Pi OS Stretch Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Raspberry_Pi_OS_Stretch The system is based on Raspberry Pi OS Stretch and can be downloaded from the following link [pi-puck-os_25.05.22.zip](https://projects.gctronic.com/epuck2/PiPuck/pi-puck-os_25.05.22.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: 1. `sudo raspi-config` 2. Select `Advanced Options` and then `Expand Filesystem` 3. reboot Beware that this system is no more maintained, please refer to [Raspberry Pi OS Buster](https://www.gctronic.com/doc/index.php?title=Pi-puck#Raspberry_Pi_OS_Buster). ROS users need to work with this system because the updated system (Buster) supports only ROS2. ## Raspberry Pi OS Buster Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Raspberry_Pi_OS_Buster The system is based on Raspberry Pi OS Buster and can be downloaded from the following link [buster_ros2_21.06.24.tar.gz](https://projects.gctronic.com/epuck2/PiPuck/buster_ros2_21.06.24.tar.gz). This system supports only ROS2, this is the main difference against the older system (Stretch). All the examples are fully supported. ## e-puck version 2 camera configuration Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#e-puck_version_2_camera_configuration The e-puck version 2 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 (`/home/pi/Pi-puck/camera-configuration.py`), 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 `python3 /home/pi/Pi-puck/camera-configuration.py`. In order to automatically run the script at boot, the `/etc/rc.local` was modified by adding the call to the script just before the end of the file. ## Power button handling Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Power_button_handling The power button press is handled by a background service (`systemd`) started automatically at boot. The service description file is located in `/etc/systemd/system/power_handling.service` and it calls the `/home/pi/power-handling/` program. Beware to not remove neither of these files. The source code of the power button handling program is available in the Pi-puck repository and is located in `/home/pi/Pi-puck/power-handling/power-handling.c`. ## Desktop mode Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Desktop_mode The system starts in console mode, to switch to desktop (LXDE) mode issue the command `startx`. ### Camera viewer Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Camera_viewer A camera viewer called `luvcview` is installed in the system. You can open a terminal and issue simply the command `luvcview` to see the image coming from the robot camera. ## VNC Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#VNC [VNC](https://www.realvnc.com/en/) 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. 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 [How to know your IP address](https://www.gctronic.com/doc/index.php?title=Pi-puck#How_to_know_your_IP_address)). Notice that the *VNC server* is started also in console mode. ## I2C communication Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#I2C_communication The communication between the Pi-puck extension and the robot is based on I2C. The system is configured to exploit the I2C hardware peripheral in order to save CPU usage, but if you need to use the software I2C you can enable it by modifying the `/boot/config.txt` file and removing the `#` symbol (comment) in front of the line with the text `dtparam=soft_i2c` (it is placed towards the end of the file). ## Audio output configuration Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Audio_output_configuration You can enable or disable audio output by modifying the `config.txt` file in the `boot` partition. To enable audio output insert the line: `gpio=22=op,dh` To disable audio output insert the line: `gpio=22=op,dl` If you don't need to play audio files it is suggested to disable audio output in order to save power. # ROS Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#ROS ROS Kinetic is integrated in the Pi-puck system. A ROS node developed to run in the Pi-puck is available for both `CPP` and `Python`, the communication system is based on the third architecture shown in chapter [Wireless remote control](https://www.gctronic.com/doc/index.php?title=Pi-puck#Wireless_remote_control); a more detailed schema is shown below: ![epuck2-ros-schema_pipuck.png](https://www.gctronic.com/doc/images/f/fe/epuck2-ros-schema_pipuck.png) ## Initial configuration Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Initial_configuration The ROS workspace is located in `~/rosbots_catkin_ws/` The e-puck version 2 ROS driver is located in `~/rosbots_catkin_ws/src/epuck_driver_cpp/` Remember to follow the steps in the section [Requirements](http://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements) and section [Demos and scripts update](https://www.gctronic.com/doc/index.php?title=Pi-puck#Demos_and_scripts_update), only once. The PC (if used) and the Pi-puck extension are supposed to be configured in the same network. ## Running roscore Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Running_roscore `roscore` can be launched either from the PC or directly from the Pi-puck. Before starting roscore, open a terminal and issue the following commands: - `export ROS_IP=roscore-ip` - `export ROS_MASTER_URI=http://roscore-ip:11311` where `roscore-ip` is the IP of the machine that runs `roscore` Then start `roscore` by issueing `roscore`. ## Running the ROS node Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Running_the_ROS_node Before starting the e-puck version 2 ROS node on the Pi-puck, issue the following commands: - `export ROS_IP=pipuck-ip` - `export ROS_MASTER_URI=http://roscore-ip:11311` where `pipuck-ip` is the IP of the Pi-puck extension and `roscore-ip` is the IP of the machine that runs `roscore` (can be the same IP if `roscore` runs directly on the Pi-puck). To start the e-puck version 2 ROS node issue the command: `roslaunch epuck_driver_cpp epuck_minimal.launch debug_en:=true ros_rate:=20` The following graph shows all the topics published by the e-puck version 2 driver node: ![ros-e-puck2.jpg](https://www.gctronic.com/doc/images/2/21/ros-e-puck2.jpg) *Click to enlarge* ## Test the communication Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Test_the_communication You can test if the communication between the robot and the computer is actually working by simply display messages published by a topic, e.g.: `rostopic echo /proximity0` You can have the list of all the topics by issuing the command: `rostopic list`. You can move the robot straight forward by issuing `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'`. You can rotate the robot on the spot by issuing `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'`. You can change the LEDs state by issuing `rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [LED1, LED3, LED5, LED7]}"`, e.g. `rostopic pub -1 /mobile_base/cmd_led std_msgs/UInt8MultiArray "{data: [1, 1, 1, 1]}"` to turn them all on. ## Get the source code Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Get_the_source_code The last version of the e-puck version 2 ROS node can be downloaded from the git: `git clone -b pi-puck https://github.com/gctronic/epuck_driver_cpp.git` To update to the last version follow these steps: 1. `cd ~/rosbots_catkin_ws/src/` 2. `rm -R -f epuck_driver_cpp` 3. `git clone -b pi-puck https://github.com/gctronic/epuck_driver_cpp.git` 4. `cd ~/rosbots_catkin_ws/` 5. `catkin_make --only-pkg-with-deps epuck_driver_cpp` ## Python version Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Python_version A Python version developed by the York University can be found here . # ROS 2 Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#ROS_2 ROS2 Foxy running on Raspberry Pi OS Buster is available in the section [Raspberry_Pi_OS_Buster](https://www.gctronic.com/doc/index.php?title=Pi-puck#Raspberry_Pi_OS_Buster). ## Running ROS 2 node Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Running_ROS_2_node To start the robot node issue the command `ros2 run epuck_ros2_driver driver`. To start the camera node issue the command `ros2 run epuck_ros2_camera camera`. To start the ultra wide band node issue the command `ros2 run epuck_ros2_uwb uwb_pub --ros-args -p "tag_name:=my_tag"`, you can change the parameter `tag_name`. If you want to start all the nodes, you can use the launch script by issuing the command `ros2 launch epuck_ros2 robot_launch.py camera:=true uwb:=true`; if you want you can choose whether to start or not the camera and UWB nodes by setting the related parameters. ## Test the communication Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Test_the_communication_2 You can test from the computer if the communication with the robot is actually working by simply display messages published by a topic, e.g.: `ros2 topic echo /tof` You can have the list of all the topics by issuing the command: `ros2 topic list`. You can move the robot straight forward by issuing `ros2 topic pub -1 /cmd_vel geometry_msgs/Twist "{linear:{x: 2.0, y: 0.0, z: 0.0}, angular:{x: 0.0, y: 0.0, z: 0.0}}"`. You can change the LEDs state by issuing `ros2 topic pub -1 /led0 std_msgs/msg/Bool "{data: true}"`; topics for LEDs are `/led0`, `/led2`, `/led4`, `/led6`. You can change the RGB LEDs state by issuing `ros2 topic pub -1 /led1 std_msgs/msg/Int32 "{data: 0x00FFFFFF}"` (turn on white); topics for RGB LEDs are `/led1`, `/led3`, `/led5`, `/led7`. A simple example node in Python is also available in the repo `https://github.com/gctronic/epuck_ros2_pub.git` ## Get the source code Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Get_the_source_code_2 The last version of the e-puck version 2 ROS2 node can be downloaded from the git: `git clone https://github.com/gctronic/epuck_ros2` # OpenCV Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#OpenCV OpenCV 3.4.1 is integrated in the Pi-puck system. # York Robotics Lab Expansion Board Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#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 . ![yrl-expansion-top.jpg](https://www.gctronic.com/doc/images/b/ba/yrl-expansion-top.jpg) An example showing how to communicate with the YRL expansion board is available in the Pi-puck repository of the York Robotics Lab: 1. `git clone https://github.com/yorkrobotlab/pi-puck.git pi-puck_yrl` 2. `cd pi-puck_yrl/python-library` 3. `python3 pipuck-library-test.py -x` Once started, press in sequence up, down, left, right, center to continue the demo. ## Assembly Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#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. ![yrl-exp1.jpg](https://www.gctronic.com/doc/images/2/2b/yrl-exp1.jpg) ![yrl-exp2.jpg](https://www.gctronic.com/doc/images/4/4e/yrl-exp2.jpg) ![yrl-exp3.jpg](https://www.gctronic.com/doc/images/f/fe/yrl-exp3.jpg) ## XBee Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#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 `XBEE 802.15.4-USB ADAPTER` firmware; this can be done with the [XTCU software](http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/xctu). With XTCU be sure to program also the same parameters on both modules in order to be able to communicate between each other: `Channel` (e.g. `C`), `PAN ID` (e.g. `3332`), `DH = 0`, `DL = 0`, `MY = 0`. Some Python examples ara available in the [YRL Expansion Board GitHub repository](https://github.com/yorkrobotlab/pi-puck-expansion-board) that can be used to communicate with the XBee module mounted on the YRL expansion. These examples are based on the [Digi XBee Python library](https://github.com/digidotcom/xbee-python) that can be installed with the command `pip3 install digi-xbee`. This library requires the XBee module to be configured in API mode; you can setup this mode following these steps: 1. `git clone https://github.com/yorkrobotlab/pi-puck-expansion-board.git` 2. `cd pi-puck-expansion-board/xbee` 3. `python3 xbee-enable-api-mode.py` Now connect the second module to the computer and run XTCU, select the console view and open the serial connection. Then run the [xbee-send-broadcast.py](https://projects.gctronic.com/epuck2/PiPuck/xbee-send-broadcast.py) example from the Pi-puck by issuing the command: `python3 xbee-send-broadcast.py`. From the XTCU console you should receive `Hello Xbee World!`. For more information refer to . # Time-of-Flight Distance Sensor add-on Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Time-of-Flight_Distance_Sensor_add-on 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: ![pi-puck-tof.jpg](https://www.gctronic.com/doc/images/8/8b/pi-puck-tof.jpg) For more information have a look at . 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. ## Communicate with the ToF sensors Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_ToF_sensors In order to communicate with the sensors you can use the `multiple-i2c-bus-support` branch of the [vl53l1x-python](https://github.com/pimoroni/vl53l1x-python) library from [Pimoroni](https://shop.pimoroni.com/). To install this library follow these steps: 1. `git clone -b multiple-i2c-bus-support https://github.com/pimoroni/vl53l1x-python.git` 2. `cd vl53l1x-python` 3. `sudo python3 setup.py install` A Python example showing how to read data from the ToF sensors is available in the Pi-puck repository of the York Robotics Lab: 1. `git clone https://github.com/yorkrobotlab/pi-puck.git pi-puck_yrl` 2. `cd pi-puck_yrl/python-library` 3. `python3 pipuck-library-test.py -t` # Ultra Wide Band extension for Pi-Puck Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Ultra_Wide_Band_extension_for_Pi-Puck ![uwb-top.jpg](https://www.gctronic.com/doc/images/5/5c/uwb-top.jpg) ![uwb-front.jpg](https://www.gctronic.com/doc/images/e/e4/uwb-front.jpg) The Ultra Wide Band extension is connected to the Pi-Puck extension through the extension connector pins (2x10). Pin 1 is marked in white in both the Pi-Puck connector and UWB extension in order to connect it in the correct direction as shown in the following figure: ![uwb-hw-connection.jpeg](https://www.gctronic.com/doc/images/6/6b/uwb-hw-connection.jpeg) ## Communicate with the UWB modules Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Communicate_with_the_UWB_modules The SPI channel is used for the communication between the Raspberry Pi and the Ultra Wide Band module so that the user is able to configure the module and receive position information from the RPi OS. Here are some examples based on [DWM1001_DWM1001-DEV_MDEK1001_Sources_and_Docs_v11.zip](https://projects.gctronic.com/epuck2/uwb/DWM1001_DWM1001-DEV_MDEK1001_Sources_and_Docs_v11.zip): - Anchor configuration: go to the directory `/home/pi/Pi-puck/uwb/examples/conf_anchor` and issue the command `./conf_anchor`; to build issue the command `make` - Tag configuration: go to the directory `/home/pi/Pi-puck/uwb/examples/conf_tag` and issue the command `./conf_tag`; to build issue the command `make` - Get position from tag: go to the directory `/home/pi/Pi-puck/uwb/examples/tag_get_pos` and issue the command `./tag_get_pos`; to build issue the command `make` The following Android application [DRTLS_Manager_R2.apk](https://projects.gctronic.com/epuck2/uwb/DRTLS_Manager_R2.apk) can also be used to configure the Ultra Wide Band extension. Python 3 examples are also available in the directory `/home/pi/Pi-puck/uwb/examples/python/`: - Anchor configuration: issue the command `python3 conf_anchor.py` - Tag configuration: issue the command `python3 conf_tag.py` - Get position from tag: issue the command `python3 tag_get_pos.py` If not already present, you need to install the following package `pip3 install git+https://github.com/gctronic/decawave-1001-rjg.git` ## Arena configuration Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Arena_configuration To get started you need 4 `ANCHORS` to delimit your arena (see following figure); one of the anchors need to be configured as `initiator`. The anchors are standalone and the Ultra Wide Band extension is equipped with a standard battery connector for easy recharging. The anchor battery lasts for more than 5 hours. Beware to always detach the battery at the end of your experiments in order to avoid to ruin it. ![uwb-anchor-connected.jpeg](https://www.gctronic.com/doc/images/5/56/uwb-anchor-connected.jpeg) ![uwb-anchor-disconnected.jpeg](https://www.gctronic.com/doc/images/8/89/uwb-anchor-disconnected.jpeg) Then you can equip your robots with the Ultra Wide Band extension and by configuring them as `TAG` you will receive their position inside the arena. ## Charging Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Charging You have 3 options to charge the anchors: 1. using the Pi-puck extension : ![uwb-recharge-pipuck.jpeg](https://www.gctronic.com/doc/images/0/03/uwb-recharge-pipuck.jpeg) 2. using an e-puck2 robot (remove the robot battery from the bottom when you want to charge the UWB battery) : ![uwb-recharge-epuck.jpeg](https://www.gctronic.com/doc/images/0/01/uwb-recharge-epuck.jpeg) 3. using your own LiPo charger for 4.2V battery ## Tests Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Tests During our test on a 2m x 2m arena with 4 anchors we get position (x, y) accuracy of the e-puck2 robot of about 7cm. Have a look at the following video: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) And also with 4 tags: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## Documentation Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Documentation 1. [DWM1001C_Datasheet.pdf](https://projects.gctronic.com/epuck2/uwb/DWM1001C_Datasheet.pdf) 2. [DWM1001-Firmware-User-Guide.pdf](https://projects.gctronic.com/epuck2/uwb/DWM1001-Firmware-User-Guide.pdf) 3. [DWM1001-API-Guide.pdf](https://projects.gctronic.com/epuck2/uwb/DWM1001-API-Guide.pdf) # OLED display Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#OLED_display With the Pi-puck v2.1 (available from about mid 2023) it is possible to directly connect a small OLED display (0.91 inch, 128x32) to the extension as shown in the following figure; you just need to push the connector inside the correct holes (highlighted in the yellow box): ![pipuck-display-holes.jpg](https://www.gctronic.com/doc/images/9/9e/pipuck-display-holes.jpg) ![pipuck-display-mounted1.jpg](https://www.gctronic.com/doc/images/f/fb/pipuck-display-mounted1.jpg) ![pipuck-display-mounted2.jpg](https://www.gctronic.com/doc/images/0/05/pipuck-display-mounted2.jpg) ## Requirements Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Requirements_2 The instructions given in this chapter are only needed if you are working with the old system ([Raspberry Pi OS Stretch](https://www.gctronic.com/doc/index.php?title=Pi-puck#Raspberry_Pi_OS_Stretch)), otherwise you can skip it. The following library can be used to control the display. To install the library issue the following commands: - `sudo python -m pip install --upgrade pip setuptools wheel` - `sudo pip2 install spidev==3.5` - `sudo pip install Adafruit-SSD1306` ## Examples Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Examples The examples are based on Python, refer to the repo [examples](https://github.com/adafruit/Adafruit_Python_SSD1306/tree/master/examples) that shows how to use the library. You can find the examples in the directory `/home/pi/Pi-puck/display/`. There are 4 examples available: - `python animate.py` - `python image.py` : ![pipuck-display-example2.jpg](https://www.gctronic.com/doc/images/f/f4/pipuck-display-example2.jpg) - `python shapes.py` - `python stats.py` : ![pipuck-display-example1.jpg](https://www.gctronic.com/doc/images/c/c1/pipuck-display-example1.jpg) # Magnetometer Link: https://www.gctronic.com/doc/index.php?title=Pi-puck#Magnetometer With the Pi-puck v2.1 (available from about mid 2023) it's available a BMM150 3-axis magnetometer sensor ([datasheet](https://projects.gctronic.com/epuck2/PiPuck/Bst-bmm150-ds001.pdf)). The examples are based on the work done here and adapted to be used with the Pi-puck extension. Both C and Python3 examples are available: - C: go to the directory `/home/pi/Pi-puck/magnetometer/c` and issue the command `./bmm150`; to build issue the command `make` - Python3: go to the directory `/home/pi/Pi-puck/magnetometer/python` and issue the command `python3 get_geomagnetic_data.py` --- # ROS2 Source: https://www.gctronic.com/doc/index.php?title=ROS2 Last edited: 2023-10-19T09:08:42Z ROS2 Humble is released in a docker container named `ros_docker_epuck`. The ROS2 node can be found here . In order to start the node follow these steps: 1. `docker run -it --privileged --network="host" ros_docker_epuck` 2. `source /opt/ros/humble/install/local_setup.bash` 3. `ros2 launch epuck_ros2 robot_launch.py` From your computer (pi-puck and computer must be connected to the same network) you can then list the topics with the command `ros2 topic list`. For example you can read the time of flight sensor values with the command `ros2 topic echo /tof`. You can turn on led0 with the command `ros2 topic pub -1 /led0 std_msgs/msg/Bool "{data: true}"`. You can move forward with the command `ros2 topic pub -1 /cmd_vel geometry_msgs/Twist "{linear:{x: 0.0, y: 0.0, z: 0.0}, angular:{x: 0.0, y: 0.0, z: 0.0}}"`. ======================================================================== TOPIC: omnivision Documentation for the first Omnivision camera module (Omnivision V1). Do not apply this information to other Omnivision versions and do not apply information regarding others Omnivision versions to Omnivision V1. Check which module version a statement refers to. ======================================================================== # Omnivision Module Source: https://www.gctronic.com/doc/index.php?title=Omnivision_Module Last edited: 2026-04-22T11:34:34Z # Overview Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Overview The omnivision module is an extension that is coupled with the e-puck extension for Gumstix Overo COM. The camera is the same as the one mounted on the e-puck, having a maximum resolution of 640x480 (thus 480x480 for this purpose) and a framerate of 18 fps with the current driver. The module includes the camera and 3 RGB leds as shown in the following figure. The package will contain the omnivision extension board already mounted on the Gumstix extension (comprised of a Gumstix Earth COM) with the camera connected with the flex ribbon cable and a nano wifi dongle that is out of sight of the camera; the package is strongly recommended since the assembly is a little tricky, but the extension alone is available too for those who already have an e-puck extension for Gumstix Overo COM (nano wifi not included in this case). The driver of the camera is open-source, you can find it in the [camera driver section](https://www.gctronic.com/doc/index.php/Omnivision_Module#Camera_driver). ![Omnicam-schema.jpg](https://www.gctronic.com/doc/images/b/b9/Omnicam-schema.jpg) The field of view is up to 7 degrees over the horizon. ![Omnicam-view2.jpg](https://www.gctronic.com/doc/images/8/89/Omnicam-view2.jpg) # Getting started Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Getting_started ## 1. Hardware Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#1._Hardware The camera mounted on the robot must be removed to avoid conflicts on the I2C bus. ## 2. Software Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#2._Software A specific firmware must be charged on the e-puck when working with this extension, it can be downloaded from section [E-Puck#Standard_firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware). Remember to put the selector in position 10. The system on the micro sd is the same used for the gumstix extension alone, refer to section for more informations. ## 3. Terminal configuration Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#3._Terminal_configuration Execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No". ## 4. U-Boot Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#4._U-Boot In order to use the extension module it's required to modify the boot commands within u-boot, as shown afterwards: : 1) Turn on the robot and enter the u-boot command line by pressing "any key" when the following message is shown (it is displayed in a few seconds after turning on the robot): ``` Hit any key to stop autoboot: 1 ``` : 2) modify the variable *mmcargs*, this will activate the clock for the camera: ``` setenv mmcargs setenv bootargs console=${console} video=${videospec},mode:${videomode} root=/dev/mmcblk0p2 rw rootfstype=ext3 rootwait po6030cam.omap_gen_clock=1 ``` : 3) add a new environment variable called *confleds*: ``` setenv confleds "mw.w 0x480020CE 0x000C; mw.w 0x48002114 0x000C; mw.w 0x48002126 0x000C; mw.w 0x48002128 0x000C; mw.w 0x4800212A 0x000C; mw.w 0x4800212C 0x000C; mw.w 0x4800212E 0x000C; mw.w 0x48002132 0x000C; mw.w 0x48002130 0x000C" ``` : 4) modify the *bootcmd* varibale in order to call *confleds*: ``` setenv bootcmd "run confleds; if mmc init; then if run loadbootscript; then run bootscript; else if run loaduimage; then run mmcboot; else run nandboot; fi; fi; else run nandboot; fi" ``` : 5) save the environment variables in order to preserve the configuration for the next boots: ``` saveenv reset ``` : 6) login with user=root, password=root ## 5. WiFi Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#5._WiFi The nano WiFi dongle shipped with the extension board is an Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu). The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it: 1. turn on the robot and login with user=root, password=root 2. type *insmod 8192cu.ko* (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created 3. type *ifconfig wlanX up* (where X is a number) to turn on the device; now the wifi can be configured and used normally ## 6. Demos Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#6._Demos Once logged in it's possible to execute the demos: - type *./demos/test-leds* to run the basic leds test demo - type *./demos/leds-pwm* to run the pwm demo For more information and source code refer to [Software section](https://www.gctronic.com/doc/index.php/Omnivision_Module#Software) # Software Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Software ## Demos Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Demos All the demos using the camera proposed in the [gumstix extension section](https://www.gctronic.com/doc/index.php/Overo_Extension#Demos) will work also with the omnivision module. Moreover some specific demos for this extension are available in the next sections. ### Basic leds test demo Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Basic_leds_test_demo This application is thought to illustrate how to communicate with the 3 RGB leds of the omnivision extension. Basically there are 9 gpio lines (one for each color) exported automatically in the system (see section [Getting started](https://www.gctronic.com/doc/index.php/Omnivision_Module#Getting_started)) that can be used to turn on and off all the leds. For more information on gpio refer to the section [GPIO - pins mode](https://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode). The leds test demo can downloaded from the following link [test-leds.c](https://projects.gctronic.com/omnicam/test-leds.c). ### PWM demo Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#PWM_demo This demo handles the leds implementing a software pwm; this let the user have finer control on the leds, that is their brightness is controllable and the range of reproducible colors is greater acting on the duty cycle of each one of the RGB leds. Once the application is started the user can control the duty cycles through the console with the following commands: - red led 1: q (inc duty), w (dec duty) - green led 1: a (inc duty), s (dec duty) - blue led 1: y (ind duty), x (dec duty) - red led 2: e (inc duty), r (dec duty) - green led 2: d (inc duty), f (dec duty) - blue led 2: c (inc duty), v (dec duty) - red led 3: t (inc duty), z (dec duty) - green led 3: g (inc duty), h (dec duty) - blue led 3: b (inc duty), n (dec duty) The leds handled through pwm demo can downloaded from the following link [leds-pwm.c](https://projects.gctronic.com/omnicam/leds-pwm.c). ## Camera driver Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Camera_driver Refer to section [camera driver](https://www.gctronic.com/doc/index.php/Overo_Extension#Camera_driver) for more information about the driver of the e-puck camera. # Image unwrapping Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Image_unwrapping Once you get an image from the camera you can post-process the image in order to see the whole 360-degrees laid out in a rectangular strip. For this purpose vision software called [RoboRealm](https://www.roborealm.com/); you can download a free 30 days trial. Once you installed the software you can proceed with the following steps: 1) Grab an image from the camera: ![Camera9-cut.jpg](https://www.gctronic.com/doc/images/9/9b/Camera9-cut.jpg) 2) Start RoboRealm, open the grabbed image and apply a polar transformation (Transforms=>Polar); you should get an image similar to the following one: ![Camera9-cut-polar.jpeg](https://www.gctronic.com/doc/images/8/8a/Camera9-cut-polar.jpeg) 3) Finally you need to simply cut the relevant part of the image, as shown here: ![Camera9-cut-polar2.jpg](https://www.gctronic.com/doc/images/b/ba/Camera9-cut-polar2.jpg) # Omnivision module with Caspa camera board Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module#Omnivision_module_with_Caspa_camera_board This version of the omnivision module use the [caspa camera board](https://wiki.gumstix.org/index.php?title=Caspa_camera_boards) instead of using the e-puck camera. It's based on the 2.6.34 kernel so it isn't possible to use both the robot camera and the omnivision camera, since at the moment the driver of the e-puck camera isn't compatible with the 2.6.34 kernel. Moreover the RGB leds aren't usable with this omnivision hardware version (not connected). An image can be grabbed with the following command; in the example the image is cropped to 480x480 starting at offset (136,0) and saved as jpeg (10 frames grabbed): ``` mplayer tv:// -vo jpeg -vf crop=480:480:136:0 -ss 1 -frames 10 -loop 1 -tv driver=v4l2:device=/dev/video0 ``` If the image results too dark, especially in indoor enviornments, it is possible to enable a camera parameter (companding) when loading the driver; follow these steps: ``` # rmmod mt9v032 # insmod /lib/modules/2.6.34/kernel/drivers/media/video/mt9v032.ko low_light=1 ``` Now the next grabbed images should be brighter. In order to setup the wifi connection, you need first stop "NetworkManager" with the following command: ``` /etc/init.d/NetworkManager stop ``` The following image is grabbed with the omnivsion coupled with the caspa: ![Omnivision-caspa.png](https://www.gctronic.com/doc/images/3/32/Omnivision-caspa.png) ======================================================================== TOPIC: omnivision V2 Documentation for the second Omnivision camera module (Omnivision V2). Do not apply this information to other Omnivision versions and do not apply information regarding others Omnivision versions to Omnivision V2. Check which module version a statement refers to. ======================================================================== # Omnivision Module V2 Source: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2 Last edited: 2026-04-22T11:44:59Z # Overview Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Overview ![omnivision-v2-epuck-3.jpg](https://www.gctronic.com/doc/images/b/b8/omnivision-v2-epuck-3.jpg) ![omnivision-v2-epuck-2.jpg](https://www.gctronic.com/doc/images/1/1e/omnivision-v2-epuck-2.jpg) ![omnivision-v2-epuck-4.jpg](https://www.gctronic.com/doc/images/8/85/omnivision-v2-epuck-4.jpg) The omnivision module is upgraded with a microcontroller directly mounted on the extension that is responsible of handling the 3 RGB leds; the power of the leds can be set through I2C. The camera mounted on the extension is an USB 2.0 camera with a maximum resolution of 1280x1024 and a potential framerate of 30 fps. Omnivision module may contain different image sensors depending on shipment date, in particular: - the Targus Micro Webcam - the Trust SpotLight Pro The robot frontal camera below can still be used independently since this camera is connected either to the USB OTG or to the USB HOST of the e-puck gumstix extension. The field of view is up to about 7 degrees over the horizon for the Trust SpotLight Pro, as shown in the following figure: ![omnivision-trust-fieldview.jpg](https://www.gctronic.com/doc/images/7/71/omnivision-trust-fieldview.jpg) The same apply for the Targus camera as shown in the following figure: ![omnivision-targus-fieldview.jpg](https://www.gctronic.com/doc/images/e/e8/omnivision-targus-fieldview.jpg) ## Camera specification Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Camera_specification | Name | **Targus Micro Webcam AVC05EU** | **Trust SpotLight Pro** | | --- | --- | --- | | Supported resolutions | 1280x1024, 640x480, 352x288, 176x144, 160x120 | 1280x1024, 640x480, 352x288, 176x144, 160x120 | | Maximum frame rate | 30 fps | 30 fps | # Getting started Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Getting_started ## 1. Software Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#1._Software As with the gumstix extension, a specific firmware must be charged on the e-puck when working with this extension, it can be downloaded from section [E-Puck#Standard_firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware). Remember to put the selector in position 10. The system on the micro sd is the same used for the gumstix extension alone, refer to section for more informations. ## 2. Terminal configuration Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#2._Terminal_configuration Execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No". Once the boot is terminated login with user=root and password=root. ## 3. WiFi Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#3._WiFi The nano WiFi dongle shipped with the extension board is an Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu). The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it: 1. turn on the robot and login with user=root, password=root 2. if the WiFi dongle is connected to the USB OTG you need to activate typing *./scripts/gumstix-common/usbenable otg* 3. type *insmod 8192cu.ko* (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created 4. type *ifconfig wlanX up* (where X is a number) to turn on the device; now the wifi can be configured and used normally # RGB leds Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#RGB_leds The RGB leds can be controlled from the *gumstix-side* through the I2C (400 KHz). The I2C address is 0x61 and to change the leds state all the values for each led need to be sent as follow: R1, G1, B1, R2, G2, B2, R3, G3, B3. Once logged in it's possible to execute a demo to pilote all the 3 RGB leds through I2C: - type *./demos/omnivision-v2/omnivision-i2c R1 G1 B1 R2 G2 B2 R3 G3 B3* where the Rx,Gx,Bx are the values you would like to set (ranging from 0 to 255) You can download the source code from the following link [omnivision-i2c-clean.c](https://projects.gctronic.com/omnicam/omnivision-i2c-clean.c). It was noticed that when the leds are turned on they can somehow create some reflex in the resulting image; in order to avoid this effect a simple solution would be to put a small piece of black tape on top of them. Refer to the section for more information about the RGB usage. # Camera Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Camera If the camera is connected to the USB OTG port you need to issue the following command to enable it (from */home/root/scripts/gumstix-common/* directory): ``` ./usbenable otg ``` After this command a new device (*/dev/video1*) should be created automatically. If the camera is connected to the USB HOST port then the camera is recognized automatically and the device */dev/video1* should be already available. ## Image streaming Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Image_streaming You can test and see the camera image using mjpeg-streamer; this tool is already configured with a web server in the system image so you can follow these steps: 1. configure the network in order to be able to communicate between the gumstix and the computer 2. issue the following commands: ``` export LD_LIBRARY_PATH=/usr/local/mjpg-streamer/:$LD_LIBRARY_PATH /usr/local/mjpg-streamer/mjpg_streamer -i "input_uvc.so -y -d /dev/video1" -o "output_http.so -p 8090 -w /usr/local/mjpg-streamer/www" ``` 1. open a browser in the computer and insert the address ** where *gumstix-ip* is the network address assigned to the gumstix You can use also your phone to access the webserver. The following figure shows an example of a 640x480 image received through the broswer: ![omnivision-v2-image640x480.jpg](https://www.gctronic.com/doc/images/4/4f/omnivision-v2-image640x480.jpg) For the post-processing of the image refers to the section . ## Image grabbing Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Image_grabbing ### Video 4 linux Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Video_4_linux The [*v4l2grab* application](https://www.gctronic.com/doc/index.php/Overo_Extension#Images_grabbing_.28camera_driver.29) can be used to grab an image from the camera with the following command: ``` ./v4l2grab -d /dev/video1 -o image.jpg -f 1 -W 352 -H 288 ``` Currently the maximum resolution is 352x288 from the OTG port, we're working to solve this limitation. From the USB HOST there is no known limitation. ### OpenCV Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#OpenCV An example demo was implemented to show how to interact with OpenCV and the Omnvision extension. In this demo a color blob is tracked; the target color range need to be passed as argument (HSV color space), the parameters in sequence are: `Hmin Hmax Smin Smax Vmin Vmax debugFlag` (values between 0 and 255, debugFlag = 0 or 1). The robot is rotated in place to track the detected blob. You can download the source code from the following link [blob-tracking-opencv.zip](https://projects.gctronic.com/omnicam/blob-tracking-opencv-rev10.zip). In order to build the code follow these steps: 1. install the toolchain: `sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi` 2. build using the makefile included in the zip file: `make` Before running the application you need to update some libraries on the gumstix system following these steps (this need to be done only once): 1. configure the network in order to have internet access 2. update the package manager repo: `echo 'src/gz base https://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/base/' > /etc/opkg/base-feed.conf` 3. add `arch armv7a-vfp-neon 45` to the file `/etc/opkg/arch.conf` 4. `opkg update` 5. `opkg install libc6` 6. `opkg install libstdc++6` 7. optionally you can also remove some warnings related to the update by running the following script [remove-warnings.sh](https://projects.gctronic.com/omnicam/remove-warnings.sh) Once the system is updated, you can copy the executable `omniOpenCVblobDetection` on the gumstix system and run it. Basically with the HSV range you define a target color, then once the application is started you can move the target around the robot and the robot should try to orient towards it. ## Settings Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Settings You can modify the camera parameters to better suit your needs, here are the steps to install the `v4l2-ctl` utility for doing that: 1. configure internet access 2. make a copy of the current repo for the package source: `mv /etc/opkg/base-feed.conf /dest-dir` 3. add the new repo: `echo 'src/gz base https://feeds.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base' > /etc/opkg/base-feed.conf` 4. issue the command `opkg update` 5. place the file [v4l-utils_0.8.1-r0.6_armv7a.ipk](https://projects.gctronic.com/omnicam/v4l-utils_0.8.1-r0.6_armv7a.ipk) in the home directory and then issue: `opkg install v4l-utils_0.8.1-r0.6_armv7a.ipk` Once you install the utility, you can have a list of all available camera parameters by issueing the command `v4l2-ctl -L`. For example to change the saturation you issue the command: `v4l2-ctl --device=1 -c saturation=128` # Charging Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Charging The omnivsion module incorporates an additional battery that can be charged with the e-puck battery charger, but it needs cabling (provided together with the extension) as illustrated in the following figures: ![omnivision-v2-epuck-charger.jpg](https://www.gctronic.com/doc/images/5/5e/omnivision-v2-epuck-charger.jpg) ![omnivision-charger-soldering.jpg](https://www.gctronic.com/doc/images/b/b1/omnivision-charger-soldering.jpg) # Extension firmware Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V2#Extension_firmware The firmware programmed in the microcontroller mounted on the extension is freely available from the following link [omnivision-uc-firmware.zip](https://projects.gctronic.com/omnicam/omnivision-uc-firmware.zip). The project is created with MPLAB IDE from Microchip. ======================================================================== TOPIC: omnivision V3 Documentation for the third Omnivision camera module (Omnivision V3). Do not apply this information to other Omnivision versions and do not apply information regarding others Omnivision versions to Omnivision V3. Check which module version a statement refers to. ======================================================================== # Omnivision Module V3 Source: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3 Last edited: 2026-04-22T11:51:27Z # Overview Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3#Overview Features: - 5Mpixel color camera looking 360° all around the robot - compatible with Pi-puck and interfaced with the Raspberry Pi Zero W - parabolic mirror for uniform pixel distribution - suitable for basic image processing such as blobs, colors and light detection. # Image grabbing Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3#Image_grabbing You can use `raspistill` to grab an image with the command: `raspistill -t 0 -k -o image.jpg`. This command open a live preview of the camera. When you press `ENTER`, an image is grabbed. To terminate press `x+ENTER`. You can find detailed documentation about `raspistill` in the following link . # Image unwrapping Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3#Image_unwrapping ![omni3-img-unwrap.jpg](https://www.gctronic.com/doc/images/2/27/omni3-img-unwrap.jpg) # OpenCV Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3#OpenCV ## Blob tracking Link: https://www.gctronic.com/doc/index.php?title=Omnivision_Module_V3#Blob_tracking 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. The code can be downloaded from the following repo: `git clone https://github.com/e-puck2/e-puck2_pi_blob-tracking.git` Refer to the github page for information about building and running this demo. This example is available in the system in the directory `/home/pi/e-puck2_pi_blob-tracking`. This directory includes a simple launch script for the demo that can be run with the command `./omni_detect_blob.sh`; the color parameters given are supposed to follow a pink object. Beware that this directory isn't garanted to be synced with the last repository version, thus to get the last version use `git pull` and then rebuild. ======================================================================== TOPIC: Other extensions Other extension modules designed by GCtronic for both the e-puck and e-puck2 robots. Check which robot a statement refers to. ======================================================================== # Others Extensions Source: https://www.gctronic.com/doc/index.php?title=Others_Extensions Last edited: 2026-04-22T12:47:53Z # Range and bearing Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Range_and_bearing ![randb-1.jpg](https://www.gctronic.com/doc/images/e/e9/randb-1.jpg) ![randb-2.jpg](https://www.gctronic.com/doc/images/8/83/randb-2.jpg) 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: - [Schematics (pdf)](https://projects.gctronic.com/randb/eRandB_Ed.D_Schematics.pdf) - [Assembling (pdf)](https://projects.gctronic.com/randb/eRandB_Ed.D_Assembling.pdf) - [Bill of Materials (xls)](https://projects.gctronic.com/randb/eRandB_Ed.D_BillOfMaterials.xls) - [PCB (pdf)](https://projects.gctronic.com/randb/eRandB_Ed.D_PCB.pdf) - [Hardware source files(zip)](https://projects.gctronic.com/randb/eRandB_Ed.D_HardwareSourceFiles.zip) - [Fabrication: Gerber, pick and place, ... (zip)](https://projects.gctronic.com/randb/eRandB_Ed.D_Fabrication.zip) - [e-RandB manual (pdf)](https://projects.gctronic.com/randb/eRandB_manual.pdf) - [e-RandB firmware (zip)](https://projects.gctronic.com/randb/eRandB_firmware.zip) - [e-puck software and examples (tgz)](https://projects.gctronic.com/randb/eRandB_software.tgz) You can find more information about this board in the following links: . 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 MSB (prepare) | > | 14 | - | data LSB (send `(MSB<<8)+LSB`) | > | 16 | - | 0 store light conditions (calibration) | > | 17 | - | 0=onboard calculation, 1=host calculation | ## Firmware source code Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Firmware_source_code The firmware code of the range and bearing extension 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 and follow the installation instructions (default configuration is ok) - Linux: issue the command `sudo apt-get install git` - Mac: issue the command `brew install git` The source code can downloaded with the command: `git clone https://github.com/gctronic/range_and_bearing_firmware.git` The command must be issued in `Git bash` on Windows, or in a terminal on Linux / Mac. You can download the pre-built firmware in the following link [range and bearing firmware (17.12.21)](https://projects.gctronic.com/randb/range_and_bearing_firmware_17.12.21_f928563.hex). ## e-puck 1 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#e-puck_1 A simple [MPLAB project](https://projects.gctronic.com/randb/test-eRandB.zip) 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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#e-puck_2 The e-puck2 standard firmware contains examples usages of the range and bearing extension. When the selector is in position 4 then the robot is set to be a receiver or a transmitter (you can switch between roles using the small button on the back of the robot), when in position 5 then the robot is both transmitter and receiver at the same time. In both demos the information received (data received, bearing, distance and sensor id) will be printed via Bluetooth and USB. It's important to notice that in both these demos the time of flight sensor is disabled in order to avoid (infrared) interference with the front sensors of the range and bearing extension; you can use it in your application if you want but you need to take in consideration this side effect. Moreover also the proximity sensors of the robot interfere with the range and bearing communication, so you have some options to increase communication distance and throughput: first of all if you don't need the proximities you can simply disable them, otherwise you can set a slower proximity sampling frequency and disable the proximity sampling during transmission of a message. The latter option is implemented in the demo 5. 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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Ground_sensors ![E-puck-groundsensors.jpg](https://www.gctronic.com/doc/images/3/31/E-puck-groundsensors.jpg) 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](https://www.gctronic.com/doc/index.php?title=E-Puck#Standard_firmware), for e-puck2 refer to section [Factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#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](https://www.gctronic.com/doc/index.php?title=E-Puck#Getting_started) (e-puck1) or [Connecting to the Bluetooth](https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#Connecting_to_the_Bluetooth) (e-puck2). For more information about the Bluetooth protocol refer to section [Advanced sercom protocol](https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol). If you couple the e-puck extension for Gumstix Overo with the ground sensor refer to the section 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 . ## Assembly for e-puck2 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Assembly_for_e-puck2 | [1] | [2] | [3.1] | [3.2] | [3.3] | [3.4] | | --- | --- | --- | --- | --- | --- | | ground-assembly-1.png | ground-assembly-2.png | ground-assembly-3.1.png | ground-assembly-3.2.png | ground-assembly-3.3.jpegground-assembly-3.4.jpeg | ground-assembly-3.5.png | | [4] | [5.1] | [5.2] | [5.3] | [5.4] | [6] | | ground-assembly-4.png | ground-assembly-5.1.png | ground-assembly-5.2.png | ground-assembly-5.3.png | ground-assembly-5.4.png | ground-assembly-6.png | 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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Assembly | [1] | [2] | [3] | [4.1] | [4.2] | | --- | --- | --- | --- | --- | | cliff-mounting-1.jpg | cliff-mounting-2.jpg | cliff-mounting-3.jpg | cliff-mounting-4-1.jpg | cliff-mounting-4-2.jpg | | [5.1] | [5.2] | [6] | [7] | [8] | | cliff-mounting-5-1.jpg | cliff-mounting-5-2.jpg | cliff-mounting-6.jpg | cliff-mounting-7.jpg | cliff-mounting-8.jpg | 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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Electrical_schema The circuit diagram of the e-puck cliff extension is available to the community on the following link [electrical schema](https://projects.gctronic.com/cliff-sensor/CliffSensorV1.0.pdf). ## Software Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Software ### e-puck firmware Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#e-puck_firmware Refers to the section [E-Puck Standard firmware](https://www.gctronic.com/doc/index.php/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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#e-puck_demos To demonstrate the capabilities of the cliff sensors module here is an MPLAB project [Demo-cliff-autocharge.zip](https://projects.gctronic.com/cliff-sensor/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](https://www.gctronic.com/doc/index.php/Others_Extensions#Videos). - 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](https://www.gctronic.com/doc/index.php/Others_Extensions#Videos). ### Extension firmware Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Extension_firmware The ground sensor fimrware developed at EPFL (can be downloaded at the site from [this page](https://www.e-puck.org/index.php?option=com_phocadownload&view=category&id=9:ground-sensors&Itemid=38)) was extended to interact with the additional two sensors. The source code can be downloaded from [cliff-firmware](https://projects.gctronic.com/cliff-sensor/pic18_floor_sensor_c18-cliff.zip); 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 Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#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 . ## Images Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Images Robot equipped with the cliff sensor: ![Cliff+charger.jpg](https://www.gctronic.com/doc/images/9/90/Cliff%2Bcharger.jpg) The robot can be easily moved to the charging station as shown in the following figure: ![Cliff-charging.jpg](https://www.gctronic.com/doc/images/3/38/Cliff-charging.jpg) 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: ![Cliff-zoom.jpg](https://www.gctronic.com/doc/images/7/7a/Cliff-zoom.jpg) ## Videos Link: https://www.gctronic.com/doc/index.php?title=Others_Extensions#Videos [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ======================================================================== TOPIC: Overo Extension e-puck extension board for the Gumstix Overo COM ======================================================================== # Overo Extension Source: https://www.gctronic.com/doc/index.php?title=Overo_Extension Last edited: 2026-04-22T12:02:41Z This is a mini how-to of the e-puck extension board for the Gumstix Overo COM. # Minimal getting started Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Minimal_getting_started | 1. upload the [standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) to the e-puck robot and put selector in position 10 2. connect the USB cable: mini-USB to the extension module and the other side to the PC 3. execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No". 4. switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds) 5. login with user=root, password=root | | --- | Anyway you're encouraged to read all the documentation since you'll find more detailed explanations. # Introduction Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Introduction ![Ext+robot1.jpg](https://www.gctronic.com/doc/images/d/d4/Ext%2Brobot1.jpg) This introductory section explains the minimal procedures needed to work with the Gumstix Overo computer-on-module (COM) mounted on the e-puck extension board and gives a general overview of the available demos and scripts shipped with the micro sd. You can also refer to [extension-instructions](https://projects.gctronic.com/Gumstix/extension-instructions.pdf) that is a document containing the most important information in order to start working with the extension. The extension is mostly an interface between the e-puck robot and the Gumstix Overo COM. Gumstix Overo COM: [product information](https://www.gumstix.com) and [programming information](https://www.gumstix.org), ## Full package Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Full_package The full package content is: - e-puck extension with Gumstix Overo COM and micro sd card already inserted - USB adapter for the micro sd - A to mini-B USB cable - USB wifi dongle - external power adapter - USB host adapter The standard COM mounted on the e-puck extension is the Gumstix Overo EarthSTORM COM. Some extensions were delivered with the Gumstix Overo SandSTORM COM, don't worry, the main difference between the two COMs is that the SandSTORM has no flash memory, but the flash isn't necessary since the system is booted from the micro sd. ## Requirements Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Requirements In order to connect to the extension through the mini USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise visit the following site and download the drivers for your architecture (32 or 64 bits) [FTDI drivers](https://www.ftdichip.com/Drivers/VCP.htm). ## General procedure Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#General_procedure The e-puck extension board for the Gumstix Overo COM comes with a pre-configured system ready to run without any additional configuration. The whole system is installed on a micro sd and is composed of: - U-Boot (bootloader customized for the hardware) - OMAP35x Linux TI-PSP (linux kernel) - some demos and useful scripts in the /home/root directory It's important to note that the flash isn't reprogrammed, so it will contain the factory system. In order to access the system from a PC (console mode), the following steps must be performed: 1. connect the USB cable: mini-USB to the extension module and the other side to the PC 2. execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No". 3. switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds) 4. login with user=root, password=root ## Wireless setup Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Wireless_setup Before proceding with the following configurations be sure that the WiFi dongle is well recognized, refer to section [WiFi_dongle](https://www.gctronic.com/doc/index.php/Overo_Extension#WiFi_dongle). ### Wireless configuration using a script Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Wireless_configuration_using_a_script The script *setupWifi* placed under /home/root/scripts is used to configure easily the wireless network (managed mode) and need to be adapted to your specific situation. The script is shown below: ``` #!/bin/bash ifconfig wlan0 up iwconfig wlan0 essid SSID key HEX_KEY iwconfig wlan0 ap MAC_ADDRESS iwconfig wlan0 rate 54M ifconfig wlan0 LOCAL_IP netmask SUBNET_MASK route add default gw GATEWAY_IP ``` To know the available wifi networks and related information such as mac address of the access point, you can issue the command *iwlist scanning wlan0*. On some platforms, udev may rename the network interface *wlan0.* In this event, the 'setupWifi' script will return several errors, some of which will say "No Such Device." To identify your network interfaces, use the commands *ifconfig* or *iwconfig.* These will provide a listing of your devices, and their current states. Identify the appropriate interface (typically *wlan#* where "#" is a number) and replace *wlan0* in the above script with this. If you're using dhcp, you can instead adapt the script *setupWifiDhcp* found under /home/root/scripts: ``` #!/bin/bash ifconfig wlan0 up iwconfig wlan0 essid SSID key HEX_KEY iwconfig wlan0 ap MAC_ADDRESS iwconfig wlan0 rate 54M dhclient wlan0 ``` The parameters that must be customized are shown in capitals; after that you can execute the script typing *./setupWifi* (or *./setupWifiDhcp*) and after a while a message should be displayed indicating that the wireless is ready. You can test the network configuration using *ping*. It may be necessary to create a directory if you get the error "can't create /var/lib/dhcp/dhclient.leases: No such file or directory." Use the *mkdir* command ``` mkdir /var/lib/dhcp ``` Usually, when the Wifi dongle is connected to the AP, a message is written in the message buffer of the kernel. The following bash code snippet can be used to make sure that the connection is well established when the program returns: ``` #!/bin/bash echo Wait until the Wifi is connected to the AP while true do #the text "link becomes ready" can vary according the Wifi dongle a=$(dmesg | grep wlan0 | grep "link becomes ready") if [ -n "$a" ] then echo Wifi enabled! exit fi sleep 1 done ``` In order for the *setupWifi* or *setupWifiDhcp* scripts to be run during boot, copy the appropriate script into the *init.d* directory with the other start/stop scripts. ``` cp -i ~/scripts/setupWifi /etc/init.d/setupWifi ``` Then determine which run level the system is using with the command: ``` runlevel ``` This should return "N #" where # is the run level number. Create a link to your script in the *init.d* directory within the directory */etc/rc#.d* Name the link *S##setupWifi.* The number ## (customarily 2 digits, which you choose) determines where in the startup sequence your script will be run. It is good advice to choose a number just smaller than the largest in the *rc#.d* directory, this way the script is not called before lower-level ones. The creation of this link can be done with the following command (where # and ## must be changed to their appropriate values). ``` ln -i -s /etc/init.d/setupWifi /etc/rc#.d/S##setupWifi ``` ### Wireless configuration using a wpa_supplicant Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Wireless_configuration_using_a_wpa_supplicant Alternativerly, the Wifi connection can be set up by using both [wpa_supplicant](https://hostap.epitest.fi/wpa_supplicant/) and the native wifi setup. This has the advantage to be more robust against failure. In order to do that, the Wifi interface can be added to /etc/network/interfaces, this way: ``` auto wlan0 iface wlan0 inet static address 192.168.1.2 netmask 255.255.255.0 wpa-conf /path/to/wifi.conf #this should be replaced by the absolute location of wifi.conf ``` And the related wifi.conf ``` ctrl_interface=/var/run/wpa_supplicant ctrl_interface_group=0 ap_scan=1 network={ ssid="myssid" #this should be replaced by your ssid scan_ssid=1 key_mgmt=NONE wep_key0=1234567890 #this should be replaced by your WEP key wep_tx_keyidx=0 } ``` In this example, static IPs and WEP encryption have been used. DHCP and other encryption can be obviously used by following the documentation both of the linux native network setup and of [wpa_supplicant](https://hostap.epitest.fi/wpa_supplicant/). ### Network performance Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Network_performance To test the network performance you could use the *iperf* tool installed on the system. In the server side you must issue the following command (either for TCP or UDP testing), after which the server machine is listening for incoming data: ``` iperf -s [TCP] iperf -s -u [UDP] ``` In the client side you must type: ``` iperf -c SERVER-IP [TCP] iperf -c SERBER-IP -u -b 50000000 [UDP] ``` Where *SERVER-IP* must be changed accordingly to the network configuration. ## Package manager Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Package_manager If you have an internet connection up and running you can update and install easily new packages with *opkg*. Some of the useful operations you could do are: - update repositories: `opkg update` - update installed packages and kernel; pay attention that the camera driver is based on the provided kernel and upgrading it will prevent the use of the camera: `opkg upgrade` - list of software currently installed on the machine: `opkg list_installed` - install a new package (perl in the example): `opkg install perl` - remove a pacakge (perl in the example): `opkg remove perl` - list of all packages available to be installed: `opkg list` ### opkg update failed Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#opkg_update_failed If you get errors on reaching the default repo sources you can try changing them by following these steps: 1. make a copy of the current repo: `mv /etc/opkg/base-feed.conf /dest-dir` 2. add the new repo: `echo 'src/gz base https://feeds.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base' > /etc/opkg/base-feed.conf` 3. opkg update The procedure shows how to change the `base` repo, the same need to be done for all others repos. ## USB ports Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#USB_ports The e-puck extension board for the Gumstix Overo COM comes with two USB interfaces called USB host and USB otg. If you try inserting devices that require more energy than the one permitted on the otg, the device will not be enabled automatically. In these cases you can use the three scripts *usbup*, *usbdown* and *usbenable* to respectively power up, power down and enable the USB device; they're placed under /home/root/scripts. These scripts are intended for primary use with the USB otg port, even if they're suitable for both ports (otg and host). - *./usbup otg* (or *./usbup host*): power on the usb device - *./usbdown otg* (or *./usbdown host*): power off the usb device - *./usbenable otg* (or *./usbenable host*): activate the usb device (now is in the usb device list) ## Demos Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Demos A specific firmware must be charged on the e-puck to run the Gumstix Overo linked demos, refer to section [E-puck firmware](https://www.gctronic.com/doc/index.php/Overo_Extension#E-puck_firmware). ### Serial test on the Gumstix Overo COM Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Serial_test_on_the_Gumstix_Overo_COM This small program read and write from a serial port (non-canonical mode). For more information on the usage refers to [sertest](https://docwiki.gumstix.org/index.php?title=Sample_code/C/Serial) ([sertest sources](https://projects.gctronic.com/Gumstix/sertest.tar.gz)). It's placed under /home/root/demos/gumstix-common, and it's called *sertest*. ### Advanced sercom Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Advanced_sercom Once the new firmware is running on the e-puck, the selector must be set in position 10 to run the advanced sercom for the Gumstix Overo. Now you can type (after being in /home/root/demos/gumstix-common) *./sertest -p /dev/ttyS0 -b 230400* (or simply *./ser+ENTER*) to enter the e-puck menu in console mode; for a list of all available commands type *h+ENTER*. After stopping the sertest program (CTRL+C), the display may not respond correctly; to reset the display run the script *r* by simply typing *./r+ENTER*. Now the display should behave normally. For more information about the advanced sercom refer to the page [Advanced sercom protocol](https://www.gctronic.com/doc/index.php/Advanced_sercom_protocol). ### Images grabbing (camera driver) Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Images_grabbing_(camera_driver) A small application called *v4l2grab* ([v4l2grab.zip](https://projects.gctronic.com/Gumstix/v4l2grab-2buff-rev17-13.08.14.zip)) based on was used for grabbing JPEGs from V4L2 devices. In order to get an image from the e-puck camera you need to run the program typing (after being in `/home/root/demos/gumstix-common/`) `./v4l2grab -o image.jpg`. The application communicates also with the robot through the serial line to know the camera orientation and rotates the image automatically in case the camera is rotated (refer to section [e-puck camera](https://www.gctronic.com/doc/index.php/E-Puck#Camera) for more information on camera orientation). For more information on the options available refer to the help by typing`./v4l2grab -h`. ### Images transfer (camera driver) Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Images_transfer_(camera_driver) This demo is divided in two parts: one running on the e-puck extension board for the Gumstix Overo COM that continuously request images to the e-puck camera and transfers them over UDP, and the other running on a PC that acts as a server and is listening for the images visualizing them as soon as they are available. A network link must be established between the two in order to run this demo; for more information on how to configure the network refer to the section [Wireless setup](https://www.gctronic.com/doc/index.php/Overo_Extension#Wireless_setup). First of all you need to start the server ([Receiver QT project](https://projects.gctronic.com/Gumstix/Receiver.zip)). The application is a Qt project, so the compilation may be handled easily with [Qt Creator](https://wiki.qt.io/Category:Tools::QtCreator); alternatively [qmake](https://doc.qt.io/qt-5/qmake-manual.html) can be used. The usage is very simple: the server listening port and the protocol (only UDP available at the moment) must be selected first, then click on the button *Connect*; at this moment the application is waiting images. On the e-puck extension board side, you need to run the program typing (after being in /home/root/demos) *./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0*. *SERVER_IP* is the address of the PC and *SERVER_PORT* should be the same as configured when the receiver was started. The *f* option indicates the format (in this case RGB) and *t* indicates the transfer mode (0=UDP, 1=TCP). For more information on the options available refer to *./v4l2grab-send -h*. The sources for the sender, that is an extension of the *v4l2grab* application, could be found in the following link [v4l2grab-send.zip](https://projects.gctronic.com/Gumstix/v4l2grab-send.zip); in order to compile the application the *Makefile* must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to ). ### Music player Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Music_player This isn't really a demo, it's only one of the possible way on how to listen something from the extension module. The system comes with a tool called [mplayer](https://www.mplayerhq.hu/) that supports many multimedia formats. You can use it to play for example an mp3 file in this way: ``` mplayer file.mp3 ``` You can then adjust the volume with either the *alsamixer* graphical tool (adjusting DAC2 control) or using the command line tool *amixer*; the following command can be used for instance to set the volume to 80%: ``` amixer set 'DAC2 Analog' 80% ``` ## File transfer Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#File_transfer ### ssh Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#ssh The e-puck extension board for the Gumstix Overo COM supports ssh connections through dropbear (small SSH 2 server and client) that is installed on the system. To exchange file between the module and the PC, the *scp* tool (secure copy) will be used; the general command is the following: ``` scp user@ip:path-to-file file-name ``` As an example of transfer a file from the PC to the extension, let the PC user be *stefano* and its IP be 192.168.1.10, then the command will be: ``` scp stefano@192.168.1.10:/home/stefano/file-to-send prova ``` The file *file-to-send* will be renamed in *prova* and placed in the current directory. If you are working in Windows you can use [WinSCP](https://winscp.net) to exchange data between the robot and the computer. ### zmodem Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#zmodem The following instructions to exchange data between the extension and the computer refer to *minicom* as the terminal. If you want to receive a file, that is transfer a file from the PC to the e-puck extension board for the Gumstix Overo COM, you need to follow these steps: 1. open a terminal window with minicom; now you access the linux system in console mode 2. type *lrz* 3. press *CTRL+A* and then *S* 4. select *zmodem* and navigate to find the file you want to tranfer 5. select the file with the *SPACEBAR* and then press *ENTER* to start the transfer 6. when transfer is complete press *ENTER* once more to come back to the command line For more information type *lrz -h*. If you want to send a file, that is transfer a file from the e-puck extension board to the PC, you need to follow these steps: 1. open a terminal window with minicom; now you access the linux system in console mode 2. type *lsz file-name*, where *file-name* is the file you want to transfer 3. when transfer is complete press *ENTER* to return to the command line The file will be placed in the directory where minicom is started. For more information type *lsz -h*. ## Extension LEDs Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Extension_LEDs The e-puck extension board for the Gumstix Overo COM comprises 8 new small leds that can be turned on/off easily from the file system in this way: ``` echo 1 > /sys/class/gpio/gpio7x/value [turn on] echo 0 > /sys/class/gpio/gpio7x/value [turn off] ``` where x ranges from 0 to 7. For more information on gpio refer to the section [GPIO - pins mode](https://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode). ## File system image Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#File_system_image You can download the entire system running on the micro sd released with the e-puck extension board from the following links: [file system](https://projects.gctronic.com/Gumstix/epuck-overo-e2fs-12.08.14.tar.gz) and [FAT](https://projects.gctronic.com/Gumstix/epuck-overo-fat-30.03.15.tar.gz) (with camera driver 1.3). In order to prepare the micro sd you can use a script ([prepareMicroSD.sh](https://projects.gctronic.com/Gumstix/prepareMicroSD.sh)), in which you need only to specify where to find the two previously downloaded files and run it (*./prepareMicroSD.sh /path/to/dev*) to have your micro sd ready to be used. Alternatively you can have a look the gumstix documentation on how to [create a bootable microsd card](https://www.gumstix.com/support/getting-started/create-bootable-microsd-card/). If you experience problems in booting from mmc enter u-boot and issue the following command: ``` nand erase 240000 20000 reset ``` Moreover if you need you can find pre-built images for the Gumstix Overo in the following link: . ### Sources Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Sources The complete kernel sources (comprising the camera driver) can be downloaded from the following link [gctronic-ti-psp-omap-2.6.32-12.08.14.zip](https://projects.gctronic.com/Gumstix/gctronic-ti-psp-omap-2.6.32-12.08.14.zip) if you want to try to build it your own (anyway you don't need to do it because the released micro SD is ready to run with this system). The system is based on: - sakoman's pre-built file system image - [ti-psp-2.6.32 kernel](https://arago-project.org/git/people/?p=sriram/ti-psp-omap.git;a=summary) ### Camera driver Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Camera_driver The driver of the camera is open-source, you can download the code in the section [kernel source](https://www.gctronic.com/doc/index.php/Overo_Extension#Sources). The driver is located in `/ti-psp-omap/drivers/media/video/po6030cam.c`; related ISP code is located in `/ti-psp-omap/drivers/media/video/isp`. #### Release notes Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Release_notes : 1.0 - support for PO6030 camera (front e-puck camera or camera of omnicam module version 1) - support for RGB565 output format - only 640x480 resolution images : 1.1 - added support for PO3030 camera - added support for YUV422 output format - brightness, contrast, saturation, auto-white balance, red gain, blue gain controls available : 1.2 - exposure control available - support for 480x480 color and greyscale images : 1.3 - added support for PO8030 camera #### System update Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#System_update In order to update the system released in the micro sd with the new driver you need to download the kernel modules from [linux-2.6.32.tar.gz](https://projects.gctronic.com/Gumstix/driver-update/1.3/linux-2.6.32.tar.gz) and the kernel image from [uImage](https://projects.gctronic.com/Gumstix/driver-update/1.3/uImage). Then: 1. insert the micro sd in the computer; two partitions will be recognized 2. copy the kernel image (uImage) in the FAT partition 3. extract the kernel modules in the second partition: 1. cd path/to/partition 2. sudo tar zxvf path/to/kernel-modules 4. unmount the micro sd from the computer and insert it in the extension; at first boot type *depmod -a* and reboot ## Daemon Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Daemon It can be useful to start a daemon at the end of the boot process in order to run your own program at the start up of the e-puck (when the console mode won't be accessible). This can be done by placing your program executable into */etc/init.d* and then: ``` cp /path/to/your/executable /usr/sbin/mainProgram cd /etc/init.d update-rc.d mainProgram defaults 99 ``` The daemon can be removed by removing these files: ``` rm /etc/rc*/*mainProgram* ``` Remember to give execution permission to the program by typing `chmod +x mainProgram`. # Hardware Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Hardware The following figure shows the main components offered by the e-puck extension for the Gumstix Overo COM and their interconnection with the e-puck robot and the Gumstix Overo COM. ![Gumstix-schema.jpg](https://www.gctronic.com/doc/images/b/be/Gumstix-schema.jpg) In particular there are: - a Gumstix Overo COMs: compatible with all Gumstix Overo COM models. The communication between the Gumstix Overo COM (OMAP 35xx) and the e-puck (dsPIC) is handled with a serial line at 230400 baud - a mini-usb connector (console) used to enter the linux system through a terminal - one usb otg and one usb host: these two connectors are really useful to connect whatever peripheral you need, like a WiFi dongle or simply a pen drive to extend the memory - a speaker ([speaker specification](https://projects.gctronic.com/Gumstix/datasheet-speaker.pdf)): with Linux running on the Gumstix Overo COM, it's really easy play any audio format you need or implement a speech synthesizer. If the user prefer to have the speaker on the extension linked to the e-puck processor, it can simply be done changing two small resistors - 8 LEDs: have you ever seen a board without leds?! Anyway they are completely controllable through GPIO lines (gpio70-gpio77), for detailed information refer to section [GPIO - pins mode](https://www.gctronic.com/doc/index.php/Overo_Extension#GPIO_-_pins_mode) - an I2C connector (@5 V) - a rotary selector: one could choose what program is running on the e-puck based on the selector position - 2 long range infrared proximity sensors ([long range specification](https://projects.gctronic.com/Gumstix/datasheet-long-range.pdf)) - the PixelPlus PO6030 camera remains mounted on the robot, but you could receive image from it by using the OMAP ISP (Camera Interface Subsystem); this way we can receive up to 18 frames per second (VGA color images) The following figure illustrates where the components are physically placed on the e-puck extension board for the Gumstix Overo COM. ![Gumstix-schema2.jpg](https://www.gctronic.com/doc/images/6/6a/Gumstix-schema2.jpg) ## Electrical schema Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Electrical_schema The circuit diagram of the e-puck extension for Gumstix Overo COM is available to the community on the following link [electrical schema](https://projects.gctronic.com/Gumstix/GC_EXT5_V3.pdf). ## Long range proximity sensors Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Long_range_proximity_sensors The following chart illustrates the long range proximity sensors response towards a white surface. These results should be considered indicative. ![IR-characterization.jpg](https://www.gctronic.com/doc/images/4/47/IR-characterization.jpg) A zoom in the bigger distances shows that the values returned from the sensors are still usable to react to obstacles. ## WiFi dongle Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#WiFi_dongle ### Zyxel Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Zyxel The WiFi dongle shipped with the extension board for the Gumstix Overo COM is a ZyXEL NWD271N USB adapter, 802.11n compatible. It's based on an Atheros chipset, for more infromation about the linux driver visit the following site . The measured throughput with the e-puck extension and provided wifi dongle is **20 Mb/s**. The consumption of the wifi dongle is 100 mA in standby and 300 mA when active. ### Edimax Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Edimax A new WiFi dongle is shipped starting from January 2012, it is the Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu). The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it: 1. turn on the robot and login with `user=root, password=root` 2. only needed if the wifi dongle is connected to the USB OTG: type `./scripts/gumstix-common/usbenable otg`. Don't worry about the warning `usb 1-1: new config #1 exceeds power limit by 400mA` 3. type `insmod 8192cu.ko` (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created 4. type `ifconfig wlanX up` (where X is a number) to turn on the device; now the wifi can be configured and used normally The following figures show how the device is mounted on the extension: on the left the WiFi dongle is connected to the USB HOST connector (pay attention to the position on the connector), on the right the WiFi dongle is connected to the USB OTG (this is needed when using an [omnivsion extension](https://www.gctronic.com/doc/index.php/Omnivision_Module_V2)): ![Gumstix-nano-wifi.jpg](https://www.gctronic.com/doc/images/0/0b/Gumstix-nano-wifi.jpg) ![edimax-otg.jpg](https://www.gctronic.com/doc/images/9/9a/edimax-otg.jpg) ## Consumption Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Consumption The consumption of the robot and extension is 300 mA; with the Zyxel wifi dongle inserted (standby) the consumption goes up to 400 mA; when the wifi dongle becomes active, the consumption reaches 700 mA. If the wifi isn't used it can be turned off completely using the usb scripts . Two different tests were performed to provide an estimation of the duration of the battery: 1. e-puck and gumstix active (gumstix sends commands via serial to robot; movement every 3s lasting 1s at 30% of maximum speed): **3h and 30 minutes** 2. e-puck, gumstix and wifi active (same as above, moreover wifi active all the time with continuous ping): **1h and 25 minutes** ## External power Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#External_power In the package you'll find also an external power adapter that will be useful during development of your applications. As power supply you could use the one of the e-puck battery charger. The following figure shows the power supply cable, the external power cable and the extension. ![External-power.jpg](https://www.gctronic.com/doc/images/e/e1/External-power.jpg) You need to simply attach the power supply in one side, and the other side of the external power cable on top of the extension (near the USB plug). Once the cable is connected a green led should turn on indicating that the extension is running. ![External-power-attached.jpg](https://www.gctronic.com/doc/images/2/25/External-power-attached.jpg) The external power cable could also be plugged in when the extension is mounted on the e-puck, but **pay attention to not turn on the robot when the external cable supplies the energy, otherwise there could be serious damages of the devices and the battery**. ## 3.3V and 5V source Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#3.3V_and_5V_source The 3.3 V comes from the e-puck robot and the 5V comes from the gumstix extension. The gumstix extension can be used alone (without the robot attached to it) but some things are related to the 3.3 V thus without the robot connected they will not work; an example are the RGB leds of the omnivion module, that need the robot to be connected to the extension in order to be used. # Software Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Software ## E-puck firmware Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#E-puck_firmware Refers to the section [E-Puck Standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware) for the firmware that need to be uploaded to the robot. Essentially in this firmware a new version of the *advanced sercom* is included (selector position 10) in which the bluetooth communication is replaced by the serial line communication, running at 230400 between robot and gumstix. Moreover the I2C is disabled temporary from the dsPIC side (the dsPIC cannot communicate through I2C) in order to avoid conflicts. As a last note, the body led and front led aren't anymore usable with the extension due to the two extra long range proximity sensors and for power saving purposes the motors are configured to the minimum energy consumption during movement. The values of the two extra proximity sensors can be retrieved with the command *N* in the *advanced sercom* (selector position 10); the last two values returned by the command refer to these proximity sensors (the others values refer to the proximity sensors mounted on the e-puck as usual). ### Project building Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Project_building Refer to section [Project building](https://www.gctronic.com/doc/index.php/E-Puck#Project_building) for information on how to build the project for the e-puck firmware. ## Cross compilation Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Cross_compilation If you want to develop some applications that will run on the gumstix you need to firstly download the toolchain. If you're using Ubuntu you can simply type `sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi` to install the required toolchain (have a look at and for more information). Alternatively when you need to handle external dependencies is better using the toolchain integrated in OpenEmbedded (${OVEROTOP}/tmp/cross or ${OVEROTOP}/tmp/sysroots/i686-linux/usr/armv7a/bin/ with recent version) if you have it in your system. For more information refers to the [gumstix wiki](https://wiki.gumstix.org/index.php?title=Category:How_to_-_OpenEmbedded). For other linux systems you can find a toolchain in the following link (30 days trial); this toolchain is useful for small programs: 1. download the Lite Edition, you'll have a file named something like *arm-2009q3-67-arm-none-linux-gnueabi.bin* 2. open a terminal, go to the directory of the file, type *chmod +x arm-2009q3-67-arm-none-linux-gnueabi.bin*, after execute the file *./arm-2009q3-67-arm-none-linux-gnueabi.bin* to start the installation 3. follow the installation steps; you have to choose where to install the toolchain, this is the path you will specify in the makefile Once a toolchain is installed in the system the process will be simply something like this: 1. develop your application as you do normally in your developing machine 2. cross-compile in your developing machine using the tools previously downloaded 3. copy the executable in the extension's micro SD and run it You can download the [hello world example](https://projects.gctronic.com/Gumstix/helloworld.zip) containing a makefile in which you have to specify the path to the toolchain you previously installed in order to build the program; you can use it for others programs. Refer to section for some application examples. Of course you can also install the compiler directly on the embedded system and build the applications from it, but the process will take longer due to limited computational power compared to a developing machine. ### External dependencies Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#External_dependencies Some applications may require external libraries not contained within the standard toolchain package. For instance if your application depends on *libjpeg* then you need to tell the cross-compiler where to look to find this library (compiled for the target machine) otherwise your application will not be compiled. If you have OpenEmbedded installed in your system you could simply bitbake the external dependencies (in our example *bitbake jpeg*) and then compile your application. Instead if you rely on the CodeSourcery toolchain you need to follow these steps: 1. download the sources of the library 2. cross-compile the library 3. install the library (and include files) in the right places 4. compile your application ## Ground sensor Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Ground_sensor It's possible to use contemporaneously both the e-puck extension for gumstix overo and the ground sensor; in this case the camera and the ground sensor will share the same I2C bus and like the camera, also the ground sensor will not be anymore reachable from the e-puck side, but only from the overo side. The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo, thus we need to change the bus speed to 100 KHz in order to communicate with the ground sensor module; the simplest way is to set a kernel parameter in u-boot: 1. enter u-boot by pressing any key at boot start 2. type the command `setenv i2cspeed 3,100`; this init the I2C bus 3 to 100 KHz 3. type the command `setenv mmcargs setenv bootargs console=${console} i2c_bus=${i2cspeed} ${optargs} mpurate=${mpurate} vram=${vram} omapfb.mode=dvi:${dvimode} omapdss.def_disp=${defaultdisplay} root=${mmcroot} rootfstype=${mmcrootfstype}` ; basically we pass an additional parameter to the kernel that is the `i2c_bus=${i2cspeed}` 4. type the command `saveenv` to save the environment changes 5. type `boot` to start booting Pay attention that all the peripherals connected to the bus will now work at 100 KHz, thus also the e-puck camera and the LSM330 (accelerometer + gyroscope) present with e-puck HwRev 1.3. If you want to set back the bus speed to 400 KHz you need to follow steps 2-4, by setting the `i2cspeed` u-boot environment variable with `setenv i2cspeed 3,400`. Communicating with the ground sensor is as easy as open a device and reading from it; a source code example can be found in the following link . You will find this application example in the `/home/root/demos/gumstix-common` directory; start it by executing `./i2c_groundsensors` and the sensors values will be displayed in the terminal. Make sure that you have installed the last system update otherwise you'll encounter some problems. You can find more information about the I2C and gumstix in the following links: - ## OpenCV Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#OpenCV The Open Computer Vision Library has more than 500 algorithms, documentation and sample code for real time computer vision; you can download it from , and find information about it from the official wiki . The released system comes with OpenCV version 2.0.0 pre-installed and a demo that shows an example of what can be performed with this library. The demo let the robot follow a black filled circle placed in front of it; if the circle is moved right or left the robot turns consequently. The following figure shows an example of the circle detected by the robot: ![circle-detection.jpg](https://www.gctronic.com/doc/images/e/e6/circle-detection.jpg) In order to start the demo follows these steps: 1. turn on the robot with the gumstix extension and login as *root* with password *root* 2. go to the directory */home/root/demos/gumstix-common* and execute *./v4l2grab-opencv -o image.jpg* 3. the demo should return the number of circles detected and save a resulting image showing the circles detected if any Alternatively you can use the following script, that launches the demo and send it through serial (using zmodem) iteratively: ``` #!/bin/bash while true; do ./v4l2grab-opencv -o image.jpg -q 50 lsz img1.jpg done ``` The source code can be downloaded from the following link [v4l2grab-opencv.zip](https://projects.gctronic.com/Gumstix/v4l2grab-opencv-rev15.zip). ## Accelerometer and gyroscope (e-puck HWRev 1.3) Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Accelerometer_and_gyroscope_(e-puck_HWRev_1.3) When the e-puck extension for gumstix overo is mounted on the e-puck hardware revision 1.3 the same I2C bus is shared by all the devices (camera, accelerometer, gyroscope) and the overo; since there is only one master (the overo) these devices will not be anymore reachable from the e-puck side. The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo and this is fine to work with the accelerometer and gyroscope. Communicating with the accelerometer and gyroscope is as easy as open a device and reading from it; a source code example can be found in the following link [i2c_lsm330.c](https://projects.gctronic.com/Gumstix/i2c_lsm330.c). You will find this application example in the `/home/root/demos/gumstix-common` directory; start it by executing `./i2c_lsm330`, type `0` to get the accelerometer values or `1` to get the gyroscope values printed on the terminal. The values of the accelerometer and gyroscope read from the gumstix through the I2C are 16 bits (1g = 16384); beware that regarding the accelerometer values there is a mismatch between the values read from the gumstix through I2C and the values read from the [advanced sercom protocol](http://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol) through Bluetooth, the latter are converted in the firmware to maintain compatibility with older e-puck hardware revisions. The orientation of the accelerometer for the values read from the gumstix through the I2C is also different from the one used in the e-puck firmware; the orientation is shown below, the x axis points forward, the y axis points left and the z axis points upward: ![epuck-acc-directions1.3.png](https://www.gctronic.com/doc/images/0/08/epuck-acc-directions1.3.png) ### Python Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Python An example in python is available from the following link [i2c_lsm330.py](https://projects.gctronic.com/Gumstix/i2c_lsm330.py). In order to run the script, some additional dependencies need to be installed in the system, follow these steps: 1. configure the network in order to have internet access 2. update the package manager repos: 1. `echo 'src/gz base https://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/base/' > /etc/opkg/base-feed.conf` 2. `echo 'src/gz python https://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/python/' > /etc/opkg/python-feed.conf` 3. add `arch armv7a-vfp-neon 45` to the file `/etc/opkg/arch.conf` 4. `opkg update` 5. `opkg -force-overwrite install python-smbus` 6. optionally you can also remove some warnings related to the update by running the following script [remove-warnings.sh](https://projects.gctronic.com/omnicam/remove-warnings.sh) Once the system is configured you can start the script by executing `python i2c_lsm330.py`, type `0` to get the accelerometer values or `1` to get the gyroscope values printed on the terminal. ## ROS Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#ROS We tested ROS on the gumstix extension with the Yocto system. Follow these steps to get ROS running on the e-puck extension: : 1. prepare a micro sd following the instructions from : 2. download the file system and fat from the following links: [yocto-ros-3.5.7-FAT.tar.gz](https://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-FAT.tar.gz), [yocto-ros-3.5.7-rootfs.tar.gz](https://projects.gctronic.com/Gumstix/yocto-ros-3.5.7-rootfs.tar.gz) : 3. login with user=root and empty password : 4. issue the following commands to enable the WiFi dongle: : `echo host > /sys/bus/platform/devices/musb-hdrc/mode` : `echo -n 1 > /sys/bus/usb/devices/2-1/bConfigurationValue` : 5. follow the instructions from to run a demo ## Python Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Python_2 In order to install python 2.6 on the e-puck extension for Gumstix follow these steps: 1. download the package [python-gumstix.tar.gz](https://projects.gctronic.com/Gumstix/python-gumstix.tar.gz) 2. extract the package: `tar -zxvf python-gumstix.tar.gz` 3. remove the micro sd from the robot and connect it to your computer; two partitions will be opened, one called `FAT` and the other called `overo` containing the file system (the partitions name could be a little different) 4. copy the content of the decompressed file to the same position in the `overo` partition: 1. `sudo cp -R /python-gumstix/usr/lib/* /overo/usr/lib` 2. `sudo cp /python-gumstix/usr/bin/* /overo/usr/bin` Alternatively if you have access to internet you can use the package manager: 1. `opkg install python` 2. `opkg install python-modules` 3. `opkg install python-pyserial` In order to test your python installation you can download the following script [printhelp.py](https://projects.gctronic.com/Gumstix/printhelp.py); execute it by typing `python printhelp.py`. This is a minimal example of serial communication in python that let the gumstix communicate with the robot; basically it opens a serial connection with the robot and ask the available commands that you can use to get sensors data and change actuators state. Another example is available here [getprox.py](https://projects.gctronic.com/Gumstix/getprox.py); in this script the values of the proximities are requested to the robot and printed to the console. The data are requested in binary format, for more information about the communication protocol refer to the section [advanced sercom](https://www.gctronic.com/doc/index.php/Overo_Extension#Advanced_sercom). ## e-puck2 Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#e-puck2 When the gumstix extension is mounted on the e-puck2 robot, the same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the overo; since there is only one master (the overo), these devices will not be anymore reachable directly from the e-puck2 main microcontroller that will act instead as I2C slave. It's worth notice that with e-puck2, the I2C bus is used also for the communication between the robot and the gumstix (to receive sensors and set the actuators); with e-puck1.x a serial channel was used instead for the communication between the robot and the gumstix. ### Firmware Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Firmware A special firmware must be uploaded to the e-puck2 robot in order to let the main processor act as I2C slave. In this firmware the main processor receive commands from the gumstix extension to actuate the motors and leds and give back the sensors values (proximity, microphones, selector, motors steps, tv remote) to the gumstix. When using this firmware the body led and front led aren't usable; the two extra long range proximity sensors mounted on the gumstix extension are also not available with e-puck2. The selector on the robot must be in position 10. Be sure that the selector on the robot is in position 10, because the selector on the gumstix extension is not connected to the e-puck2 robot. The pre-compiled firmware can be downloaded from [e-puck2_main-processor_extension.elf (07.06.19)](https://projects.gctronic.com/epuck2/gumstix/e-puck2_main-processor_extension_b346841_07.06.19.elf). If you want to have a look a the source code, you can clone the git repository by issueing the command `git clone -b gumstix --recursive https://github.com/e-puck2/e-puck2_main-processor.git`. An example showing how to exchange data between the robot and the gumstix extension is called `i2c_e-puck2` and can be found in the directory `/home/root/demos/e-puck2/`. Simply run the program by issueing `./i2c_e-puck2`; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz. The code is available from [i2c_e-puck2.zip](https://projects.gctronic.com/epuck2/gumstix/i2c_e-puck2.zip). #### Packet format Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Packet_format Gumstix to robot packet format, 20 bytes payload (the number in the parenthesis expresses the bytes for each field): | Left speed (2) | Right speed (2) | Speaker (1) | LED1, LED3, LED5, LED7 (1) | LED2 RGB (3) | LED4 RGB (3) | LED6 RGB (3) | LED8 RGB (3) | Settings (1) | Checksum (1) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | - Left, right speed: [-2000 ... 2000] - Speaker id: [0, 1, 2] - LEDs on/off flag: bit0 for LED1, bit1 for LED3, bit2 for LED5, bit3 for LED7 - RGB LEDs: [0 (off) ... 100 (max)] - Settings: - bit0: 1=calibrate IR proximity sensors - bit1: 0=disable onboard obstacle avoidance; 1=enable onboard obstacle avoidance (not implemented yet) - bit2: 0=set motors speed; 1=set motors steps (position) - Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..18) Robot to gumstix packet format, 47 bytes payload (the number in the parenthesis expresses the bytes for each field): | 8 x Prox (16) | 8 x Ambient (16) | 4 x Mic (8) | Selector + button (1) | Left steps (2) | Right steps (2) | TV remote (1) | Checksum | | --- | --- | --- | --- | --- | --- | --- | --- | - Selector + button: selector values represented by 4 least significant bits (bit0, bit1, bit2, bit3); button state is in bit4 (1=pressed, 0=not pressed) - Checksum: Longitudinal Redundancy Check (XOR of the bytes 0..45) ### I2C devices Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#I2C_devices #### Ground sensor Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Ground_sensor_2 Refer to section [Ground_sensor](https://www.gctronic.com/doc/index.php?title=Overo_Extension#Ground_sensor). #### IMU Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#IMU An example showing how to read data from the IMU is called `i2c_mpu9250` and can be found in the directory `/home/root/demos/e-puck2/`. Simply run the program by issueing `./i2c_mpu9250` and then choose whether to get data from the accelerometer or gyroscope; this demo will print the sensors data on the terminal. The code is available from [i2c_mpu9250.zip](https://projects.gctronic.com/epuck2/gumstix/i2c_mpu9250.zip). #### Distance sensor Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Distance_sensor # Configuration Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Configuration ## Graphic mode Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Graphic_mode The resolution of the monitor can be modified in the u-boot command line, that can be entered at booting. In the u-boot command line type: ``` setenv dvimode "1280x720MR-16@60" saveenv boot ``` Now the configuration is saved in the flash; if your monitor doesn't support the current resolution, repeat the procedure with a different configuration (change the resolution numbers). Note that the DVI Controller ([TFP410](https://projects.gctronic.com/Gumstix/tfp410.pdf)) mounted on Summit and Tobi supports resolutions from VGA (640x480) to UXGA (1600x1200). Useful files to look at: - linux_source_home/drivers/video/modedb.c: explains what's the mean of the dvimode names - linux_source_home/Documentation/fb/viafb.modes: list of available modes usable with the *fbset* tool ## GPIO - pins mode Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#GPIO_-_pins_mode There are three different ways to read GPIO lines: : 1. Kernel space: GPIO lines handled through an API : 2. User space: : 2.1. standard filesystem commands like *cat* and *echo* (static configuration) : 2.2 direct physical memory access using *devmem2* or with a C application (dynamic configuration) Afterward will be explained how to handle the GPIO lines on the Gumstix Overo COM in all different methods; information about this topic were found from various sites, but especially from the [mailing list](https://sourceforge.net/p/gumstix/mailman/). Moreover for a general howto on GPIO refers to the linux documentation ["KernelSrc/Documentation/gpio.txt"](https://www.kernel.org/doc/Documentation/gpio/gpio.txt). ### Kernel space Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Kernel_space ### User space Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#User_space #### Static configuration Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Static_configuration Each of the microprocessor IO pins can be configured to work in different ways for different purposes; in case we desire a certain pin to be configured as a gpio line, we must modify the function assigned to that pin (mux configuration) in the U-Boot board configuration file, that for the Gumstix Overo COM is located at "U-BootSrc/board/overo/overo.h". To know which modes are available for the pins consult the chapter *7-System Control Module* (more specifically *7.4.4-Pad Functional Multiplexing and Configuration*) in the [OMAP35x TRM](https://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf). Assume we want to have the possibility to switch on and off a led attached to the line gpio70; in order to accomplish this task, we need to follow these steps: : **1.** Modify the board configuration file "overo.h" specifying that the pin has to behave as a gpio line: ``` MUX_VAL(CP(DSS_DATA0), (IDIS | PTU | DIS | M4)) /*DSS_DATA0 => GPIO70*/\ ``` : - IDIS = input disable, namely output pin - PTU = pull type up, but could be also PTD (pull type down) because of the third parameter - DIS = disable pull type up/down - M4 = mode 4 (gpio) : This give us a GPIO pin that is output and not pulled up or down. : **2.** Build U-Boot and place the generated *u-boot.bin* image in the flash ([Writing images to onboard nand](https://www.gumstix.org/how-to/70-writing-images-to-flash.html)) or in a micro sd card ([Creating a bootable microSD card](https://www.gumstix.org/create-a-bootable-microsd-card.html)) : **3.** After login, we can see all the GPIO pins that have been exported by the kernel to userspace in the /sys/class/gpio/ directory. In order to access the gpio70 line, we should export it first, by typing: ``` echo "70" > /sys/class/gpio/export ``` : Now the following line is active /sys/class/gpio/gpio70. : **4.** At this point we must configure the direction of the exported line and set a logical value (1 or 0) to that line, we can do that by typing: ``` echo "high" > /sys/class/gpio/gpio70/direction ``` : This command set the pin in output and give it a value of 1. : **5.** Finally we can switch on or off the led, by setting the value of the gpio line: ``` echo "value" > /sys/class/gpio/gpio70/value ``` : Where value=1 means switch on, and value=0 means switch off. In order to automate the process of creating a gpio line accessible through "/sys/class/gpio/", we must modify the board configuration file in the kernel source; this file can be found in "KernelSrc/arch/arm/mach-omap2/board-overo.c" (and related definitions in "KernelSrc/arch/arm/plat-omap/include/mach/board-overo.h"). These files must contain instructions to initialize the gpio line that we want to export in user space and set their direction and initial value. Consider the previous example in which we would like to control a led with the gpio70 pin; for this purpose the following instructions must be added in the board configuration file *board.overo.c* within the *overo_init* function: ``` if ((gpio_request(70, "OVERO_GPIO_DD00") == 0) && (gpio_direction_output(70, 1) == 0)) { gpio_export(70, 0); gpio_set_value(70, 1); //not really needed, the initial output value is set with gpio_direction_output } else { printk(KERN_ERR "could not obtain gpio for OVERO_GPIO_DD00\n"); } ``` After this modification we need to build the kernel and copy it to the flash or micro sd card, and after login we will have the /sys/class/gpio/gpio70 line automatically active. For more information on the previous snippet code refers to ["KernelSrc/Documentation/gpio.txt"](https://www.kernel.org/doc/Documentation/gpio/gpio.txt). #### Dynamic configuration Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Dynamic_configuration If you aren't familiar with modifying and building U-Boot and kernel, you would probably choose to modify the pin configuration at runtime, without the need to touch any board configuration file. The only way to change the configuration of the pins is to access directly the physical memory of the microprocessor, in particular its configuration registers. The utility [devmem2](https://buildroot.uclibc.org/downloads/sources/devmem2.c) allows for easy reading and writing of the memory; after building and installing this utility on the Gumstix Overo COM, you are ready to change the ports functionality. Consider the previous example of the led on gpio70, to change the pin mode to gpio you must issue the following command: ``` devmem2 0x480020DC b 0x14 ``` *0x480020DC* is the address of the register we want to write to and can be found observing the table 7-4 on chapter 7.4.4.3 of the [OMAP35x TRM](https://projects.gctronic.com/Gumstix/omap35xx-TRM.pdf); *b* means we want to write a byte to that register and finally *0x14* is the value we want to write. The pin mode depends on the last three bits, in this case the mode is set to 4, namely the pin is a gpio. From now on we can follow steps from 3 to 5 of the previous chapter to switch on and off the led. An example on modifying the pins configuration through the C programming language can be found in the following link [gpregs.c](https://docwiki.gumstix.org/index.php?title=Sample_code/C/gpregs). ### Useful links/resources Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Useful_links/resources For more information on GPIO usage, have a look at the following links: - ["KernelSrc/Documentation/gpio.txt"](https://www.kernel.org/doc/Documentation/gpio/gpio.txt) - [gumstix mailing list](https://sourceforge.net/p/gumstix/mailman/) - - - - - - # Webots interface Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Webots_interface Nikola Velickovic developed an interface with the Webots simulator during his MSc Thesis in 2012. His report is available [here](https://projects.gctronic.com/Gumstix/MScThesis_NikolaVelickovic_2012.tar.gz). His files are available [here](https://projects.gctronic.com/Gumstix/ThesisProjectFiles(30.12.2011).tar.gz). # FAQ Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#FAQ **1. Why the serial communication between Gumstix Overo COM and the robot doesn't work?** There could be three possible reasons for the communication problem: - selector position incorrect: you need to be sure that the robot selector is in position 10 in order to start the right software on the robot side - wrong device: the serial device is identified as /dev/ttyS0 in the linux machine, be sure to use it when you're using for example the sertest demo ("./sertest -p /dev/ttyS0 -b 230400") - battery discharged: somebody could be deceived from the fact that the linux console is still usable, but if the orange led on the robot indicating the low battery level is turned on, then the robot will not be able anymore to respond, even if you are working on the linux console; either change or charge your battery and try again. **2. I am able to communicate with the robot through the serial line, but seems that I receive only garbage, why?** Probably the baudrate isn't correct; with the robot selector in position 10 you need to configure the baudrate at 230400 (e.g "./sertest -p /dev/ttyS0 -b 230400"). **3. Can I use bluetooth to connect to the robot? Can I use the [monitor](https://www.gctronic.com/doc/index.php/E-Puck#PC_interface)?** Yes, you can connect to the robot with bluetooth and play with the monitor interface placing the selector in position 3. You'll experience some errors on the values displayed on the monitor due to the additional two long IR sensors that aren't considered when the interface was developed; moreover you will not be able to receive images from the robot. **4. Why I cannot connect to the robot through SSH?** - first of all be sure that the network is well configured (you can i.e. ping the robot sucessfully) - check the SSH daemon is running typing: *ps -ef | grep sshd*; if it is not running then setup the SSH daemon to run automatically at boot; for this purpose you can type *update-rc.d sshd defaults 99*. This command will install the links to *sshd* into rc*.d dirs. See the man page for more informations. - if the SSH server is running, but you get an error like "ssh: connect to host 192.168.1.2 port 22: Connection refused" when trying to connect, you can check whether a user and group sshd are created. If not, add the following entries in the system: ``` /etc/group:sshd:*:27: /etc/passwd:sshd:*:27:27:sshd privsep:/var/empty:/sbin/nologin ``` **5. How to auto-login and execute applications automatically at startup?** Refers to the instructions explained here . **6. Are micro SDHC supported?** Yes they are supported. # Videos Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Videos [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) Comments: This e-puck is on an exploration, his camera sends continuous image to the computer with a wifi connection. # Useful links Link: https://www.gctronic.com/doc/index.php?title=Overo_Extension#Useful_links ======================================================================== TOPIC: elisa-3 Documentation for the Elisa-3 robot. Elisa-3 is the successor of the older Elisa robot: do not apply Elisa information to Elisa-3. ======================================================================== # Elisa-3 Source: https://www.gctronic.com/doc/index.php?title=Elisa-3 Last edited: 2026-07-22T13:32:24Z # Overview Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Overview ![Elisa3_and_charger.JPG](https://www.gctronic.com/doc/images/b/b4/Elisa3_and_charger.JPG) Elisa-3 is an evolution of the [Elisa](https://www.gctronic.com/doc/index.php/Elisa) robot based on a different microcontroller and including a comprehensive set of sensors: - [Atmel 2560](https://projects.gctronic.com/elisa3/atmega640-1280-1281-2560-2561_datasheet.pdf) microcontroller (Arduino compatible) - central RGB led - 8 green leds around the robot - IRs emitters - 8 IR proximity sensors ([Vishay Semiconductors Reflective Optical Sensor](https://projects.gctronic.com/elisa3/tcrt1000.pdf)) - 4 ground sensors ([Fairchild Semiconductor Minature Reflective Object Sensor](https://projects.gctronic.com/elisa3/QRE1113-D.PDF)) - 3-axis accelerometer ([Freescale MMA7455L](https://projects.gctronic.com/elisa3/MMA7455L.pdf)) - RF radio for communication ([Nordic Semiconductor nRF24L01+](https://www.nordicsemi.com/kor/Products/2.4GHz-RF/nRF24L01P)) - micro USB connector for programming, debugging and charging - IR receiver - 2 DC motors - top light diffuser - selector The robot is able to self charge using the charger station, as shown in the previous figure. The following figure illustrates the position of the various sensors: ![Elisa3-mainComp-digital-white.png](https://www.gctronic.com/doc/images/9/99/Elisa3-mainComp-digital-white.png) ## Useful information Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Useful_information - the top light diffuser and robot are designed to lock together, but the diffuser isn't fixed and can thus be removed as desired; the top light diffuser, as the name suggests, helps the light coming from the RGB led to be smoothly spread out, moreover the strip attached around the diffuser let the robot be better detected from others robots. Once the top light diffuser is removed, pay attention not to look at the RGB led directly. In order to remove the top light diffuser simply pull up it, then to place it back on top of the robot remember to align the 3 holes in the diffuser with the 3 IRs emitters and push down carefully untill the diffuser is stable; pay attention to not apply too much force on the IRs emitters otherwise they can bend and stop working. ![Diffuser-pull-up.jpg](https://www.gctronic.com/doc/images/c/cb/Diffuser-pull-up.jpg) ![Diffuser-push-down.jpg](https://www.gctronic.com/doc/images/0/0e/Diffuser-push-down.jpg) - when the top light diffuser is fit on top of the robot, then in order to change the selector position you can use the tweezers; the selector is located near the front-left IR emitter, as shown in the following figure: ![selector-tweezers.jpg](https://www.gctronic.com/doc/images/d/d4/selector-tweezers.jpg) - if you encounter problems with the radio communication (e.g. lot of packet loss) then you can try moving the antenna that is a wire near the robot label. Place the antenna as high as possible, near the plastic top light diffuser; try placing it in the borders in order to avoid seeing a black line on the top light diffuser when the RGB led is turned on. ![Antenna-position.jpg](https://www.gctronic.com/doc/images/c/c5/Antenna-position.jpg) ![Antenna-diffuser.jpg](https://www.gctronic.com/doc/images/9/94/Antenna-diffuser.jpg) ## Robot charging Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Robot_charging The Elisa-3 can be piloted in the charger station in order to be automatically self charged; there is no need to unplug the battery for charing. The following figures shows the robot approaching the charger station; a led indicates that the robot is in charge: ![Elisa3-charger-out.jpg](https://www.gctronic.com/doc/images/e/e8/Elisa3-charger-out.jpg) ![Elisa3-charger-in.jpg](https://www.gctronic.com/doc/images/9/99/Elisa3-charger-in.jpg) The microcontroller is informed when the robot is in charge and this information is also transferred to the PC in the *flags* byte; this let the user be able to pilote the robot to the charger station and be informed when it is actually in charge. More information about the radio protocol can be found in the section [Communication](https://www.gctronic.com/doc/index.php/Elisa-3#Communication). Moreover the robot is also charged when the micro USB cable is connected to a computer; pay attention that if the USB cable is connected to a hub, this one need to be power supplied. The following video shows the Elisa-3 piloted through the radio to the charging station using the monitor application: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## Top light diffuser Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Top_light_diffuser From February 2013 onwards the Elisa-3 is equipped with a new top light diffuser designed to fit perfectly in the 3 IRs emitters of the robot. The diffuser is made of plastic (3d printed), it is more robust and it simplifies the removal and insertion. Here is an image: ![elisa3-new-case.jpg](https://www.gctronic.com/doc/images/e/e5/elisa3-new-case.jpg) # Hardware Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Hardware The following figures show the main components offered by the Elisa-3 robot and where they are physically placed: ![Elisa3.1-hw-schema-top.jpg](https://www.gctronic.com/doc/images/7/70/Elisa3.1-hw-schema-top.jpg) ![Elisa3-hw-schema-bottom3.jpg](https://www.gctronic.com/doc/images/1/1f/Elisa3-hw-schema-bottom3.jpg) ## Power autonomy Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Power_autonomy The robot is equipped with two batteries for a duration of about 3 hours at normal usage (motors run continuously, IRs and RGB leds turned on). ![Power-autonomy.jpg](https://www.gctronic.com/doc/images/9/9b/Power-autonomy.jpg) ## Detailed specifications Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Detailed_specifications | **Feature** | **Technical information** | | --- | --- | | Size, weight | 50 mm diameter, 30 mm height, 39 g | | Battery, autonomy | LiIPo rechargeable battery (2 x 130 mAh, 3.7 V). About 3 hours autonomy. Recharging time about 1h e 30. | | Processor | Atmel ATmega2560 @ 8MHz (~ 8 MIPS); 8 bit microcontroller | | Memory | RAM: 8 KB; Flash: 256 KB; EEPROM: 4 KB | | Motors | 2 DC motors with a 25:1 reduction gear; speed controlled with backEMF | | Magnetic wheels | Adesion force of about 1 N (100 g) depending on surface material and painting Wheels diamater = 9 mm Distance between wheels = 40.8 mm | | Speed | Max: 60 cm/s | | Mechanical structure | PCB, motors holder, top white plastic to diffuse light | | IR sensors | 8 infra-red sensors measuring ambient light and proximity of objects up to 6 cm; each sensor is 45° away from each other 4 ground sensors detecting the end of the viable surface (placed on the front-side of the robot) | | IR emitters | 3 IR emitters (2 on front-side, 1 on back-side of the robot) | | Accelerometer | 3D accelerometer along the X, Y and Z axis | | LEDs | 1 RGB LED in the center of the robot; 8 green LEDs around the robot | | Switch / selector | 16 position rotating switch | | Communication | Standard Serial Port (up to 38kbps) Wireless: RF 2.4 GHz; the throughput depends on number of robot: eg. 250Hz for 4 robots, 10Hz for 100 robots; up to 10 m | | Remote Control | Infra-red receiver for standard remote control commands | | Expansion bus | Optional connectors: 2 x UART, I2C, 2 x PWM, battery, ground, analog and digital voltage | | Programming | C/C++ programming with the AVR-GCC compiler ([WinAVR](https://winavr.sourceforge.net/) for Windows). Free compiler and IDE (AVR Studio / Arduino) | # Communication Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Communication ## Wireless Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Wireless The radio base-station is connected to the PC through USB and transfers data to and from the robot wirelessly. In the same way the radio chip ([nRF24L01+](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P)) mounted on the robot communicates through SPI with the microcontroller and transfers data to and from the PC wirelessly. The robot is identified by an address that is stored in the last two bytes of the microcontroller internal EEPROM; the robot firmware setup the radio module reading the address from the EEPROM. This address corresponds to the robot id written on the label placed under the robot and should not be changed. ![Elisa-communication.jpg](https://www.gctronic.com/doc/images/7/73/Elisa-communication.jpg) ### Packet format - PC to radio to robot Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Packet_format_-_PC_to_radio_to_robot The 13 bytes payload packet format is shown below (the number in the parenthesis expresses the bytes): | Command (1) | Red led (1) | Blue led (1) | Green led (1) | IR + Flags (1) | Right motor (1) | Left motor (1) | Small green leds (1) | Flags2 (1) | Reserved (1) | Remaining 4 bytes are unused | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | - Command: 0x27 = change robot state; 0x28 = goto base-station bootloader (this byte is not sent to the robot) - Red, Blue, Green leds: values from 0 (OFF) to 100 (ON max power) - IR + flags: - first two bits are dedicated to the IRs: - 0x00 => all IRs off - 0x01 => back IR on - 0x02 => front IRs on - 0x03 => all IRs on - third bit is reserved for enabling/disabling IR remote control (0=>disabled, 1=>enabled) - fourth bit is used for sleep (1 => go to sleep for 1 minute) - fifth bit is used to calibrate all sensors (proximity, ground, accelerometer) and reset odometry - sixth bit is reserved (used by radio station) - seventh bit is used for enabling/disabling onboard obstacle avoidance - eight bit is used for enabling/disabling onboard cliff avoidance - Right, Left motors: speed expressed in 1/5 of mm/s (i.e. a value of 10 means 50 mm/s); MSBit indicate direction: 1=forward, 0=backward; values from 0 to 127 - Small green leds: each bit define whether the corresponding led is turned on (1) or off (0); e.g. if bit0=1 then led0=on - Flags2: - bit0 is used for odometry calibration - remaining bits unused - Remaining bytes free to be used #### Optimized protocol Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Optimized_protocol The communication between the pc and the base-station is controlled by the master (computer) that continuously polls the slave (base-station); the polling is done once every millisecond and this is a restriction on the maximum communication throughput. To overcome this limitation we implemented an optimized protocol in which the packet sent to the base-station contains commands for four robots simultaneously; the base-station then separate the data and send them to the correct robot address. The same is applied in reception, that is the base-station is responsible of receiving the ack payloads of 4 robots (64 bytes in total) and send them to the computer. This procedure let us have a throughput 4 times faster. ### Packet format - robot to radio to PC Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Packet_format_-_robot_to_radio_to_PC The robot send back to the base-station information about all its sensors every time it receive a command; this is accomplished by using the "ack payload" feature of the radio module. Each "ack payload" is 16 bytes length and is marked with an ID that is used to know which information the robot is currently transferring. The sequence is the following (the number in the parenthesis expresses the bytes): | ID=3 (1) | Prox0 (2) | Prox1 (2) | Prox2 (2) | Prox3 (2) | Prox5 (2) | Prox6 (2) | Prox7 (2) | Flags (1) | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | | | | | | | | | | | ID=4 (1) | Prox4 (2) | Ground0 (2) | Ground1 (2) | Ground2 (2) | Ground3 (2) | AccX (2) | AccY (2) | TV remote (1) | | | | | | | | | | | | ID=5 (1) | ProxAmbient0 (2) | ProxAmbient1 (2) | ProxAmbient2 (2) | ProxAmbient3 (2) | ProxAmbient5 (2) | ProxAmbient6 (2) | ProxAmbient7 (2) | Selector (1) | | | | | | | | | | | | ID=6 (1) | ProxAmbient4 (2) | GroundAmbient0 (2) | GroundAmbient1 (2) | GroundAmbient2 (2) | GroundAmbient3 (2) | AccZ (2) | Battery (2) | Free (1) | | | | | | | | | | | | ID=7 (1) | LeftSteps (4) | RightSteps (4) | theta (2) | xpos (2) | ypos (2) | Free (1) | | | Pay attention that the base-station could return "error" codes in the first byte if the communication has problems: - 0 => transmission succeed (no ack received though) - 1 => ack received (should not be returned because if the ack is received, then the payload is read) - 2 => transfer failed Packet ID 3: - Prox* contain values from 0 to 1023, the greater the values the nearer the objects to the sensor - The *Flags* byte contains these information: - bit0: 0 = robot not in charge; 1 = robot in charge - bit1: 0 = button pressed; 1 = button not pressed - bit2: 0 = robot not charged completely; 1 = robot charged completely - the remainig bits are not used at the moment Packet ID 4: - Prox4 contains values from 0 to 1023, the greater the values the nearer the objects to the sensor - Ground* contain values from 512 to 1023, the smaller the value the darker the surface - AccX and AccY contain raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g - TV remote contains the last interpreted command received through IR Packet ID 5: - ProxAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light - Selector contains the value of the current selector position Packet ID 6: - ProxAmbient4 contains values from 0 to 1023, the smaller the values the brighter the ambient light - GroundAmbient* contain values from 0 to 1023, the smaller the values the brighter the ambient light - AccZ contains raw values of the accelerometer; the range is between -128 and 128, sensitivity is +-2g - Battery contains the sampled value of the battery, the values range is between 780 (battery discharged) and 930 (battery charged) Packet ID 7: - LeftSteps and RightSteps contain the sum of the sampled speed for left and right motors respectively (only available when the speed controller isn't used; refer to xpos, ypos and theta when the speed controller is used) - theta contains the orientation of the robot expressed in 1/10 of degree (3600 degrees for a full turn); available only when the speed controller is enabled - xpos and ypos contain the position of the robot expressed in millimeters; available only when the speed controller is enabled ## USB cable Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#USB_cable You can directly connect the robot to the computer to make a basic functional test. You can find the source code in the following link [Elisa3-global-test.zip](https://projects.gctronic.com/elisa3/Elisa3-global-test.zip) (Windows). To start the test follow these steps: 1. put the selector in position 6 2. connect the robot to the computer with the USB cable and turn it on 3. run the program, insert the correct COM port and choose option 1 With the same program you can also change the ID of the robot by choosing option 2 in the last step (not recommended). Via USB cable you can also program the robot with [Aseba](https://www.gctronic.com/doc/index.php?title=Elisa-3#Aseba). # Software Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Software ## Robot Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Robot ### Requirements Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements In order to communicate with the robot through the micro USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise you need to download the drivers for your system and architecture: - [Windows Vista/XP](https://www.ftdichip.com/Drivers/CDM/CDM%20v2.10.00%20WHQL%20Certified.exe), [Windows 7/8/10 (run as administrator)](https://www.ftdichip.com/Drivers/CDM/CDM%20v2.12.10%20WHQL%20Certified.exe) - Ubuntu: when the robot is connected the port will be created in `/dev/ttyUSB0` (no need to install a driver) - [Mac OS X 10.3 to 10.8 (32 bit)](https://www.ftdichip.com/drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg), [Mac OS X 10.3 to 10.8 (64 bit)](https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_2_18.dmg), [Mac OS X 10.9 and above](https://www.ftdichip.com/Drivers/VCP/MacOSX/FTDIUSBSerialDriver_v2_3.dmg); after installing the driver the port will be created in `/dev/tty.usbserial-...`; you can find a guide on how to install the driver in the following link [AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf](https://www.ftdichip.com/Support/Documents/AppNotes/AN_134_FTDI_Drivers_Installation_Guide_for_MAC_OSX.pdf) All the drivers can be found in the official page from the following link [FTDI drivers](https://www.ftdichip.com/Drivers/VCP.htm). Starting from robot ID 3823 the USB to serial chip can be one of the following: FTDI, [Cypress CY7C65213](https://projects.gctronic.com/elisa3/CypressDriverInstaller_1.exe) or Silicon Labs CP2102 ([Windows 10 or later](https://projects.gctronic.com/elisa3/CP210x_Universal_Windows_Driver.zip), [Windows 7](https://projects.gctronic.com/elisa3/CP210x_Windows_Drivers.zip)); this is due to chips availability. ### AVR Studio 4 project Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#AVR_Studio_4_project The projects are built with [AVR Studio 4](https://projects.gctronic.com/elisa3/AvrStudio4Setup.exe) released by Atmel. The projects should be compatible also with newer versions of Atmel Studio (last version known as Microchip Studio), the last version is available from . #### Basic demo Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Basic_demo This project is thought to be a starting point for Elisa-3 newbie users and basically contains a small and clean main with some basic demos selected through the hardware selector that show how to interact with robot sensors and actuators. The project source can be downloaded from the repository ; the hex file can be directly downloaded from [Elisa-3 basic firmware hex](https://projects.gctronic.com/elisa3/elisa3-firmware-basic_ffb3947_21.03.18.hex). To program the robot refer to section [Programming](https://www.gctronic.com/doc/index.php/Elisa-3#Programming). Selector position and related demo: - 0: no speed controller activated => free running (all others positions have the speed controller activated) - 1: obstacle avoidance enabled - 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands) - 3: both obstacle and cliff avoidance enabled - 4: random RGB colors and small green leds on - 5: robot moving forward with obstacle avoidance enabled and random RGB colors #### Advanced demo Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Advanced_demo This is an extension of the *basic demo project*, basically it contains some additional advanced demos. The project source can be downloaded from the repository ; the hex file can be directly downloaded from [Elisa-3 advanced firmware hex](https://projects.gctronic.com/elisa3/elisa3-firmware-advanced_96c355a_13.03.18.hex). To program the robot refer to section [Programming](https://www.gctronic.com/doc/index.php/Elisa-3#Programming). Selector position and related demo: - 0: no speed controller activated => free running (all others positions have the speed controller activated) - 1: obstacle avoidance enabled - 2: cliff avoidance enabled (currently it will simply stop before falling and stay there waiting for commands) - 3: both obstacle and cliff avoidance enabled - 4: random RGB colors and small green leds on - 5: robot moving forward with obstacle avoidance enabled and random RGB colors - 6: robot testing and address writing through serial connection (used in production) - 7: automatic charging demo (refer to section [Videos](https://www.gctronic.com/doc/index.php/Elisa-3#Videos)), that is composed of 4 states: - random walk with obstacle avoidance - search black line - follow black line that lead to the charging station - charge for a while - 8: autonomous odometry calibration (refer to section [Autonomous calibration](https://www.gctronic.com/doc/index.php/Elisa-3#Autonomous_calibration)) - 9: write default odometry calibration values in EEPROM (hard-coded values); wait 2 seconds before start writing the calibration values - 10: robot moving forward (with pause) and obstacle avoidance enabled; random RGB colors and green led effect - 11: local communication: robot alignment - 12: local communication: 2 or more robots exchange data sequentially - 13: local communication: listen and transmit continuously; when data received change RGB color - 14: local communication: RGB color propagation - 15: clock calibration (communicate with the PC through the USB cable to change the OSCCAL register); this position could also be used to remote contol the robot through the radio (only speed control is enabled) #### Atmel Studio 7 / Microchip Studio Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Atmel_Studio_7_/_Microchip_Studio If you are working with Atmel Studio 7 / Microchip Studio, you can simply use the provided AVR Studio 4 projects by importing them directly in Atmel Studio 7 / Microchip Studio: `File => Import => AVR Studio 4 Project`, then select `Elisa3-avr-studio.aps` and click on `Convert`. If you are asked to update some components (see following figure), then agree: ![atmel-studio-convert.png](https://www.gctronic.com/doc/images/8/86/atmel-studio-convert.png) Then click on `Build => Clean solution` and then `Build => Build solution`. If you experience problems during the building, make sure you have the correct toolchain installed: you can download WinAVR toolchain from [WinAVR-20100110-install.exe](https://projects.gctronic.com/elisa3/WinAVR-20100110-install.exe). Close and open again Atmel/Microchip Studio and verify that the new toolchain is recognized and that the path is correct: `Tools => Options` and on the left panel select `Toolchain => Package Configuration`. Select on top `Atmel AVR 8-bit (C language)`, then `WinAVR` flavour and verify the path corresponds to the WinAVR installation path. The following figure shows the toolchain configuration: ![elisa3-atmelstudio1.png](https://www.gctronic.com/doc/images/5/55/elisa3-atmelstudio1.png) Finally verify the project is using the WinAVR toolchain: `right click on the project name => Properties`, on the left panel select `Advanced` and verify that `Toolchain Flavour` is set to WinAVR. Press `CTRL+S` to save your project configuration changes. The following figures show the project configuration: ![elisa3-atmelstudio2.png](https://www.gctronic.com/doc/images/2/27/elisa3-atmelstudio2.png) ![elisa3-atmelstudio3.png](https://www.gctronic.com/doc/images/a/a9/elisa3-atmelstudio3.png) ### Arduino IDE project Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Arduino_IDE_project The project is built with the Arduino IDE 1.x freely available from the [official Arduino website](https://arduino.cc/). In order to build the Elisa-3 firmware with the Arduino IDE 1.x the following steps has to be performed: - 1. download the [Arduino IDE 1.x](https://arduino.cc/hu/Main/Software) (the last known working version is 1.8.9, refer to [Arduino Software](https://www.arduino.cc/en/Main/OldSoftwareReleases#previous)) and extract it, let say in a folder named `arduino-1.x` - 2. download the [Elisa-3 Arduino library](https://projects.gctronic.com/elisa3/elisa3_arduino_library_03.02.25_65964ed.zip) and extract it within the libraries folder of the Arduino IDE, in this case `arduino-1.x\libraries` (see [Find-sketches-libraries-board-cores-and-other-files-on-your-computer](https://support.arduino.cc/hc/en-us/articles/4415103213714-Find-sketches-libraries-board-cores-and-other-files-on-your-computer) for more information on Arduino useful paths); you should end up with a `Elisa3` folder within the libraries. If you start the Arduino IDE now you can see that the `Elisa-3` library is available in the menu `Sketch=>Import Library...` (or `Sketch=>Include Lirary` in later IDE versions). In later versions of Arduino IDE you can also install the library via menu: `Sketch=>Include Library=>Add .ZIP library`, for more info have a look at [importing-a-zip-library](https://docs.arduino.cc/software/ide-v1/tutorials/installing-libraries#importing-a-zip-library). - 3. the file `boards.txt` in the Arduino IDE folder `arduino-1.x\hardware\arduino` (or `arduino-1.x\hardware\arduino\avr` or `Users\{username}\AppData\Local\Arduino15\packages\arduino\hardware\avr\1.8.6` in later IDE versions) need to be changed to contain the definitions for the Elisa-3 robot, add the following definitions at the end of the file: ``` ############################################################## elisa3.name=Elisa 3 robot elisa3.upload.tool=avrdude elisa3.upload.tool.serial=avrdude elisa3.upload.protocol=stk500v2 elisa3.upload.maximum_size=258048 elisa3.upload.speed=57600 elisa3.bootloader.low_fuses=0xE2 elisa3.bootloader.high_fuses=0xD0 elisa3.bootloader.extended_fuses=0xFF elisa3.bootloader.path=stk500v2-elisa3 elisa3.bootloader.file=stk500v2-elisa3.hex elisa3.bootloader.unlock_bits=0x3F elisa3.bootloader.lock_bits=0x0F elisa3.build.mcu=atmega2560 elisa3.build.f_cpu=8000000L elisa3.build.board=AVR_ELISA3 elisa3.build.core=arduino elisa3.build.variant=mega ############################################################## ``` - 4. this step need to be performed only with later IDE versions, when you receive a warning like this `Bootloader file specified but missing...` during compilation. In this case place the bootloader hex file (`stk500v2.hex`) you can find in the [Bootloader section](https://www.gctronic.com/doc/index.php/Elisa-3#Bootloader) in the directory `arduino-1.x\Arduino\hardware\arduino\avr\bootloaders\` and name it `stk500v2-elisa3.hex` - 5. download the [Elisa-3 project file](https://projects.gctronic.com/elisa3/elisa3_arduino_project_02.03.21_d2c017e.zip) and open it with the Arduino IDE (you should open the file "*elisa3.ino*") - 6. select `Elisa-3 robot` from the `Tools=>Board` menu; click on the `Verify` button to build the project - 7. turn on the robot, attach the micro USB and wait the blinks terminate. - 8. to upload the resulting hex file, from the Arduino IDE set the port from the `Tools=>Serial Port` menu consequently; click on the `Upload` button : Only for Windows users: before clicking on `Upload`, open the serial monitor from the Arduino IDE (`Tools => Serial Monitor` or `Ctrl+Shift+M`), the robot should then blink again; keep the serial monitor opened. You can download the Arduino IDE 1.0.5 for Linux (32 bits) containing an updated avr toolchain (4.5.3) and the Elisa3 library from the following link [arduino-1.0.5-linux32.zip](https://projects.gctronic.com/elisa3/arduino-1.0.5-linux32.zip). If the `Tools->Serial Port` menu is grayed out then you need to start the Arduino IDE in a terminal typing `sudo path/to/arduino`. If you want to have access to the compiler options you can download the following project [Elisa3-arduino-makefile.zip](https://projects.gctronic.com/elisa3/Elisa3-arduino-makefile.zip) that contains an Arduino IDE project with a Makefile, follow the instructions in the "readme.txt" file in order to build and upload to the robot. **If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again.** **Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.** ### Aseba Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Aseba Refer to the page [Elisa-3 Aseba](http://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba). ### Matlab Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Matlab ![elisa3-matlab.jpg](https://www.gctronic.com/doc/images/f/fc/elisa3-matlab.jpg) The [ePic2](https://www.e-puck.org/index.php?option=com_content&view=article&id=29&Itemid=27) Matlab interface was adapted to work with the Elisa-3 robot. The communication is handled with the radio module. Both Matlab 32 bits and 64 bits are supported (tested on Matlab R2010a). Follow these steps to start playing with the interface: 1. program the robot with the [advanced demo](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) 2. place the selector in position 15 (to pilot the robot through the interface with no obstacle and no cliff avoidance) 3. connect the radio base-station to the computer 4. download the ePic2 for Elisa-3 from the repository : either from github site clicking on `Code`=>`Download ZIP` or by issueing the command `git clone https://github.com/gctronic/elisa3_epic.git` 5. open (double click) the file *main.m*; once Matlab is ready type *main+ENTER* and the GUI should start 6. click on the *+* sign (top left) and insert the robot address (e.g 3307), then click on *Connect* ### Webots simulator Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Webots_simulator ![Elisa-3-webots.png](https://www.gctronic.com/doc/images/5/5f/Elisa-3-webots.png) The following features have been included in the Elisa-3 model for the [Webots simulator](https://www.cyberbotics.com/): - proximity sensors - ground sensors - accelerometer - motors - green leds around the robot - RGB led - radio communication You can donwload the Webots project containig the Elisa-3 model (proto) and a demonstration world in the following link [Elisa-3-webots.zip](https://projects.gctronic.com/elisa3/Elisa-3-webots.zip). You can download a Webots project containing a demonstration world illustrating the usage of the radio communication between 10 Elisa-3 robots and a supervisor in the following link [Elisa-3-webots-radio.zip](https://projects.gctronic.com/elisa3/Elisa-3-webots-radio.zip). Here is a video of this demo: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Onboard behaviors Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Onboard_behaviors The released firmware contains two basic onboard behaviors: obstacle and cliff avoidance. Both can be enabled and disabled from the computer through the radio (seventh bit of flags byte for obstacle avoidance, eight bit of flags byte for cliff avoidance). The following videos show three robots that have their obstacle avoidance enabled: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Programming Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Programming The robot is pre-programmed with a serial bootloader. In order to upload a new program to the robot a micro USB cable is required. The connection with the robot is shown below: ![Elisa3.1-programming.jpg](https://www.gctronic.com/doc/images/b/b4/Elisa3.1-programming.jpg) If you are working with the Arduino IDE you don't need to follow this procedure, refer instead to section [Arduino IDE project](https://www.gctronic.com/doc/index.php/Elisa-3#Arduino_IDE_project). **If you encounter some problem during programming (e.g. timeout problems) you can try following this sequence: turn on the robot, unplug the robot from the computer, plug the robot into the computer, it will make some blinks; when the blinks terminate execute the programming commands again.** **Beware that every time you need to re-program the robot you need to unplug and plug again the cable to the computer.** #### Windows 7 Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Windows_7 1. Download the [Windows 7 package](https://projects.gctronic.com/elisa3/programming/AVR-Burn-O-Mat-Windows7.zip) and extract it. The package contains also the FTDI driver. Beware that starting from robot id 4000 the USB driver might be different, refer to section [Requirements](https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements), so you need to install it manually in case it isn't an FTDI chip. 2. Execute the script `config.bat` and follow the installation; beware that this need to be done only once. The script will ask you to modify the registry, this is fine (used to save application preferences). 3. Connect the robot to the computer; the COM port will be created. 4. Run the application `AVR Burn-O-Mat.exe`; you need to configure the port to communicate with the robot: 1. click on `Settings => AVRDUDE` 2. in the `AVRDUDE Options`, on `Port` enter the name of the port just created when the robot was connected to the computer (e.g. COM10); then click `Ok` 5. In the `Flash` section search the hex file you want to upload on the robot. 6. Turn on the robot, connect the USB cable to the computer and wait the blinks terminate. Then open a terminal and issue the command `c:\windows\system32\mode.com com10: dtr=on` (change the port number accordingly to your robot). The robot should blink again, if this is not the case then try again the command. 7. From the `AVR Burn-O-Mat` interface, click on `Write` in the `Flash` section. If you get an `Access is denied` error, then run `AVR Burn-O-Mat.exe` as administrator. 8. During the programming the robot will blink; at the end you'll receive a message saying `Flash succesfully written.` #### Mac OS X Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Mac_OS_X The following procedure is tested in Max OS X 10.10, but should work from Mac OS X 10.9 onwards; in these versions there is built-in support for the FTDI devices. 1. Download the [Mac OS X package](https://projects.gctronic.com/elisa3/programming/AVR8-Burn-O-Mat-MacOsX.zip) and extract it. 2. Execute the script `config.sh` in the terminal, it will ask you to install the Java Runtime Environment; in case there is a problem executing the script try with `chmod +x config.sh` and try again. Beware that this need to be done only once. 3. Connect the robot to the computer; the serial device will be created (something like `/dev/tty.usbserial-AJ03296J`). 4. Run the application `AVR Burn-O-Mat`; you need to configure the port to communicate with the robot: 1. click on `Settings => AVRDUDE` 2. in the `AVRDUDE Options`, on `Port` enter the name of the port just created when the robot was connected to the computer; then click `Ok` 5. In the `Flash` section search the hex file you want to upload on the robot. 6. Turn on the robot, wait the blinks terminate and then click on `Write` in the `Flash` section. 7. During the programming the robot will blink; at the end you'll receive a message saying `Flash succesfully written.` #### Linux Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Linux The following procedure was tested in Ubunut 12.04, but a similar procedure can be followed in newer systems and other Linux versions. You can find a nice GUI for `avrdude` in the following link ; you can download directly the application for Ubuntu from the following link [avr8-burn-o-mat-2.1.2-all.deb](https://projects.gctronic.com/elisa3/programming/avr8-burn-o-mat-2.1.2-all.deb). Double click the package and install it; the executable will be `avr8-burn-o-mat`. Beware that the application requires the Java SE Runtime Environment (JRE) that you can download from the official page , alternatively you can issue the command `sudo apt-get install openjdk-8-jre` in the terminal. The application need a bit of configuration, follow these steps: : 1. connect the robot to the computer, the serial device will be created (something like /dev/USB0) : 2. to use the USB port the permissions need to be set to read and write issueing the command `sudo chmod a+rw /dev/ttyUSB0` : 3. start the application and click on `Settings => AVRDUDE` : 4. set the location of `avrdude` and the related configuration file (refer to the previous section when `avrdude` was installed to know the exact location); the configuration file is in `/etc/avrdude.conf` : 3. click `OK`, close the application and open it again (this is needed to load the configuration file information); click on `Settings => AVRDUDE` : 4. select `stk500v2` as the `Programmer` : 5. set the serial port connected to the robot (`/dev/ttyUSB0`) : 6. in `additional options` insert `-b 57600`, you will end up with a window like the following one: ![avrdude-gui.png](https://www.gctronic.com/doc/images/9/92/avrdude-gui.png) : 7. click `OK`; select `ATmega2560` in the `AVR type` : 8. in the `Flash` section search the hex file you want to upload on the robot; select `Intel Hex` on the right : 9. connect the robot to the computer, turn on the robot, wait the blinks terminate and then click on `Write` in the `Flash` section : 10. during the programming the robot will blink; at the end you'll receive a message saying `Flash succesfully written.` #### Command line Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Command_line The [avrdude](https://www.ladyada.net/learn/avr/setup-win.html) utility is used to do the upload, you can download it directly from the following links depending on your system: - [Windows (tested on Windows 7 and 10)](https://projects.gctronic.com/elisa3/programming/WinAVR-20100110-install.exe); `avrdude` will be installed in the path `C:\WinAVR-20100110\bin\avrdude`; avrdude version 5.10 - [Mac OS X](https://projects.gctronic.com/elisa3/programming/CrossPack-AVR-20131216.dmg); `avrdude` will be installed in the path `/usr/local/CrossPack-AVR/bin/avrdude`; to check the path issue the commmand `which avrdude` in the terminal; avrdude version 6.0.1 - Ubuntu (12.04 32-bit): issue the command `sudo apt-get install avrdude` in the terminal; `avrdude` will be installed in the path `/usr/bin/avrdude`; to check the path issue the commmand `which avrdude` in the terminal; avrdude version 5.11.1 Open a terminal and issue the following commands: 1. only for windows users: `c:\windows\system32\mode.com com10: dtr=on`. You should see the robot blink (blue), if this is not the case try again the command. 2. `avrdude -p m2560 -P COM10 -b 57600 -c stk500v2 -D -Uflash:w:Elisa3-avr-studio.hex:i -v` where `COM10` must be replaced with your com port and `Elisa3-avr-studio.hex` must be replaced with your application name; in Mac OS X the port will be something like `/dev/tty.usbserial-...`, in Ubuntu will be `/dev/ttyUSB0`. The [Basic demo](https://www.gctronic.com/doc/index.php/Elisa-3#Basic_demo) and [Advanced demo](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) have this command contained in the file `program.bat` in the `default` directory within the project, this can be useful for Windows users. ### Internal EEPROM Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Internal_EEPROM The internal 4 KB EEPROM that resides in the microcontroller is pre-programmed with the robot ID in the last two bytes (e.g. if ID=3200 (0x0C80), then address 4094=0x80 and address 4095=0x0C). The ID represents also the RF address that the robot uses to communicate with the computer and is automatically read at startup (have a look a the firmware for more details). Moreover the address 4093 is used to save the clock calibration value that is found during production/testing of the robots; this value hasn't to be modified otherwise some functionalities such as tv remote control could not work anymore. For more information on clock calibration refers to the applicaiton note [AVR053: Calibration of the internal RC oscillator](https://projects.gctronic.com/elisa3/AVR053-Calibration-RC-oscillator.pdf). The Elisa-3 robot supports an autonomous calibration process and the result of this calibration is saved in EEPROM starting at address 3946 to 4092. **The size of usable EEPROM is thus 3946 bytes (0-3945) and the remaining memory must not be modified/erased.** In order to program the eeprom an AVR programmer is required, we utilize the Pocket AVR Programmer from Sparkfun (recognized as USBtiny device); then with the [avrdude](https://www.ladyada.net/learn/avr/setup-win.html) utility the following command has to be issued: ``` avrdude -p m2560 -c usbtiny -v -U eeprom:w:Elisa3-eeprom.hex:i -v -B 1 ``` where *Elisa3-eeprom.hex* is the EEPROM memory saved as Intel Hex format ([eeprom example](https://projects.gctronic.com/elisa3/Elisa3-eeprom.hex)); a possible tool to read and write Intel Hex format is [Galep32 from Conitec Datensysteme](https://projects.gctronic.com/elisa3/G32setup_12004-intel-hex-editor.exe). Alternatively a program designed to writing to these EEPROM locations can be uploaded to the robot, in case an AVR programmer isn't available. The project source is available in the repository ; it is simply needed to modify the address, rebuild and upload to the robot. Another option is to use the following Python script [write_radio_address.py](https://projects.gctronic.com/elisa3/write_radio_address.py) (tested in Ubuntu 22.04), the procedure would be: 1. program the robot with the factory firmware 2. put selector in position 6 3. connect the robot to the computer via USB cable 4. set the correct serial port and address in the script 5. run the script After a power-cycle the new address can be used. ### Bootloader Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Bootloader In case the bootloader of the Elisa-3 is erased by mistake, then you can restore it by using an AVR programmer. You can download the bootloader from here [stk500v2.hex](https://projects.gctronic.com/elisa3/stk500v2_20.03.18_13b46ce.hex); the source code is available from the repository . `Avrdude` can be used to actually write the bootloader to the robot with a command similar to the following one: `avrdude -p m2560 -c stk500v2 -P COM348 -v -U lfuse:w:0xE2:m -U hfuse:w:0xD8:m -U efuse:w:0xFF:m -V -U flash:w:stk500v2.hex:i -v -B 2` Here we used a programmer recognized as a serial device (port COM348) that utilizes the `stk500v2` protocol. ## Base-station Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Base-station This chapter explains informations that aren't needed for most of the users since the radio module is ready to be used and don't need to be reprogrammed. Only if you are interested in the firmware running in the radio module and on how to reprogram it then refer to section (chapter 4.2) of the Elisa robot wiki. ## PC side Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#PC_side This section gives informations related to the radio module connected to the computer; if you don't have a radio module you can skip this section. ### Requirements Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Requirements_2 Refer to the section . ### Elisa-3 library Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Elisa-3_library This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. Some basic examples will be provided in the following sections to show how to use this library. The source code of the library is available in the repository ; follow the instructions in the repository to build the library. ### Multiplatform monitor Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Multiplatform_monitor The demo is a command line monitor that shows all the sensors information (e.g. proximity, ground, acceleromter, battery, ...) and let the user move the robot and change its colors and behavior with the keyboard. The data are sent using the protocol described in the previous section. The following figures show the monitor on the left and the available commands on the right. ![Cmd-line-monitor.jpg](https://www.gctronic.com/doc/images/f/fe/Cmd-line-monitor.jpg) ![Pc-side-commands2.jpg](https://www.gctronic.com/doc/images/3/31/Pc-side-commands2.jpg) The source can be downloaded from the repository . #### Windows Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Windows Execution: - install the driver contained in the [nRFgo Studio tool](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio) if not already done; this let the base-station be recognized as a WinUSB device (bootloader), independently of whether the libusb library is installed or not - once the driver is installed, the pre-compiled "exe" (under `\bin\Release` dir) should run without problems; the program will prompt you the address of the robot you want to control Compilation: the Code::Blocks project should already be setup to reference the Elisa-3 library headers and lib files, anyway you need to put this project within the same directory of the Elisa-3 library, e.g. you should have a tree similar to the following one: - Elisa-3 demo (parent dir) - `elisa3_remote_library` (Elisa-3 library project) - `elisa3_remote_monitor` (current project) #### Linux / Mac OS X Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Linux_/_Mac_OS_X The project was tested to work also in Ubuntu and Mac OS X (no driver required). Compilation: - you need to put this project within the same directory of the Elisa-3 library - build command: go under "linux" dir and type `make clean && make` Execution: - `sudo ./main` ### Communicate with 4 robots simultaneously Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Communicate_with_4_robots_simultaneously This example shows how to interact with 4 robots simlutaneously, basically it shows the sensors information (proximity and ground) coming from 4 robots and let control one robot at a time through the keyboard (you can change the robot you want to control). The source can be downloaded from the repository . For building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). ### Obstacle avoidance Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Obstacle_avoidance This demo implements the *obstacle avoidance* behavior controlling the robot from the pc through the radio; this means that the robot reacts only to the commands received using the basic communication protocol and has no "intelligence" onboard. The demo uses the information gathered from the 3 front proximity sensors and set the motors speed accordingly; moreover the RGB LED is updated with a random color at fixed intervals. The source can be downloaded from the repository . For building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). The following video shows the result: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) It is available also the same example but with 4 robots controlled simultaneously; the source can be downloaded from the branch `4robots` of the repository It is easy to extend the previous example in order to control many robots, the code that controls 8 robots simultaneously can be downloaded from the branch `8robots` of the repository . ### Cliff avoidance Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Cliff_avoidance This demo implements the *cliff avoidance* behavior controlling the robot from the pc through the radio; as with the *obstacle avoidance* demo, the robot reacts only to the commands received from the radio. The demo uses the information gathered from the 4 ground sensors to stop the robot when a cliff is detected (threshold tuned to run in a white surface); moreover the RGB LED is updated with a random color at fixed intervals. The source can be downloaded from the repository . For building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). The following video shows the result: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Communication between robots via PC Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Communication_between_robots_via_PC This examples shows how to emulate direct communication between robots: basically a common state is shared between the robots and this state is changed based on the current state of each robot; it emulates the facts that each robot propagates its state to all other robots. Actually all the robots communicate only with the computer (only one computer with only one radio module) and the computer forward the information to all the others robots; the radio is fast enough so that the computer in the middle will not slow down the communication. A big advantage passing from the computer is that you can log the communication messages on the computer and see what is happening. In particular in this demo a total of 4 robots are handled and when a robot crosses a black line, then it inform all others robots to change their color. The source can be downloaded from the repository . For building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). The following video shows the result: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ### Set robots state from file Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Set_robots_state_from_file This project show how to send data to robots for which we will know the address only at runtime, in particular the content of the packets to be transmitted is parsed from a csv file and the interpreted commands are sent to the robots one time. The source can be downloaded from the repository . For building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). ### Elisa-3 Python library Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Elisa-3_Python_library This library simplify the implementation of applications on the pc side (where the radio base-station is connected) that will take control of the robots and receive data from them. The source code of the library and some usage examples are available in the repository . # Odometry Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Odometry The odometry of Elisa-3 is quite good even if the speed is only measured by back-emf. On vertical surfaces the absolute angle is given by the accelerometer measuring g... quite a fix reference without drifting ;-) A fine calibration of the right and left wheel speed parameters might give better results. However the current odometry is a good estimate of the absolute position from a starting point. The experiments are performed on a square labyrinth and the robot advances doing obstacle avoidance. The on-board calculated (x,y,theta) position is sent to a PC via radio and logged for further display. ![odometry-vertical.jpg](https://www.gctronic.com/doc/images/0/09/odometry-vertical.jpg) Details about the code can be found in the [advanced-demo](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) project, in particular the *motors.c* source file. The PC application used for logging data is the [monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29). ## Autonomous calibration Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Autonomous_calibration Since the motors can be slightly different a calibration can improve the behavior of the robot in terms of maneuverability and odometry accuracy. An autonomous calibration process is implemented onboard: basically a calibration is performed for both the right and left wheels in two modes that are forward and backward with speed control enabled. In order to let the robot calibrate istelf a white sheet in which a black line is drawed is needed; the robot will measure the time between detection of the line at various speeds. The calibration sheet can be downloaded from the following link [calibration-sheet.pdf](https://projects.gctronic.com/elisa3/calibration-sheet.pdf). In order to accomplish the calibration the robot need to be programmed with the [advanced firmare](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) and a specific command has to be sent to the robot through the radio module or the TV remote; if you are using the radio module you can use the [monitor application](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor_.28pc_side.29) in which the letter *l (el)* is reserved to launch the calibration, otherwise if you have a TV remote control you can press the button *5*. The sequence is the following: 1. put the selector in position 8 2. place the robot near the black line as shown below; the left motor is the first to be calibrated. Pay attention to place the right wheel as precise as possible with the black line ![elisa3-calibration-1.jpg](https://www.gctronic.com/doc/images/b/bc/elisa3-calibration-1.jpg) ![elisa3-calibration-2.jpg](https://www.gctronic.com/doc/images/2/26/elisa3-calibration-2.jpg) 3. once the robot is placed you can type the *l (el)* command (or press the button *5*); wait a couple of minutes during which the robot will do various turns at various speed in the forward direction and then in the backward direction 4. when the robot terminated (robot is stopped after going backward at high speed) you need to place it in the opposite direction in order to calibrate the right motor, as shown below. ![elisa3-calibration-3.jpg](https://www.gctronic.com/doc/images/2/20/elisa3-calibration-3.jpg) 5. once the robot is placed you can type again the *l (el)* command (or press the button *5*) 6. when the robot finish, the calibration process is also terminated. The previous figures show a robot without the top diffuser, anyway you don't need to remove it! # Tracking Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Tracking ## Assembly documentation Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Assembly_documentation You can download the documentation from here [tracking-doc.pdf](https://projects.gctronic.com/elisa3/tracking-doc.pdf). Have a look also at the video: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## SwisTrack Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#SwisTrack Some experiments are done with the [SwisTrack software](https://en.wikibooks.org/wiki/SwisTrack) in order to be able to track the Elisa-3 robots through the back IR emitter, here is a resulting image with 2 robots: ![elisa-3-tracking-2robots.jpg](https://www.gctronic.com/doc/images/1/1c/elisa-3-tracking-2robots.jpg) The pre-compiled SwisTrack software (Windows) can be downloaded from the following link [SwisTrack-compiled](https://projects.gctronic.com/elisa3/SwisTrackEnvironment-10.04.13.zip). The following video shows the tracking of 5 robots: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) The SwisTrack software lets you easily log also the resulting data that you can then elaborate, here is an example taken from the experiment using 5 robots: ![swistrack-output.jpg](https://www.gctronic.com/doc/images/e/e4/swistrack-output.jpg) The following video shows the test done with 20, 30 and 38 Elisa-3 robots, the tracking is still good; it's important to notice that we stopped to 38 Elisa-3 robots because are the ones we have in our lab. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## Position control Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Position_control We developed a simple position control example that interacts with Swistrack through a TCP connection and control 4 robots simultaneously; the orientation of the robots is estimated only with the Swistrack information (delta position), future improvements will integrate odometry information. The following video shows the control of 4 robots that are driven in a *8-shape*. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ![tracking-8shape.jpg](https://www.gctronic.com/doc/images/d/d8/tracking-8shape.jpg) All the following projects require the [Elisa-3 library](https://www.gctronic.com/doc/index.php/Elisa-3#Elisa-3_library), for building refer to the section [Multiplatform monitor](https://www.gctronic.com/doc/index.php/Elisa-3#Multiplatform_monitor). - Horizontal position control (4 robots): the source code can be downloaded from [position-control-pattern-horizontal-4-robots.zip](https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-4-robots-rev245-15.01.21.zip) (Code::Blocks project). One of the characteristics of the Elisa-3 robot is that it can move in vertical thanks to its magnetic wheels, thus we developed also a vertical position control that use accelerometer data coming from the robot to get the orientation of the robot (more precise) instead of estimating it with the Swistrack information, you can download the source code from the following link: - Vertical position control (4 robots): [position-control-pattern-vertical-4-robots.zip](https://projects.gctronic.com/elisa3/position-control-pattern-vertical-4-robots-rev245-15.01.21.zip) (Code::Blocks project). We developed also an example of position control that control a single robot (code adapted from previous example) that can be useful during the initial environment installation/testing; you can download the source code from the following link: - Horizontal position control (1 robot): [position-control-pattern-horizontal-1-robot.zip](https://projects.gctronic.com/elisa3/position-control-pattern-horizontal-1-robot-rev245-15.01.21.zip) (Code::Blocks project). Another good example to start playing with the tracking is an application that lets you specify interactively the target point that the robot should reach; you can download the source code of this application from the following link: - Go to target point: [position-control-goto-pos-horizontal-1-robot.zip](https://projects.gctronic.com/elisa3/position-control-goto-pos-horizontal-1-robot-rev245-15.01.21.zip) (Code::Blocks project). ## Utilities Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Utilities In order to adjust the IR camera position it is useful to have an application that turn on the back IR of the robots. The following application [back-IR-on-4-robots-rev245-15.01.21.zip](https://projects.gctronic.com/elisa3/back-IR-on-4-robots-rev245-15.01.21.zip) is an example that turn on the back IR of 4 robots, their addresses are asked to the user at the execution. # Local communication Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Local_communication [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) The [advanced firmware](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) is needed in order to use the local communication. You can find some examples on how to use this module in the main, refers to demos in selector position from 11 to 14. Here are some details about the current implementation of the communication module: - use the infrared sensors to exchange data, thus during reception/transmission the proximity sensors cannot be used to avoid obstacles; in the worst case (continuous receive and transmit) the sensor update frequency is about 3 Hz - bidirectional communication - id and angle of the proximity sensor that received the data are available - the throughput is about 1 bytes/sec - maximum communication distance is about 5 cm - no reception/transmission queue (only one byte at a time) - the data are sent using all the sensors, cannot select a single sensor from which to send the data. The data isn't sent contemporaneously from all the sensors, but the sensors used are divided in two groups of 4 alternating sensors (to reduce consumption) ## Clustering example Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Clustering_example In this demo there are **37** elisa-3 robots programmed with a special firmware that you can download here [elisa3_cluster_firmware.hex](https://projects.gctronic.com/elisa3/elisa3_cluster_firmware.hex); the source code is available in the repo . The robots will try to form some clusters by exchanging data through the local communication and at the same time exchange data with a central computer: they send their status (in cluster or not) and receive a new color when in cluster. The application running on the computer side is available in the repo . Here is a video of the demo: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) # ROS Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#ROS This chapter explains how to use ROS with the elisa-3 robots; the radio module is needed here. Basically all the sensors are exposed to ROS and you can also send commands back to the robot through ROS. The ROS node is implemented in cpp. Here is a general schema: ![elisa-ros-schema.png](https://www.gctronic.com/doc/images/0/01/elisa-ros-schema.png) *Click to enlarge* First of all you need to install and configure ROS, refer to for more informations. Alternatively you can download directly a virtual machine pre-installed with everything you need, refer to section [virtual machine](https://www.gctronic.com/doc/index.php/Elisa-3#Virtual_machine); this is the preferred way. : - This tutorial is based on ROS Hydro. The same instructions are working with ROS Noetic, beware to use `noetic` instead of `hydro` when installing the packages. - If you downloaded the pre-installed VM you can go directly to section [Running the ROS node](https://www.gctronic.com/doc/index.php/Elisa-3#Running_the_ROS_node). The ROS elisa-3 node based on roscpp can be found in the following repository . ## Initial configuration Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Initial_configuration The following steps need to be done only once after installing ROS: : 1. If not already done, create a catkin workspace, refer to . Basically you need to issue the following commands: ``` mkdir -p ~/catkin_ws/src cd ~/catkin_ws/src catkin_init_workspace cd ~/catkin_ws/ catkin_make source devel/setup.bash ``` : 2. You will need to add the line `source ~/catkin_ws/devel/setup.bash` to your .bashrc in order to automatically have access to the ROS commands when the system is started : 3. Clone the elisa-3 ROS node repo from inside the catkin workspace source folder (~/catkin_ws/src): `git clone https://github.com/gctronic/elisa3_node_cpp.git` : 4. Install the dependencies: : ROS: : - `sudo apt-get install ros-hydro-slam-gmapping` - `sudo apt-get install ros-hydro-imu-tools` : If you are using a newer version of ROS, replace `hydro` with your distribution name. : cpp: : - install OpenCV: `sudo apt-get install libopencv-dev` : If you are working with OpenCV 4, then you need to change the header include from `#include ` to `#include ` : 5. Rebuild the `elisa-3 library`: go to `~/catkin_ws/src/elisa3_node_cpp/src/pc-side-elisa3-library/linux`, then issue `make clean` and `make` : 6. Open a terminal and go to the catkin workspace directory (~/catkin_ws) and issue the command `catkin_make`, there shouldn't be errors : 7. The USB radio module by default requires root priviliges to be accessed; to let the current user have access to the radio we use udev rules: - in the udev rules file you can find in /etc/udev/rules.d/name.rules add the following string changing the GROUP field with your current user group: : SUBSYSTEMS=="usb", ATTRS{product}=="nRF24LU1P-F32 BOOT LDR", GROUP="viki" : To know which groups your user belongs to issue the command id - disconnect and reconnect the radio module : 8. Program the elisa-3 robot with the last [advanced firmware](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo) (>= rev.221) and put the selector in position 15 ## Running the ROS node Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Running_the_ROS_node First of all get the last version of the elisa-3 ROS node from github: - clone the repo and copy the elisa3_node_cpp directory inside the catkin workspace source folder (e.g. ~/catkin_ws/src) - build the driver by opening a terminal and issueing the command `catkin_make` from within the catkin workspace directory (e.g. ~/catkin_ws). Now you can start the ROS node, for this purposes there is a launch script (based on [roslaunch](https://wiki.ros.org/roslaunch)), as explained in the following section. Before starting the ROS node you need to start roscore, open another terminal tab and issue the command roscore. ### Single robot Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Single_robot Open a terminal and issue the following command: `roslaunch elisa3_node_cpp elisa3_single.launch elisa3_address:='1234'` where 1234 is the robot id (number on the bottom). If all is going well [rviz](https://wiki.ros.org/rviz/UserGuide) will be opened showing the informations gathered from the topics published by the elisa ROS node as shown in the following figure: ![elisa-ros-single-robot.png](https://www.gctronic.com/doc/images/c/c0/elisa-ros-single-robot.png) *Click to enlarge* The launch script is configured also to run the [gmapping (SLAM)](https://wiki.ros.org/gmapping) node that let the robot construct a map of the environment; the map is visualized in real-time directly in the rviz window. Here is a video: EmbedVideo is missing a required parameter. ## Move the robot Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Move_the_robot You have two options to move the robot. The first one is to use the `rviz` interface: in the bottom left side of the interface there is a `Teleop` panel containing an *interactive square* meant to be used with differential drive robots. By clicking in this square you'll move the robot, for instance by clicking on the top-right section, then the robot will move forward-right. ![elisa-teleop.png](https://www.gctronic.com/doc/images/a/a3/elisa-teleop.png) *Click to enlarge* The second method is by directly publishing on the `/mobile_base/cmd_vel` topic, for instance by issueing the following command `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[0.0, 0.0, 0.0]' '[0.0, 0.0, 1.0]'` the robot will rotate on the spot, instead by issueing the following command `rostopic pub -1 /mobile_base/cmd_vel geometry_msgs/Twist -- '[4.0, 0.0, 0.0]' '[0.0, 0.0, 0.0]'` the robot will move straight forward. Beware that there shouldn't be any other node publishing on the `/mobile_base/cmd_vel` topic (e.g. Rviz), otherwise your commands will be overwritten. ## Troubleshooting Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Troubleshooting ### Robot state publisher Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Robot_state_publisher If you get an error similar to the following when you start a node with roslaunch: ``` ERROR: cannot launch node of type [robot_state_publisher/state_publisher]: Cannot locate node of type [state_publisher] in package [robot_state_publisher]. Make sure file exists in package path and permission is set to executable (chmod +x) ``` Then you need to change the launch file from: ``` ``` To: ``` ``` This is due to the fact that `state_publisher` was a deprecated alias for the node named `robot_state_publisher` (see ). ## Virtual machine Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Virtual_machine To avoid the tedious work of installing and configuring all the system we provide a virtual machine which includes all the system requirements you need to start playing with ROS and elisa. You can download the image as *open virtualization format* from the following link ROS-Hydro-12.04.ova (contact us to have access to this VM), based on the VM from ; you can then use [VirtualBox](https://www.virtualbox.org/) to import the file and automatically create the virtual machine. Some details about the system: - user: gctronic, pw: gctronic - Ubuntu 12.04.4 LTS (32 bits) - ROS Hydro installed - [Webots](https://www.cyberbotics.com/) 8.0.5 is installed (last version available for 32 bits linux) - [git-cola](https://git-cola.github.io/) (git interface) is installed - the catkin workspace is placed in the desktop # Videos Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Videos ## Autonomous charge Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Autonomous_charge The following videos show 3 Elisa-3 robots moving around in the environment avoiding obstacles thanks to their proximity sensors and then going to the charging station autonomously; some black tape is placed in the charging positions to help the robots place themselves thanks to their ground sensors. The movement and charging is indipendent of the gravity. It works also vertically and up-side-down. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## Remote control Link: https://www.gctronic.com/doc/index.php?title=Elisa-3#Remote_control The following video shows 38 Elisa-3 robots moving around with onboard obstacle avoidance enabled; 15 of them are running autonmously, the remaining 23 are controlled from one computer with the radio module. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) --- # Elisa-3 Aseba Source: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba Last edited: 2026-04-22T09:48:12Z # Introduction Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Introduction Aseba is a set of tools which allow novices to program robots easily and efficiently, refer to for more information. ## Prerequisites Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Prerequisites The following steps neeed to be done only once: 1. The communication between Aseba and Elisa-3 is done through the USB (serial communication is used) cable so you need to install the driver, refer to section [Elisa-3 requirements](https://www.gctronic.com/doc/index.php/Elisa-3#Requirements); in the future we will maybe add RF support too 2. Download ([Windows](https://projects.gctronic.com/elisa3/aseba-1.6.1.exe), [Linux](https://projects.gctronic.com/elisa3/aseba_1.6.1_amd64.deb), [Mac](https://projects.gctronic.com/elisa3/Aseba-1.6.1.dmg)) and install Aseba version **1.6.1** 3. Download the Elisa-3 target for Aseba [elisa3-aseba.hex](https://projects.gctronic.com/elisa3/elisa3-aseba.hex) and upload it to the robot (refer to section [Elisa-3 Programming](https://www.gctronic.com/doc/index.php/Elisa-3#Programming)) ## Connection with AsebaStudio Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Connection_with_AsebaStudio The following steps explain how to start playing with the Aseba Studio: 1. Connect the robot to the computer if not already done and turn it on 2. Download the following script based on your platform and modify its content specifying the AsebaStudio installation folder and the robot port: - Windows: [asebaswitch_elisa3.zip](https://projects.gctronic.com/elisa3/asebaswitch_elisa3.zip); decompress it and spcifiy the installation folder (e.g. `C:\Program Files (x86)\AsebaStudio`) and the port number (e.g. `10` for `COM10`) - Linux / Mac OS: [asebaswitch_elisa3.sh](https://projects.gctronic.com/elisa3/asebaswitch_elisa3.sh); specifiy the installation folder (e.g. `/usr/bin` in Linux or `/Applications/Aseba/bin` in Mac OS) and the port (e.g. `/dev/ttyUSB0` in Linux or `/dev/cu.usbserial-XXXXX` in Mac OS) 3. Start the script: - Windows: double click on the bat file - Linux / Mac OS: set the script to be executable with the command `chmod +x asebaswitch_elisa3.sh` and then execute it `./asebaswitch_elisa.sh` 4. Start *AsebaStudio* and select `Network(TCP)`, insert `localhost` as `Host` and specify `33333` as `Port` to open the connection with the robot. The final target string must be `tcp:host=localhost;port=33333` 5. If the connection is correctly established you should see the Elisa-3 variables on the left side of *AsebaStudio* as shown in the following figure: ![aseba-screenshot2.jpg](https://www.gctronic.com/doc/images/4/44/aseba-screenshot2.jpg) Have a look also at the following video (you must use the script instead of manually issueing the command as in the video): [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) ## Simple test Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Simple_test Once the connection is opened click on the checkbox *auto* to start updating the sensors data automatically; we can now interact with the robot, for instance on the left side we can see all the sensors values (proximity, ground, accelerometer, ...) and we can change the motor speed and turn on/off all the leds. # Software Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Software First of all hava a look at some of the examples proposed in the following section [AsebaStudio examples](https://www.gctronic.com/doc/index.php/Elisa-3_Aseba#AsebaStudio_examples). Then when you're ready you can start programming the robot on your own, refer to section [Programming interface](https://www.gctronic.com/doc/index.php/Elisa-3_Aseba#Programming_interface); moreover you can have a look at for more information. Pay attention that you have 100 bytes availables for your script due to memory constraints. If you want to have a look behind the scene refer to section [Contribute to the Elisa-3 Aseba target](https://www.gctronic.com/doc/index.php/Elisa-3_Aseba#Contribute_to_the_Elisa-3_Aseba_target). ## AsebaStudio examples Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#AsebaStudio_examples You can download all the following examples from [aseba-elisa3-examples.zip](https://projects.gctronic.com/elisa3/aseba-elisa3-examples.zip); in order to launch an example follow these steps: 1. place the robot selector in position 5. When the robot is turned on, the position of the selector (from 0 to 9) define the node name in *AsebaStudio*, in our case the node name will be `elisa3-5` (where *5* is the selector position) 2. extract the zip, the directory contains some file with *aesl* extension, this is the *AsebaStudio* code extension 3. connect the robot with *AsebaStudio* as explained previously 4. click on menu `File => Open...` and select one of the examples extracted from the zip 5. click on button `Load` and then on `Run`; now the code is running on the robot but it isn't stored in EEPROM, thus when you turn off the robot it returns to its initial state If you want to save the program in memory you need to click on `Tools => Write the program(s)... => inside the elisa3` and wait for the programming termination (the green leds around the robot will be turned on while the memory is written); pay attention to uncheck the *auto* update of the robot variables in *AsebaStudio* before starting the writing (with the *auto* update enabled the writing could block). ### Simple obstacle avoidance Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Simple_obstacle_avoidance ``` var i = 1 while (i==1) do if ((prox[0] > 50) or (prox[1] > 50) or (prox[7] > 50)) then mot.left.target = -20 mot.right.target = 20 else mot.left.target = 20 mot.right.target = 20 end end ``` To fully see the results of this example you need to write the code into the robot. Then let it move with some objects around. ### RGB control Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#RGB_control ``` onevent ir.sensors if (prox[0] > 20) then # avoid noise led.rgb[0] = prox[0] else led.rgb[0] = 0 end if (prox[1] > 20) then # avoid noise led.rgb[1] = prox[1] else led.rgb[1] = 0 end if (prox[7] > 20) then # avoid noise led.rgb[2] = prox[7] else led.rgb[2] = 0 end ``` Once the code is loaded on the robot you can "control" the intensity of the red, green and blue with the *prox[0]*, *prox[1]* and *prox[7]* respectively. Try to get the primary and secondary colors ()...*hint: you need two fingers*. ### Working with events Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Working_with_events ``` var color = 0 onevent ir.sensors led.green[0] = 1 - led.green[0] led.green[2] = 1 - led.green[2] led.green[4] = 1 - led.green[4] led.green[6] = 1 - led.green[6] onevent acc led.green[1] = 1 - led.green[1] led.green[3] = 1 - led.green[3] led.green[5] = 1 - led.green[5] led.green[7] = 1 - led.green[7] onevent timer led.rgb[color] = 255 - led.rgb[color] onevent button if (color == 2) then color = 0 else color++ end led.rgb[0] = 0 led.rgb[1] = 0 led.rgb[2] = 0 ``` The green leds shows the update frequency of the proximity and accelerometer sensors (you can measure it with an oscilloscope if you have one). You can change the value of the variable `timer.period` to change the frequency of the RGB LED, the resolution is 1 ms (e.g. by putting 1000 you'll get the RGB LED blinking at 1 Hz). Moreover you can try pressing the button and see what happen (probably you will deduce from the code...). ### Remote control Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Remote_control ``` onevent rc5 if rc5 == 2 then # forward mot.left.target = 20 mot.right.target = 20 elseif rc5 == 5 then # stop mot.left.target = 0 mot.right.target = 0 elseif rc5 == 8 then # backward mot.left.target = -20 mot.right.target = -20 elseif rc5 == 4 then # left mot.left.target = 0 mot.right.target = 20 elseif rc5 == 6 then # right mot.left.target = 20 mot.right.target = 0 else # error led.rgb[0] = 255 end ``` To fully see the results of this example you need to write the code into the robot. Maybe you should adapt the values used for the various motions and then you can for sure extend the functionalities using others codes (e.g. change RGB LED color). ### Simple local communication Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Simple_local_communication In this example we need to connect two robots at the same time to *AsebaStudio*, to accomplish this *asebaswitch* need to be called with a different command that is: `asebaswitch -d -v "ser:port=104;baud=57600;stop=1;parity=none;fc=none;bits=8" "ser:port=69;baud=57600;stop=1;parity=none;fc=none;bits=8"` Basically there are two targets instead of one; you need to specify the correct `port` number for both the robots. Moreover you need to place the robot receiver selector in position 5 and the robot transmitter selector to another position (from 0 to 9). Both the robots will blink if the connection is correctly opened. Load the following code to the receiver robot: ``` call prox.comm.enable(1) onevent prox.comm led.green[0] = 0 led.green[1] = 0 led.green[2] = 0 led.green[3] = 0 led.green[4] = 0 led.green[5] = 0 led.green[6] = 0 led.green[7] = 0 led.green[prox.comm.rx.id] = 1 if (prox.comm.rx == 1) then led.rgb[0] = 255 led.rgb[1] = 0 led.rgb[2] = 0 elseif (prox.comm.rx == 2) then led.rgb[0] = 0 led.rgb[1] = 255 led.rgb[2] = 0 elseif (prox.comm.rx == 3) then led.rgb[0] = 0 led.rgb[1] = 0 led.rgb[2] = 255 end ``` Load the following line code to the transmitter robot: ``` call prox.comm.enable(1) ``` Now you can change the `prox.comm.tx` values (from 1 to 3) on the transmitter tab and see the effect on the receiver robot; also `prox.comm.rx` and `prox.comm.rx.id` on the receiver tab will change accordingly. You can easily transform the id to an angle by knowing that each sensor is placed at 45 degrees from each other. Remember to place the robots near each other (< 5 cm). ### Square path Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Square_path In this example we exploit the onboard odometry to let the robot move in a square path. You have two possibilities: either running on a vertical wall or running on an horizontal plane, both cases are handled automatically. When the Elisa-3 is turned on, it calibrates the sensors (when is placed vertically it rotates around itself for a while with the green led turned on); when the calibration process is finished you can start the square by "touching" the back side proximity. Pay attention that the robot must be placed with the front pointing right when placed vertically. ``` var DISTANCE = 100 # given in mm var start = 0 var state = 0 var isVertical ``` ``` sub updateState if start == 1 then if (state == 0) then mot.left.target = 20 mot.right.target = 20 led.rgb[0] = 255 led.rgb[1] = 0 led.rgb[2] = 0 if (odom.x >= DISTANCE) then state = 1 end elseif (state == 1) then mot.left.target = 0 mot.right.target = 15 led.rgb[0] = 0 led.rgb[1] = 255 led.rgb[2] = 0 if (odom.theta >= 90) then state = 2 end elseif (state == 2) then mot.left.target = 20 mot.right.target = 20 led.rgb[0] = 0 led.rgb[1] = 0 led.rgb[2] = 255 if (odom.y >= DISTANCE) then state = 3 end elseif (state == 3) then mot.left.target = 0 mot.right.target = 20 led.rgb[0] = 255 led.rgb[1] = 255 led.rgb[2] = 0 call robot.isVertical(isVertical) if (isVertical == 1) then if (odom.theta < 0) then state = 4 end else if (odom.theta >= 180) then state = 4 end end elseif (state == 4) then mot.left.target = 20 mot.right.target = 20 led.rgb[0] = 255 led.rgb[1] = 0 led.rgb[2] = 255 if (odom.x <= 0) then state = 5 end elseif (state == 5) then mot.left.target = 0 mot.right.target = 20 led.rgb[0] = 0 led.rgb[1] = 255 led.rgb[2] = 255 call robot.isVertical(isVertical) if (isVertical == 1) then if ((odom.theta >= -90) and (odom.theta < 0) ) then state = 6 end else if (odom.theta >= 270) then state = 6 end end elseif (state == 6) then mot.left.target = 20 mot.right.target = 20 led.rgb[0] = 0 led.rgb[1] = 0 led.rgb[2] = 0 if (odom.y <= 0) then state = 7 end elseif (state == 7) then mot.left.target = 0 mot.right.target = 20 led.rgb[0] = 0 led.rgb[1] = 0 led.rgb[2] = 0 call robot.isVertical(isVertical) if (isVertical == 1) then if (odom.theta >= 0) then state = 8 end else if (odom.theta >= 360) then state = 8 end end elseif (state == 8) then mot.left.target = 0 mot.right.target = 0 start = 0 end end onevent ir.sensors if (start == 0) then if (prox[4] > 200) then call reset.odometry() state = 0 start = 1 end end callsub updateState ``` ## Contribute to the Elisa-3 Aseba target Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Contribute_to_the_Elisa-3_Aseba_target You can get the source code of the Elisa-3 Aseba target from [github](https://github.com/aseba-community/aseba-targets-arduino.git). The repo contains all Arduino targets, the Elisa-3 target is placed in the directory *elisa3*. To build the project follow these steps: 1. clone the repo by issueing the command: `git clone --recursive https://github.com/gctronic/aseba-targets-arduino.git` 2. download [Atmel Studio 7](https://www.atmel.com/Microsite/atmel-studio/) since this IDE was used to create the project; the installation of *Atmel Studio* includes also the toolchain so you should be able to build the project without any modification 3. to open the project double click `elisa3-aseba.atsln` ### Dependencies Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Dependencies The project depends on some files of [Aseba](https://github.com/aseba-community/aseba) that is included as submodule in the [aseba-targets-arduino repo](https://github.com/aseba-community/aseba-targets-arduino.git) to simplify the building. The files referenced from the project are: - `aseba\trunk\vm\natives.c` - `aseba\trunk\vm\natives.h` - `aseba\trunk\vm\vm.c` - `aseba\trunk\vm\vm.h` - `aseba\trunk\transport\buffer\vm-buffer.c` - `aseba\trunk\transport\buffer\vm-buffer.h` The project depends also on the Elisa-3 library contained in the [*Elisa-3 advanced firmware revision 221*](https://www.gctronic.com/doc/index.php/Elisa-3#Advanced_demo). # Programming interface Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Programming_interface This page describes the programming capabilities of Elisa-3. It lists the different variables, events and functions and indicates to which elements of the robot they refer (see section [Hardware](https://www.gctronic.com/doc/index.php/Elisa-3#Hardware) to know where is the actual position on the robot of the sensors and actuators). Each variable is marked with either *[R]* or *[W]* to indicate whether the variable is used to read a value from the robot or write a value to the robot respectively. This page refers to firmware revision 0 and later. You can find a document that summarizes the programming interface in the following link [elisa3-aseba-cheatsheet.png](https://projects.gctronic.com/elisa3/elisa3-aseba-cheatsheet.png). ## Standard library Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Standard_library The Elisa-3 comes with the Aseba [standard library of native functions, documented on its own page](https://www.thymio.org/en:asebastdnative). ## Motors Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Motors You can change the wheel speeds by writing in these variables: - `motor.left.target` *[W]*: requested speed for left wheel - `motor.right.target` *[W]*: requested speed for right wheel You can read the real wheel speeds from these variables: - `motor.left.speed` *[R]*: real speed of left wheel - `motor.right.speed` *[R]*: real speed of right wheel The values range from -127 to 127, one unit = 5 mm/s. A value of 127 approximately corresponds to a linear speed of 60 cm/s. ## Green LEDs Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Green_LEDs 8 green LEDs make up a circle on the bottom of the robot. `led.green[0..7]` *[W]*: index 0 sets the intensity of the LED at the front of the robot, the others are numbered clockwise. ## RGB LED Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#RGB_LED There is one RGB LED in the center of the robot, its light is smoothly spread out through the top diffuser. `led.rgb[0..2]` *[W]*: the indexes 0, 1 and 2 set respectively the intensity of the red, green and blue. The values range from 0 (off) to 255 (max intensity). ## IR transmitters Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#IR_transmitters There are 3 IR transmitters pointing upwards, two placed in the front side of the robot and one placed in the back side. You can control their state by writing these variables: - `ir.tx.front` *[W]*: 0 means that both front IRs are turned off, 1 means that both front IRs are turned on - `ir.tx.back` *[W]*: 0 means that the back IR is turned off, 1 means that the back IR is turned off ## Button Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Button There is a small button in the back side of the Elisa-3. The variable `button` *[R]* holds the state of this button (1 = released, 0 = pressed). Elisa-3 generates the `button` event when it is pressed or released. ## Proximity sensors Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Proximity_sensors Elisa-3 has 8 proximity sensors around its periphery (placed at 45 degrees from each other). Two arrays of 8 variables hold the values of these sensors, the first is `prox` *[R]* and represents the proximity to an object, the second is `prox.ambient` *[R]* and represents the ambient light intensity: - `prox[0]`, `prox.ambient[0]` : front - `prox[1]`, `prox.ambient[1]` : front right - `prox[2]`, `prox.ambient[2]` : right - `prox[3]`, `prox.ambient[3]` : back right - `prox[4]`, `prox.ambient[4]` : back - `prox[5]`, `prox.ambient[5]` : back left - `prox[6]`, `prox.ambient[6]` : left - `prox[7]`, `prox.ambient[7]` : front left The values in the `prox` array vary from 0 (the robot does not see anything) to 255 (the robot is very close to an obstacle); the values of the `prox.ambient` array start from 1023 when completely dark and decrease with light increase. Elisa-3 updates these arrays at a frequency of about 80 Hz (when local communication is disabled), and generates the `ir.sensors` event after every update. ## Ground sensors Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Ground_sensors Elisa-3 holds 4 ground proximity sensors. These sensors are located at the front of the robot. As black grounds appear like no ground at all (black absorbs the infrared light), these sensors can be used to follow a line on the ground and also to avoid falling from the table. Two arrays of 4 variables hold the values of these sensors, the first is `ground` *[R]* and represents the proximity to the ground or the presence of a black line, the second is `ground.ambient` *[R]* and represents the ambient light intensity at the ground: - `ground[0]`, `ground.ambient[0]` : left - `ground[1]`, `ground.ambient[1]` : front left - `ground[2]`, `ground.ambient[2]` : front right - `ground[3]`, `ground.ambient[3]` : right The values in the `ground` array normally vary from about 600 (white surface) to about 300 (black surface or no ground); the values of the `prox.ambient` array start from 1023 when completely dark and decrease with light increase. Elisa-3 updates these arrays at a frequency of about 80 Hz (when local communication is disabled), and generates the same `ir.sensors` event after every update. ## Accelerometer Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Accelerometer Elisa-3 contains a 3-axes accelerometer. An array of 3 variables, `acc` *[R]*, holds the values of the acceleration along these 3 axes: - `acc[0]` : x-axis (from back to front, positive forward) - `acc[1]` : y-axis (from left to right, positive towards right) - `acc[2]` : z-axis (from bottom to top, positive upward) The values in this array vary from -128 to 128, with 1 g ([the acceleration of the earth's gravity](https://en.wikipedia.org/wiki/Earth%27s_gravity)) corresponding to the value 64. Elisa-3 generates the `acc` event after every update. The z-axis is used also to know the current orientation of the robot, that is if it is moving vertically or horizontally; the current orientation can be accessed using the function `robot.isVertical(dest)`, where `dest` will be 1 if it is vertical or 0 if it is horizontal. ## Selector Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Selector The variable `selector` *[R]* shows the current position of the selector (from 0 to 15). Elisa-3 generates the `sel` event everytime its position is changed. ## Remote control Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Remote_control_2 Elisa-3 contains a receiver for infrared remote controls compatible with the RC5 protocol. When Elisa-3 receives an RC5 code, it generates the `rc5` event. In this case, the variables `rc5` *[R]* is updated. ## Battery Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Battery The variable `bat.percent` *[R]* give you an estimate of the current battery charge given in percentage (100% means you have still a lot of playful time, 0% means you need to wait a little and put the robot in charge). The sampled value can be accessed with the variable `_bat.adc` *[R]* (this is an hidden variable); the values range from 0 to 1023. ## Local communication Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Local_communication Elisa-3 can use its infrared proximity sensors to communicate with other robots within a range of about 5 cm. For more detailed information refer to section [Local communication](https://www.gctronic.com/doc/index.php/Elisa-3#Local_communication). To use the communication, call the `prox.comm.enable(state)` function, with 1 in state to enable communication or 0 to turn it off. If the communication is enabled, the value in the `prox.comm.tx` *[W]* variable is transmitted to others robots from all the sensors. When Elisa-3 receives a value, the event `prox.comm` is fired and the value is in the `prox.comm.rx` *[R]* variable; moreover the `prox.comm.rx.id` *[R]* variable contains the id of the sensors (from 0 to 7, where 0 is the front sensor, sensors id increases clockwise) that received the data. ## Odometry Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Odometry Elisa-3 is capable of estimating how much distance has traveled each wheel resulting in a robot position given in cartesian coordinates (x, y); when moving horizontally the orientation is estimated through the distance traveled by each wheel, instead when moving vertically (what?? vertically?? yes Elisa-3 can move vertically thanks to its magnetic wheels) the orientation is given directly by the accelerometer and it's very precise. The variable `odom.theta` *[R]* contains the current orientation of the robot given in degrees: when moving horizontally the orientation continuously decreases when moving clockwise and continuously increases when moving counter-clockwise; when moving vertically the orientation is from -180 to 180 degrees. The variables `odom.x` *[R]* and `odom.y` *[R]* contain the current position of the robot given in millimeters. By calling the function `reset.odometry` all the data are reset to zero. ## Timer Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Timer Elisa-3 provides a user-defined timer. The variable `timer.period` *[W]* allows to specify the period of the timer in milliseconds. The timer starts the countdown when it is initialized (value > 0). When the period expires, the timer generates a `timer` event. This events is managed in the same way as all the others and cannot interrupt an already executing event handler. The maximum value is 32767 ms (about 32 seconds). ## Onboard behaviors Link: https://www.gctronic.com/doc/index.php?title=Elisa-3_Aseba#Onboard_behaviors Elisa-3 include two onboard behaviors that can be activated or deactivated at will that are obstacle avoidance and cliff detection. To use obstacle avoidance, call the `behavior.oa.enable(state)` function, with 1 in state to enable obstacle avoidance or 0 to disable it; when activated the motors speed will be adapted in order to avoid obstacles. To use cliff detection, call the `behavior.cliff.enable(state)` function, with 1 in state to enable cliff detection or 0 to disable it; when activated the Elisa-3 will stop as soon as it detect a cliff (pay attention that the robot can detect the void only when going forward). ======================================================================== TOPIC: elisa The first Elisa robot version, no longer produced and replaced by Elisa-3. ======================================================================== # Elisa Source: https://www.gctronic.com/doc/index.php?title=Elisa Last edited: 2026-04-22T11:27:57Z | **The Elisa robot is no more produced. It's subsituted by Elisa-3, its more powerful successor!** | | --- | # Overview Link: https://www.gctronic.com/doc/index.php?title=Elisa#Overview Elisa it's a small size robot with 5 cm of diamater, capable of moving also vertically thanks to its magnetic wheels. It includes: - pic microcontroller ([PIC24FJ64GA104](https://projects.gctronic.com/elisa/PIC24FJ64GA104.pdf)) - RGB led - IRs emitters - accelerometer - RF radio for communication - IR receiver - DC motors - diffuser ![Elisa_and_charger_text.jpg](https://www.gctronic.com/doc/images/8/82/Elisa_and_charger_text.jpg) The robot is equipped with two batteries for a duration of up to 4 hours, about 2 hours at normal usage (motors run continuously, IRs and RGB leds turned on). # Getting started Link: https://www.gctronic.com/doc/index.php?title=Elisa#Getting_started ## 1. Install the radio base-station driver Link: https://www.gctronic.com/doc/index.php?title=Elisa#1._Install_the_radio_base-station_driver The base-station requires a driver in order to be correctly recognized, the driver is contained in the [nRFgo-Studio](https://www.nordicsemi.com/Products/Development-tools/nRFgo-Studio) utility (direct link for version 1.21.2 [32bits](https://nsscprodmedia.blob.core.windows.net/prod/software-and-other-downloads/desktop-software/nrf-go-studio/sw/nrfgostudiowin321212installer.msi) and [64bits](https://nsscprodmedia.blob.core.windows.net/prod/software-and-other-downloads/desktop-software/nrf-go-studio/sw/nrfgostudiowin641212installer.msi)); once the utility is installed the radio will be automatically recognized. ## 2. Software Link: https://www.gctronic.com/doc/index.php?title=Elisa#2._Software The Elisa robot has to be charged with either the official released firmware or with a custom firmware; pay attention that the custom firmware must configure the radio in the same way as the official firmware otherwise the communication with the base-station will not work. For more information and source code refer to the [Elisa software section](https://www.gctronic.com/doc/index.php/Elisa#Elisa). ## 3. Demo Link: https://www.gctronic.com/doc/index.php?title=Elisa#3._Demo Once the radio is connected to the pc through usb and the robot is turned on, it's possible to execute a [demo](https://projects.gctronic.com/elisa/pc-side.zip); this demo continuously sends new RGB and motors values to the robots. If all is working well the robot should turn on all the three RGB leds, or one of them depending on the robot address, in increasing level of intensitiy. For more information and source code refer to [PC-side software section](https://www.gctronic.com/doc/index.php/Elisa#PC_side). # Communication Link: https://www.gctronic.com/doc/index.php?title=Elisa#Communication The radio base-station is connected to the PC through USB and transfers data to and from the robot wirelessly. In the same way the radio chip ([nRF24L01+](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRF24L01P)) mounted on the robot communicates through SPI with the microcontroller and transfers data to and from the PC wirelessly. ![Elisa-communication.jpg](https://www.gctronic.com/doc/images/7/73/Elisa-communication.jpg) ## Packet format - PC to robot Link: https://www.gctronic.com/doc/index.php?title=Elisa#Packet_format_-_PC_to_robot The 7 bytes payload packet format is shown below: | Command | Red led | Blue led | Green led | IR + Flags | Right motor | Left motor | | --- | --- | --- | --- | --- | --- | --- | - Command: 0x27 = change state; 0x28 = goto bootloader (base-station) - Red, Blue, Green leds: values from 0 (OFF) to 100 (ON max power) - IR + flags: - first two bits are dedicated to the IRs: - 0x00 => all IRs off - 0x01 => back IR on - 0x02 => front IRs on - 0x03 => all IRs on - third bit is reserved for enabling/disablng IR remote control (0=>diabled, 1=>enabled) - fourth bit is reserved for sleep (1 => go to sleep for 1 minute) - Right, Left motors: speed (in percentage); MSBit indicate direction: 1=forward, 0=backward; values from 0 to 100 Once the robot receives a new packet it returns its battery level to the base-station (one byte ack payload). Both the packet format and the content of the feedback returned by the robot can be easily modified in the software. # Software Link: https://www.gctronic.com/doc/index.php?title=Elisa#Software ## Elisa Link: https://www.gctronic.com/doc/index.php?title=Elisa#Elisa The project is built with Microchip MPLAB IDE; the code to configure the radio is in "nrf.c" The project source can be downloaded from [Elisa firmware](https://projects.gctronic.com/elisa/elisa-firmware.zip). Selector position: - 0: no controller activated (free running) - 2: speed controller activated ## Base-station Link: https://www.gctronic.com/doc/index.php?title=Elisa#Base-station The project is built with [Keil uVision](https://www.keil.com/uvision/) for 8051 processor and then you'll need another tool for flashing a custom firmware to the radio base-station, that is the [nRFgo-Studio](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio). The source can be downloaded from [base-station firmware](https://projects.gctronic.com/elisa/base-station.zip). In order to build the project you need the [nRFgo SDK](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-SDK); once installed, you should find the SDK environment under *C:\Nordic Semiconductor\nRFgo SDK 2.2.0.270*. The *ptx* example you can find in the directory *C:\Nordic Semiconductor\nRFgo SDK 2.2.0.270\source_code\projects\nrfgo_sdk\enhanced_shockburst_examples* was taken as the starting point for the base-station firmware. To build the projcet you need to put the firmware project directory within the *C:\Nordic Semiconductor\nRFgo SDK 2.2.0.270\source_code\projects\nrfgo_sdk\enhanced_shockburst_examples* directory to satisfy the references and then you can simply open the uVision project file *enhanced_shockburst_ptx_nrf24lu1p.uvproj* you find under *\base-station\Keil\nRF24lu1p*. ### Bootloader Link: https://www.gctronic.com/doc/index.php?title=Elisa#Bootloader The base-station firmware contains a bootloader that can be used to update the functionalities of the module; in order to upload a new firmware follow these steps: 1. plug the base-station to the pc through the usb; it will be recognized as a *WinUSB* device 2. download the application [goto-bootloader](https://projects.gctronic.com/elisa/goto-bootloader.zip) and run it; once executed you should see a message saying that the bootloader is entered 3. now start the nRFgo Studio utility; on the left side you should find the base-station module recognized as a bootloader device, select it; on the right side you should be able to select your firmware and click *Program*; after a few seconds you should receive a message saying the upload was successfull 4. once the upload is finished you need to unplug and plug again the usb cable (power-off and on) in order to enter your main program . ## PC side Link: https://www.gctronic.com/doc/index.php?title=Elisa#PC_side ### Windows Link: https://www.gctronic.com/doc/index.php?title=Elisa#Windows The project is built with [Code::Blocks (mingw)](https://www.codeblocks.org/) and sends data to 100 robots address 3010 to 3110) printing statistical information at the end of the transmission; in this demo it's suppposed that the robots return only one byte as response/ack payload. The project requires [libusb-1.0](https://libusb.info/) since it is used to communicate with the radio base-station: [libusb_2011.07.06.7z](https://projects.gctronic.com/elisa/libusb_2011.07.06.7z). The source can be downloaded from [windows demo](https://projects.gctronic.com/elisa/pc-side.zip). Execution: - install the driver contained in the [nRFgo Studio tool](https://www.nordicsemi.com/eng/Products/2.4GHz-RF/nRFgo-Studio) if not already done; this let the base-station be recognized as a WinUSB device (bootloader), independently of whether the libusb library is installed or not - once the driver is installed, the pre-compiled "exe" (under \bin\Debug dir) should run without problems Compilation-windows: - within the libusb-1.0 package you'll find the header "libusb.h" (under /include/libusb-1.0/) and the library "libusb-1.0.a" (in this case under /MinGW32/static/ since we use MinGW) that should be copied or referenced in the compiler headers/libraries - add the linker flag "-lusb-1.0" in the project in order to build successfully (the Code::Blocks project has already set it) ### Linux Link: https://www.gctronic.com/doc/index.php?title=Elisa#Linux The linux pc-side application "main_linux.c" send data to four robots and print the related battery level; in this demo it's suppposed that the robot returns only one byte as response/ack payload. The libusb-1.0 library required for compilation can be downloaded from [libusb-1.0.27.tar.bz2](https://projects.gctronic.com/elisa/libusb-1.0.27.tar.bz2); alternatively you can simply type *sudo apt-get install libusb-1.0* depending on your system. The souce code can be downloaded from [linux demo](https://projects.gctronic.com/elisa/main_linux.c). Compilation: gcc -o main_linux main_linux.c -lusb-1.0 Execution: sudo ./main_linux ======================================================================== TOPIC: robot-painting Autonomous Robot Painting project. ======================================================================== # Autonomous Robot Painting Source: https://www.gctronic.com/doc/index.php?title=Autonomous_Robot_Painting Last edited: 2026-04-22T08:50:53Z Have a look also at the [product page](https://www.gctronic.com/autonomous_robot_painting.php) # Introduction Link: https://www.gctronic.com/doc/index.php?title=Autonomous_Robot_Painting#Introduction Since the Elisa-3 robot is able to move vertically we got the idea to put the Elisa-3 inside a picture frame and let it perform various animations. The video shows only a set of possible behaviors that exploit the sensors and actuators of the robot, but many others behaviors can be implemented; here are some technical information: - the robot is aware precisely of its vertical orientation thanks to its accelerometer - the robot has a rough estimation of its current position inside the picture frame - the behaviors can be controlled through a TV remote (RC5 protocol) - the robot can easily distinguish between a dark and bright surface - the robot is equipped with 8 proximity sensors all around it that can be used to avoid obstacles or to interact with peoples - the red, green and blue channels of the RGB LED are controllable independently Moreover we designed also a charging station to let the frame be animated continuously by the Elisa-3 robot. ![elisa-frame-tv-remote.png](https://www.gctronic.com/doc/images/1/19/elisa-frame-tv-remote.png) There are many available behaviors for the robot that can be chosen using the related button on the tv remote (put the selector in position 15); in sequence: 1. go around and avoid obstacles 2. spiral motion with obstacles avoidance (automatic calibration) 3. motion following vertical and horizontal virtual lines 4. wall following 5. motion following diagonal virtual lines 6. billiards motion 7. go around avoiding obstacles and do random pivot rotations 8. go around avoiding obstacles and continuously change rotation softly 9. stopped 10. go around avoiding obstacles and do random motions (from a predefined set) at fixed intervals 11. follow a virtual "8 shape" (automatic calibration) 12. bounce on the wall 13. follow finger 14. stop a little on the black spots 15. go to charger Moreover it is possible to change the robot speed (the maximum speed isn't the same for all the behaviors). It is also possible to change the color mode independently from the current robot behavior, the available color modes are: 1. random color 2. random color from a predefined set of basic colors (red, green, blue, yellow, cyan, magenta, white) 3. change color softly in a random way 4. random intensity for the red (others channels turned off) 5. random intensity for the green (others channels turned off) 6. random intensity for the blue (others channels turned off) 7. pulse effect for the red (others channels turned off) 8. pulse effect for the green (others channels turned off) 9. pulse effect for the blue (others channels turned off) Moreover it is possible to select the maximum intensity for all of the the color modes. # Software Link: https://www.gctronic.com/doc/index.php?title=Autonomous_Robot_Painting#Software There is an automatic mode (put selector in position 14) in which some of the behaviors are executed sequentially from the ones available; the sequence is: 1. go around and avoid obstacles 2. wall following 3. motion following diagonal virtual lines 4. go around avoiding obstacles and do random pivot rotations 5. billiards motion 6. go around avoiding obstacles and do random motions (from a predefined set) at fixed intervals 7. bounce on the wall 8. go to charger # Video Link: https://www.gctronic.com/doc/index.php?title=Autonomous_Robot_Painting#Video These videos show robotics and art mixed together. [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) # Pictures Link: https://www.gctronic.com/doc/index.php?title=Autonomous_Robot_Painting#Pictures ![elisa3-frame-blackboard-4.jpg](https://www.gctronic.com/doc/images/f/fb/elisa3-frame-blackboard-4.jpg) ![elisa3-frame-poster-0.jpg](https://www.gctronic.com/doc/images/4/44/elisa3-frame-poster-0.jpg) ![elisa-arp-package.jpg](https://www.gctronic.com/doc/images/7/71/elisa-arp-package.jpg) ![elisa3-frame-0.jpg](https://www.gctronic.com/doc/images/f/f4/elisa3-frame-0.jpg) ![elisa3-frame-1.jpg](https://www.gctronic.com/doc/images/c/c0/elisa3-frame-1.jpg) ![elisa3-frame-blackboard.jpg](https://www.gctronic.com/doc/images/f/fc/elisa3-frame-blackboard.jpg) ![elisa3-frame-2.jpg](https://www.gctronic.com/doc/images/6/6e/elisa3-frame-2.jpg) ![wall-paint-arp.jpg](https://www.gctronic.com/doc/images/9/9c/wall-paint-arp.jpg) ![elisa-arp-white3-1.jpg](https://www.gctronic.com/doc/images/f/f6/elisa-arp-white3-1.jpg) ![elisa-arp-fabio2.jpg](https://www.gctronic.com/doc/images/0/0d/elisa-arp-fabio2.jpg) ![elisa-arp-sunset2.jpg](https://www.gctronic.com/doc/images/4/4b/elisa-arp-sunset2.jpg) ![elisa-arp-pacman1.jpg](https://www.gctronic.com/doc/images/c/c6/elisa-arp-pacman1.jpg) ![elisa-arp-christmas3.jpg](https://www.gctronic.com/doc/images/5/58/elisa-arp-christmas3.jpg) ======================================================================== TOPIC: wheelphone Wheelphone, a robotic platform for mobile phones. ======================================================================== # Wheelphone Source: https://www.gctronic.com/doc/index.php?title=Wheelphone Last edited: 2026-04-22T09:32:10Z # Features Link: https://www.gctronic.com/doc/index.php?title=Wheelphone#Features - compatible with **Android** phones (USB communication) and **iPhone** (sound cable) - telepresence (with Skype and robot remote control) ![phones-video-call-icon.png](https://www.gctronic.com/doc/images/2/2a/phones-video-call-icon.png) - avoid obstacles ![phones-video-call-icon.png](https://www.gctronic.com/doc/images/2/2a/phones-video-call-icon.png) - doesn't fall from table ![phones-video-call-icon.png](https://www.gctronic.com/doc/images/2/2a/phones-video-call-icon.png) - runs on carpet ![phones-video-call-icon.png](https://www.gctronic.com/doc/images/2/2a/phones-video-call-icon.png) - docking station ![phones-video-call-icon.png](https://www.gctronic.com/doc/images/2/2a/phones-video-call-icon.png) - charges phone - available examples (apps) source code For more technical specifications refer to the page [Wheelphone technical specifications](http://www.gctronic.com/doc/index.php?title=Wheelphone_technical_specifications) # Getting started Link: https://www.gctronic.com/doc/index.php?title=Wheelphone#Getting_started Informations on how to start playing with the Wheelphone robot can be found in the following page [Getting started](http://www.gctronic.com/doc/index.php?title=Getting_started). # Software Link: https://www.gctronic.com/doc/index.php?title=Wheelphone#Software You can find the software related to the **Android** platform on the following page [**Android software**](http://www.gctronic.com/doc/index.php?title=Android_software). You can find the software related to the **iPhone** platform on the follwing page [**iPhone software**](http://www.gctronic.com/doc/index.php?title=IPhone_software). # Media Link: https://www.gctronic.com/doc/index.php?title=Wheelphone#Media You can find images of the Wheelphone in the following page: [Wheelphone images](http://www.gctronic.com/doc/index.php?title=Wheelphone-images). You can find various videos of the Wheelphone in the following page: [Wheelphone videos](http://www.gctronic.com/doc/index.php?title=Wheelphone-videos). # Hands-on Link: https://www.gctronic.com/doc/index.php?title=Wheelphone#Hands-on If you're interested in doing some mechanical experiments to play with the Wheelphone robot visit the section [Hands-on](http://www.gctronic.com/doc/index.php?title=Hands-on). --- # Getting started Source: https://www.gctronic.com/doc/index.php?title=Getting_started Last edited: 2026-04-22T09:25:34Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) # Package content Link: https://www.gctronic.com/doc/index.php?title=Getting_started#Package_content In the package you will receive: - the Wheelphone robot - iPhone adapters (iPhone 4 to micro USB and iPhone 5 to micro USB) - a wide-angle lens ![wheelphone-package.jpg](https://www.gctronic.com/doc/images/6/65/wheelphone-package.jpg) You can optionally order an android phone with all the Wheelphone apps pre-installed and the charging station. Refers to the [shop](https://www.gctronic.com/shop.php#Wheelphone%20robot). # First steps Link: https://www.gctronic.com/doc/index.php?title=Getting_started#First_steps The Wheelphone robot comes with two cables directly connected to it: one is the sound cable and the other is the micro USB cable. - if you have an Android phone: the micro USB cable is used to communicate with the robot most of the time. At the moment only when the robot need to be controlled through Skype the sound cable is used instead of the USB cable. The robot (when ON) charges the phone with the micro USB. - if you have an iPhone: the sound cable will be used to transfer data between the robot and the iPhone, instead the micro USB cable will be used to charge the robot. 1. Download and install in your phone one (or more) of the applications available for the Wheelphone robot: - Android: you can either download the apps from [Google Play](https://play.google.com/store/search?q=wheelphone&c=apps) or from the Wheelphone wiki, refers to section [Android software](http://www.gctronic.com/doc/index.php?title=Android_software). If you navigate the wiki you need to click the link named *app-name.apk* in order to install an application; when the download finishes, click on it to start the actual installation. - iPhone: you can either download the apps from the AppStore or from the Wheelphone wiki, refers to section [iPhone software](http://www.gctronic.com/doc/index.php?title=iPhone_software). 2. Connect the phone to the robot: - Android: connect the micro USB cable coming from the robot to the phone ![wheelphone-gs-2-android.jpg](https://www.gctronic.com/doc/images/c/ca/wheelphone-gs-2-android.jpg) - iPhone: connect the sound cable to the earphone jack and the micro USB cable to the iPhone using the correct adapter (iPhone4 or iPhone5) ![wheelphone-gs-2-iphone.jpg](https://www.gctronic.com/doc/images/c/c9/wheelphone-gs-2-iphone.jpg) 3. Once the cable is connected you need to place the phone on the back-side of the robot. In order to hold the phone in place you have two bendable *arms* that need to be adapted to the phone size. Before inserting the phone, bend the arms a little more than the phone thickness, paying attention also to the phone width. Once the arms are bent slide in the phone from the top to the bottom until the connector is near the ground (pay attention to not touch the ground). Put the remaining wires under the robot case to avoid them to float around. A good test to know whether the phone is well mounted or not is to put the robot upside down. ![wheelphone-gs-3-1.jpg](https://www.gctronic.com/doc/images/7/77/wheelphone-gs-3-1.jpg) ![wheelphone-gs-3-2.jpg](https://www.gctronic.com/doc/images/a/ab/wheelphone-gs-3-2.jpg) ![wheelphone-gs-3-3.jpg](https://www.gctronic.com/doc/images/b/bc/wheelphone-gs-3-3.jpg) ![wheelphone-gs-3-4.jpg](https://www.gctronic.com/doc/images/c/cd/wheelphone-gs-3-4.jpg) ![wheelphone-gs-3-5.jpg](https://www.gctronic.com/doc/images/1/15/wheelphone-gs-3-5.jpg) ![wheelphone-gs-3-6.jpg](https://www.gctronic.com/doc/images/b/bc/wheelphone-gs-3-6.jpg) ![wheelphone-gs-3-7.jpg](https://www.gctronic.com/doc/images/a/a4/wheelphone-gs-3-7.jpg) ![wheelphone-gs-3-8.jpg](https://www.gctronic.com/doc/images/2/21/wheelphone-gs-3-8.jpg) If the arms give you problems in touching the screen and interacting with the application you can also apply an "*S*" bend to the arms as illustrated in the following image, the phone will still remain well attached to the robot if the bendable arms aren't too loose: ![WP-bendable-arms.jpg](https://www.gctronic.com/doc/images/8/84/WP-bendable-arms.jpg) 4. Now that your phone is sturdy mounted on the robot, you can switch it on (the switch is positioned on the front side of the robot) 5. Start the desired application: - Android: a pop-up window should appear on the screen, listing all the available apps compatible with the Wheelphone; click one of them to start it. ![app-list.png](https://www.gctronic.com/doc/images/d/d0/app-list.png) ![wheelphone-gs-5-2.jpg](https://www.gctronic.com/doc/images/0/0b/wheelphone-gs-5-2.jpg) If nothing happens, that is the list of compatible apps isn't visualized when the robot is turned on, then try to switch off the robot, wait a couple of seconds and switch on the robot again. If you receive the following message instead of the app list when the robot is turned on, then try to switch off the robot, wait a couple of seconds and switch on the robot again. ![usb-comm-error.png](https://www.gctronic.com/doc/images/2/2a/usb-comm-error.png) - iPhone: you can select the application to start from the ones you installed 6. Start another application: - Android: you need to stop the current application (back button), switch off the robot, wait a couple of seconds and switch it on again, now the list of available apps should appear on the screen - iPhone: simply stop the current one and start another one # Charging Link: https://www.gctronic.com/doc/index.php?title=Getting_started#Charging There are two ways to charge the Wheelphone, you can use the micro USB female connector or use its own charger unit thanks to the 2 golden contacts in front of the device. If you leave the phone connected to the robot through the micro USB cable (for the iPhone use the adapter) you need to turn on the robot in order to charge also the phone; if the robot is switched off only the robot will be charged. Please note that the charger unit is twice faster (1A) than in the USB mode (500mA). Furthermore, in order to quickly charge the robot and the phone simultaneously, it's recommended to supply them with two separate power systems. Have a look to the light during charging, one red LED close to the USB mini connector should turn on until the end of the charge, then a green LED indicates that the charge is completed. # Robot firmware update Link: https://www.gctronic.com/doc/index.php?title=Getting_started#Robot_firmware_update In case you need to update the robot firmware, see below the steps. Note that the phone has to be connected to Internet where it will get the new firmware. 1. install the [bootloader application](https://projects.gctronic.com/wheelphone/WheelphoneBootloader.apk) on an Android phone (you can't upgrade the firmware with an iPhone) 2. turn off the robot and connect the phone through the micro USB cable 3. put the robot in charge; it's essential that the robot is in charge because this way it enter "upgrade mode" when turned on 4. switch on the robot (while in charge); the bootloader application on the phone starts (press ok if it doesn't start automatically) 5. the update is started automatically, wait until you see *update complete*; if after a while you do not see *update complete* restart the process from point 2 6. if all gone right then you need to close the bootloader application on the phone, switch off the robot and unplug the charge cable. Now you can use the robot normally. --- # Hands-on Source: https://www.gctronic.com/doc/index.php?title=Hands-on Last edited: 2026-04-22T09:05:27Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) # Phone inclination Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Phone_inclination In some applications you need that the phone mounted on the robot has a longer view with the back camera and this can be accomplished adding a small piece of plastic with which you can adjust the tilt. In our lab we designed a simple extension that let choose between two inclinations, the following figures compares the normal inclination (no extension) and the others two (with the extension in one side and the other side): ![inclination1.jpg](https://www.gctronic.com/doc/images/1/16/inclination1.jpg) ![inclination2.jpg](https://www.gctronic.com/doc/images/8/8b/inclination2.jpg) ![inclination3.jpg](https://www.gctronic.com/doc/images/9/99/inclination3.jpg) The installation is very easy: just insert it in the case of the robot. ![inclination-ext.jpg](https://www.gctronic.com/doc/images/7/7d/inclination-ext.jpg) An application that works better with this extension is the [markers navigation app](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_markers_navigation) that need to detect markers at long distance. # Extra stabilization Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Extra_stabilization Nowadays phones are always bigger and this is normally an advantage for the user, but the Wheelphone could get in troubles loosing the balance easier. For this reason a little weight can be placed on front of the robot to let it be more stable, especially when little ground obstacles need to be overcome. The following figure shows the plastic container (filled with lead) positioned on front of the robot thanks to the "lego connectors": ![WP-stabilization1.jpg](https://www.gctronic.com/doc/images/9/9d/WP-stabilization1.jpg) ![WP-stabilization2.jpg](https://www.gctronic.com/doc/images/3/3f/WP-stabilization2.jpg) ![WP-stabilization3.jpg](https://www.gctronic.com/doc/images/6/60/WP-stabilization3.jpg) The plastic container is covered with some nice pictures, but you can put whatever images you like. # Play with lego Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Play_with_lego The Wheelphone robot has some "lego connectors" around in the case (i.e. in the bottom side near the ground sensors, in the front side over the proximity sensors, in the wheels, ...). The following figures show some lego pieces attached to the Wheelphone, e.g. you can attach two arms and play with a ball, or you can send some message to your friends, ...your fantasy is the limit. ![WP-lego1.jpg](https://www.gctronic.com/doc/images/6/6f/WP-lego1.jpg) ![WP-lego2.jpg](https://www.gctronic.com/doc/images/8/89/WP-lego2.jpg) ![WP-lego3.jpg](https://www.gctronic.com/doc/images/7/7d/WP-lego3.jpg) # Artist extension Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Artist_extension Brings out your artistic side with this extension that let you attach a pen in the back side of the robot. The installation is very easy, the piece must be framed to the case as shown below: ![WP-artist1.jpg](https://www.gctronic.com/doc/images/3/34/WP-artist1.jpg) ![WP-artist2.jpg](https://www.gctronic.com/doc/images/6/6b/WP-artist2.jpg) The following video shows an example: [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) It's not a perfect heart, it's art ;-) # Magnetic drag Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Magnetic_drag The same plastic extension used to *work* with a pen can be used to drag some others thinks thanks to a magnetic connection; insert a little magnet inside the hole as shown in the following first picture, then you are able to be for example a locomitve: ![WP-magnetic-drag1.jpg](https://www.gctronic.com/doc/images/7/79/WP-magnetic-drag1.jpg) ![WP-magnetic-drag2.jpg](https://www.gctronic.com/doc/images/a/aa/WP-magnetic-drag2.jpg) ![WP-magnetic-drag3.jpg](https://www.gctronic.com/doc/images/0/0c/WP-magnetic-drag3.jpg) # Video recording Link: https://www.gctronic.com/doc/index.php?title=Hands-on#Video_recording If you are interested in recording a video directly on the phone that is connected to the robot, thus having the perspective of the robot while is moving, you can follow these steps: 1. connect the phone to the robot and start the [monitor](https://www.gctronic.com/doc/index.php/Android_software#Monitor_advanced) application 2. take the robot in your hands and give the robot a desired speed and enable obstacle avoidance (and cliff avoidance if you are moving on a table) 3. press the *home* button of the phone 4. start the *camera app* from the Android system and start recording 5. place the robot on the ground and let it move around 6. when you are satisfied take the robot, stop the recording and turn off the robot --- # Android software Source: https://www.gctronic.com/doc/index.php?title=Android_software Last edited: 2026-07-22T11:48:20Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) # Apps shortcut list Link: https://www.gctronic.com/doc/index.php?title=Android_software#Apps_shortcut_list - [Basic demos, simple behaviour](https://www.gctronic.com/doc/index.php/Android_software#Basic_demos): - [Monitor application advanced](https://www.gctronic.com/doc/index.php/Android_software#Monitor_advanced): Visualize all the sensor information on the phone and implement "move-around-on-table" behavior. [Wheelphone.apk](https://projects.gctronic.com/wheelphone/Wheelphone.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone](https://play.google.com/store/apps/details?id=com.wheelphone.wheelphone&feature=search_result#?t=W251bGwsMSwyLDEsImNvbS53aGVlbHBob25lLndoZWVscGhvbmUiXQ..). - [Wheelpone odometry](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_odometry): odometry debug [WheelphoneOdometry.apk](https://projects.gctronic.com/wheelphone/WheelphoneOdomMotion-rev163.apk) - [Wheelpone tag detection](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_tag_detection): marker detection debug [WheelphoneTagDetection.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetDebug-rev181.apk) - [Wheelphone follow](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Follow): Follow the leader application. It allows the robot to follow an object in front of it, using the front facing proximity sensors. [Wheelphone_follow.apk](https://projects.gctronic.com/wheelphone/Wheelphone_follow-rev156.apk) - [Wheelphone recorder](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Recorder): record video while moving. [WheelphoneRecorder.apk](https://projects.gctronic.com/wheelphone/Wheelphone_recorder-rev159.apk) - [Wheelphone faceme](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Faceme): Face-tracking application. It keeps track of the position of one face using the front facing camera, then controls the robot to try to face always the tracked face. [WheelphoneFaceme.apk](https://projects.gctronic.com/wheelphone/Wheelphone_faceme-rev155.apk) - [Wheelphone blob follow](https://www.gctronic.com/doc/index.php/Android_software#Blob_following): the Wheelphone robot follows a blob chosen by the user through the interface. [WheelphoneBlobDetection.apk](https://projects.gctronic.com/wheelphone/WheelphoneBlobDetection-rev160.apk) - [Wheelphone line follow](https://www.gctronic.com/doc/index.php/Android_software#Line_following): it allows the robot to follow a black (or white) line on the floor using the ground sensors. [WheelphoneLineFollowing.apk](https://projects.gctronic.com/wheelphone/WheelphoneLineFollowing-rev162.apk) - [Interactive apps](https://www.gctronic.com/doc/index.php/Android_software#Interactive_demos): - [Wheelphone Pet](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Pet): PET application. It makes the robot behave like a pet. A behavior module allows it to show expressions and behave accordingly. Additionally has a face-tracking and text-to-speech modules to be able to interact with the environment. [WheelphonePet.apk](https://projects.gctronic.com/wheelphone/WheelphonePet.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphonePet](https://play.google.com/store/apps/details?id=com.wheelphone.pet) - [Wheelphone Alarm](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Alarm): Application that interfaces with the Wheelphone to provide a playful experience when the alarm rings. [WheelphoneAlarm.apk](https://projects.gctronic.com/wheelphone/WheelphoneAlarm.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphoneAlarm](https://play.google.com/store/apps/details?id=com.wheelphone.alarm) - [Navigation apps](https://www.gctronic.com/doc/index.php/Android_software#Navigation): - [Wheelphone markers navigation](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_markers_navigation): markers based navigation. [WheelphoneTargetNavigation.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetNavigation.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphoneTargetNavigation](https://play.google.com/store/apps/details?id=com.wheelphone.targetNavigation) - [Wheelphone Navigator](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_Navigator): environment navigation application. It allows the robot to navigate an environment looking for targets while avoiding obstacles. It has two modules to avoid the obstacles: (1)the robot’s front proximity sensors and (2)the camera + Optical Flow. [WheelphoneNavigator.apk](https://projects.gctronic.com/wheelphone/WheelphoneNavigator.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphoneNavigator](https://play.google.com/store/apps/details?id=com.wheelphone) - [ROS demo](https://www.gctronic.com/doc/index.php/Android_software#ROS): the robot publishes sensors and image data and the computer subscribes to them - phone-side: [WheelphoneROS.apk](https://projects.gctronic.com/wheelphone/WheelphoneROS.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone ROS](https://play.google.com/store/apps/details?id=com.wheelphone.ros&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJvcyJd). - pc-side: [ros pc-side binary files](https://projects.gctronic.com/wheelphone/pc-side-node-rev161-08.10.13.zip). - [Autonomous docking](https://www.gctronic.com/doc/index.php/Android_software#Autonomous_docking): - [WheelphoneBlobDocking.apk](https://projects.gctronic.com/wheelphone/WheelphoneBlobDocking.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone blob docking](https://play.google.com/store/apps/details?id=com.gctronic.android.blobDocking&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS5nY3Ryb25pYy5hbmRyb2lkLmJsb2JEb2NraW5nIl0.) - [WheelphoneTargetDocking.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetDocking.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone target docking](https://play.google.com/store/apps/details?id=com.wheelphone.targetDocking&hl=en) - [Remote control](https://www.gctronic.com/doc/index.php/Android_software#Remote_control): - [telepresence with Skype](https://www.gctronic.com/doc/index.php/Android_software#Telepresence_with_Skype). - [remote control (audio, video, movement)](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_remote):[WheelphoneRemote.apk](https://projects.gctronic.com/wheelphone/WheelphoneRemote.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone remote](https://play.google.com/store/apps/details?id=com.wheelphone.remote&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJlbW90ZSJd). - [remote control (only movement)](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_remote_mini): [WheelphoneRemoteMini.apk](https://projects.gctronic.com/wheelphone/WheelphoneRemoteMini.apk), [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone remote mini](https://play.google.com/store/apps/details?id=com.wheelphone.remotemini&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJlbW90ZW1pbmkiXQ..). # Supported phones Link: https://www.gctronic.com/doc/index.php?title=Android_software#Supported_phones Some phones are reported to not work due to missed system libraries; you can test if your phone should be supported with the following application: [features.apk](https://projects.gctronic.com/wheelphone/features.apk). From the list of features that is shown the *android.hardware.usb.accessory* must be present. If you are intereseted you can find the source code from the following link [features.zip](https://projects.gctronic.com/wheelphone/features.zip) Moreover the phone must be configured in order to accept installation of applications coming from different sources than Play Store. Here is a list of phones that are tested to be working: - Sony Ericsson Xperia arc LT15i (Android 2.3.4) - Sony Ericsson Xperia Mini (Android 2.3.4, Android 4.0.4) - Sony Ericsson Xperia tipo ST21i2 (Android 4.0.4) - LG Nexus 4 (Android 4.2+) - Samsung Galaxy S2 (Android 4.0.3) - Samsung Galaxy S3 Mini (Android 4.1.1) - Samsung Galaxy S3 (Android 4.1.2) - Samsung Galaxy S4 (Android 4.2.2) - Samsung Galaxy S Duos (Android 4.0.4) - Huawei Ascend Y300 (Android 4.1.1) - Huawei Ascend Y530 (Android 4.3) Phones running Android 4.1 (or later) works with the new Android Open Accessory Protocol Version 2.0, thus you need to update to the latest robot firmware (>= rev43). Let us know if your phone is working at the following address: ![mail.gif](https://www.gctronic.com/doc/images/a/ab/mail.gif) # Wheelphone library Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_library Wheelphone library to be used in android applications development to communicate with the robot (get sensors data and send commands). The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-library/trunk/android-wheelphone-library android-wheelphone-library-read-only ``` Alternatively you can download directly the jar file to be included in your project [WheelphoneLibrary.jar](https://projects.gctronic.com/wheelphone/WheelphoneLibrary-rev15.jar). You can find the API documentation in the *doc* folder or you can download it from [WheelphoneLibrary.pdf](https://projects.gctronic.com/wheelphone/WheelphoneLibrary-rev87-31.05.13.pdf). # ROS Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS ## Android side Link: https://www.gctronic.com/doc/index.php?title=Android_software#Android_side ### ROS Fuerte Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS_Fuerte **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone ROS](https://play.google.com/store/apps/details?id=com.wheelphone.ros&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJvcyJd), or directly from [WheelphoneROS.apk](https://projects.gctronic.com/wheelphone/WheelphoneROS.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneROS WheelphoneROS ``` It's based on the *android_tutorial_pubsub* contained in the *android package*. **Requirements building** - [android_core](https://docs.rosjava.googlecode.com/hg/android_core/html/index.html) **How To** 1) once the application is started the IP address of the computer running *roscore* need to be inserted, then press *OK* ![Screenshot-WP-ROS1.png](https://www.gctronic.com/doc/images/1/14/Screenshot-WP-ROS1.png) 2) on top of the window you should see "Connected" and right after the camera image that is sent to the computer; after some seconds you should receive the sensors values and the camera image in the computer. If you see "Robot disconnected" you need to restart the application ![Screenshot-WP-ROS2.png](https://www.gctronic.com/doc/images/9/9b/Screenshot-WP-ROS2.png) ### ROS Hydro Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS_Hydro **APK** The android application can be downloaded from directly from [WheelphoneROShydro.apk](https://projects.gctronic.com/wheelphone/WheelphoneROShydro.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/wheelphone_ros wheelphone_ros ``` **How to build** 1. download and install Andorid Studio + SDK, refer to 2. sudo apt-get install ros-hydro-catkin ros-hydro-ros ros-hydro-rosjava python-wstool 3. download android core frome the repo and extract it to your preferred dir (e.g. ~/hydro_workspace/android) 4. open Android Studio (run studio.sh) and open a project pointing to "~/hydro_workspace/android/android_core/settings.gradle" (refer to previous dir path); build the project (this can take a while...) 5. download the "wheelphone_ros" project (svn repo) and put it inside the "android_core" directory 6. modify the file "settings.gradle" inside the "android_core" directory in order to include also the "wheelphone_ros" project 7. close and reopen Android Studio; the wheelphone project should be available for building Alternatively you can download directly a virtual machine which includes all the system requirements you need to start playing with ROS and Wheelphone from the following link ROSHydro-WP.ova (contact us to have access to this VM), based on the VM from ; this is the easiest way! **How to run** 1) once the application is started the IP address of the computer running *roscore* need to be inserted, then press *Connect* ![Screenshot-WP-ROShydro.png](https://www.gctronic.com/doc/images/3/3f/Screenshot-WP-ROShydro.png) 2) on top of the window you should see "Connected" and right after the camera image that is sent to the computer; after some seconds you should receive the sensors values and the camera image in the computer. If you see "Robot disconnected" you need to restart the application ![Screenshot-WP-ROS2.png](https://www.gctronic.com/doc/images/9/9b/Screenshot-WP-ROS2.png) **Useful links** - [ROS Hydro Android](https://wiki.ros.org/android/Tutorials/hydro) - [ROS Hydro Android Development Environment](https://wiki.ros.org/android/Tutorials/hydro/Installation%20-%20Ros%20Development%20Environment) - - - - ## PC side Link: https://www.gctronic.com/doc/index.php?title=Android_software#PC_side **Summary** This is a monitor interface of the Wheelphone based on ROS: ![ros-gui.png](https://www.gctronic.com/doc/images/0/05/ros-gui.png) You can move the robot through the interface or through the keyboard: arrow keys to move and enter to stop. Here is the nodes involved in ROS: ![ros-rxgraph.jpg](https://www.gctronic.com/doc/images/8/81/ros-rxgraph.jpg) A video of the this demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Remote_control_with_ROS). ### ROS Fuerte Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS_Fuerte_2 **Requirements running** - [ROS Fuerte](https://www.ros.org) (previous version not tested) - [rosjava](https://code.google.com/p/rosjava/), refers also to the [rosjava_core documentation](https://docs.rosjava.googlecode.com/hg/rosjava_core/html/index.html) **Source** The source code is available from [rosjava_tutorial_pubsub.zip](https://projects.gctronic.com/wheelphone/rosjava_tutorial_pubsub-rev160-08.10.13.zip). It's based on the *rosjava_tutorial_pubsub* contained in the *rosjava package*. **How To** Follow these steps to start the PC-side node: 1. download the [ros pc-side binary files](https://projects.gctronic.com/wheelphone/pc-side-node-rev161-08.10.13.zip) 2. modify the script *start-ros.sh* in the *bin* directory with the correct IP address of the host computer 3. execute *start-ros.sh* (if the script isn't executable type *chmod +x -R path-to/bin* where bin is the bin directory of the zip) ### ROS Hydro Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS_Hydro_2 **Requirements** - [ROS Hydro](https://wiki.ros.org/hydro); you can download a virtual machine with ROS Hydro already installed (Ubuntu) from here - [rosjava](https://wiki.ros.org/rosjava); type the following commands in a terminal to install rosjava: - sudo apt-get update - sudo apt-get install openjdk-6-jre - sudo apt-get install ros-hydro-rosjava Alternatively you can download directly a virtual machine which includes all the system requirements you need to start playing with ROS and Wheelphone from the following link ROSHydro-WP.ova (contact us to have access to this VM), based on the VM from ; this is the easiest way! **How To Build** 1. cd ~/hydro_workspace/ 2. mkdir -p rosjava/src 3. cd src 4. catkin_create_rosjava_pkg rosjava_catkin_package_wheelphone 5. cd .. 6. catkin_make 7. source devel/setup.bash 8. cd src/rosjava_catkin_package_wheelphone 9. catkin_create_rosjava_project my_pub_sub_tutorial 10. cd ../.. 11. catkin_make 12. download the [pc-side project](https://projects.gctronic.com/wheelphone/my_pub_sub_tutorial.zip) and substitute the "my_pub_sub_tutorial" directory with the content of the zip 13. cd ~/hydro_workspace/rosjava 14. catkin_make **How To Run** 1. open a terminal and type: 1. export ROS_MASTER_URI= (IP should be the host machine IP, e.g. 192.168.1.10) 2. export ROS_IP=IP (the same IP as before) 2. open a second terminal and type the previous two commands 3. in the first terminal type "roscore" 4. in the second terminal type: 1. cd ~/hydro_workspace/rosjava/src/rosjava_catkin_package_wheelphone/my_pub_sub_tutorial 2. cd build/install/my_pub_sub_tutorial/bin 3. ./my_pub_sub_tutorial com.github.rosjava_catkin_package_wheelphone.my_pub_sub_tutorial.Listener **Useful links** - [rosjava](https://wiki.ros.org/rosjava) - [rosjava installation](https://wiki.ros.org/rosjava/Tutorials/hydro/Installation) - [Creating rosjava packages](https://wiki.ros.org/rosjava_build_tools/Tutorials/hydro/Creating%20Rosjava%20Packages) - [Writing a simple publisher and subscriber](https://wiki.ros.org/rosjava_build_tools/Tutorials/hydro/WritingPublisherSubscriber%28Java%29) - [rosjava github](https://github.com/rosjava) ### ROS Tools Link: https://www.gctronic.com/doc/index.php?title=Android_software#ROS_Tools - you can use [rviz](https://wiki.ros.org/rviz) to visualize odometry information, type "rosrun rviz rviz" and open one of the following configuration files depending on your ROS version [fuerte config](https://projects.gctronic.com/wheelphone/rviz-fuerte.zip) [hydro config](https://projects.gctronic.com/wheelphone/rviz-hydro.zip). - you can use [rxgraph (fuerte)](https://wiki.ros.org/rxgraph) or [rqt_graph (hydro)](https://wiki.ros.org/rqt_graph) to visualize a diagram of the nodes and topics available in ROS simply type "rxgraph" or "rqt_graph" in a terminal # Navigation Link: https://www.gctronic.com/doc/index.php?title=Android_software#Navigation ## Wheelphone markers navigation Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_markers_navigation **Summary** Wheelphone makes a tour of the apartment taking snapshot pictures and then returns back to the charging station. This application shows the potentiality of the Wheelphone robot in an home environment. With the help of some target points identified with different markers, the Wheelphone robot is able to navigate from one room to the other localizing itself; moreover it takes pictures and uploads them to a web page. When the Wheelphone battery is low it can automatically charge itself thanks to the docking station. There are two tabs: one illustrates some sensors values, the target detection information (direction and orientation), the current state of the robot and some others information; the second one shows the camera view and when a frame target is detected a nice augmented reality letter is visualized. The application is designed for the following sequence: 1. the robot moves around looking for the docking station; once detected it approaches the docking station and charges itself for a while 2. the robot goes out of the charger, takes a picture and then looks around for the first marker (living room); once detected it goes towards the marker until it reaches it, rotates 180 degrees and takes a picture 3. the robot looks for the next target (kitchen); once detected it goes towards the marker and takes a picture. Then the sequence is repeated. In the "Robot" tab you can see the HTTP address to which to connect in order to see the pictures taken by the robot. Frame target detection is performed using the Vuforia Augmented Reality SDK (license agreements: ). A nice video of the demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Wheelphone_navigation_and_automatic_docking_with_markers). The following image shows the history of a complete tour taken from the HTTP page published by the Wheelphone: ![AppartTagSequenceHistory.png](https://www.gctronic.com/doc/images/9/9c/AppartTagSequenceHistory.png) The markers used in the demo can be donwloaded from here: [charger station](https://projects.gctronic.com/wheelphone/frameMarkerChargerStation.pdf), [living room](https://projects.gctronic.com/wheelphone/frameMarkerLivingRoom.pdf), [kitchen](https://projects.gctronic.com/wheelphone/frameMarkerKitchen.pdf). A similar application was developed also for iPhone, have a look [here](https://www.gctronic.com/doc/index.php/IPhone_software#iWheel_semester_project) for more information. **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone markers navigation](https://play.google.com/store/apps/details?id=com.wheelphone.targetNavigation&hl=it), or directly from [WheelphoneTargetNavigation.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetNavigation.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneTargetNavigation WheelphoneTargetNavigation ``` A version of the application without rendering on the phone display (no 3D letter visualized on target position) is available from the following repositoriy; this version was created since the rendering causes the application to be unstable: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneTargetNavigation_no_rendering WheelphoneTargetNavigation_no_rendering ``` **How To** 1) prepare the docking station with the marker [charger station](https://projects.gctronic.com/wheelphone/frameMarkerChargerStation.pdf), the "navigation targets" with markers [living room](https://projects.gctronic.com/wheelphone/frameMarkerLivingRoom.pdf) and [kitchen](https://projects.gctronic.com/wheelphone/frameMarkerKitchen.pdf) and place them in a triangular shape in such a way that form the docking station the robot is able to detect the "living room", from the "living room" the robot is able to detect the "kitchen" and from the kitchen the robot is able to detect the docking station, like shown in the following figures: ![MarkerOnDocking.jpg](https://www.gctronic.com/doc/images/f/f6/MarkerOnDocking.jpg) ![MarkerOnSupport.jpg](https://www.gctronic.com/doc/images/9/9a/MarkerOnSupport.jpg) ![TargetNavigationEnv.jpg](https://www.gctronic.com/doc/images/d/d4/TargetNavigationEnv.jpg) 2) once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 3) the robot start searching (pivot rotation) the marker id 2 (living room); when the robot finds the marker it goes towards it until it is near, then it rotates for about 180 degrees saying what target it found and then takes a picture that will be automatically updated on the web page. In case the marker isn't found then after 30 seconds the robot start searching the next target 4) the searching sequence is: target id 2 (living room), target id 3 (kitchen), target id 0/1 (charger station). When the robot is approaching the charging station it need two id, one big to be detected at long distances and one small used to center itself to the docking station when it is near the charger. If the robot fails to connect to the charger station, then it applies some movements to try making a good contact with the charger; anyway in case after a while it hasn't reach the contact then it search for the next target. In case of success it charges itself for a while (user definable), then it goes out of the charger, rotates for about 180 degrees saying what target it found and then takes a picture. The following figure explains the values and parameters available in the application: ![WPTargetNavigation-howto.png](https://www.gctronic.com/doc/images/8/80/WPTargetNavigation-howto.png) ## Wheelphone Navigator Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Navigator **Summary** This is a navigation application. It allows the robot to navigate an environment looking for targets while avoiding obstacles. It has two modules to avoid the obstacles: (1)the robot’s front proximity sensors and (2)the camera + Optical Flow. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) - Android NDK: r9 [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) - OpenCV: 2.4.6 [OpenCV Android SDK](https://opencv.org/android) **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) - Back camera - OpenCV: 2.4.6 [OpenCV mangager](https://play.google.com/store/apps/details?id=org.opencv.engine) (Android app) **Building process** - This application has some JNI code (C/C++), so it is necessary to have the android NDK to compile the C/C++ code. Once you have the NDK, the C/C++ code can be compiled by running (while at the jni folder of the project): ``` ${NDKROOT}/ndk-build –B ``` ***Note:*** Make sure that the NDKROOT and OPENCVROOT environment variables are set to the NDK and OpenCV SDK paths respectively. **APK** [WheelphoneNavigator.apk](https://projects.gctronic.com/wheelphone/WheelphoneNavigator.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphoneNavigator](https://play.google.com/store/apps/details?id=com.wheelphone) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_navigator Wheelphone_navigator ``` **How To** How to interact with the application: add at least two targets and then tap on “start”. This makes the robot go between all the targets in its list, while avoiding the obstacles. # Autonomous docking Link: https://www.gctronic.com/doc/index.php?title=Android_software#Autonomous_docking ## Wheelphone blob docking Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_blob_docking **Summary** This demo uses OpenCV to detect a colored blob placed on the charging station; the blob is used to give the robot a direction to follow to reach the docking station. When the robot is near the docking it detect a black line (placed on the ground) and follow it to correctly orient itself towards the charging contacts. The project contains also a stripped version of [Spydroid](https://code.google.com/p/spydroid-ipcamera/) (only HTTP server) that let the user start and stop the demo remotely from a PC or another phone. **Requirements building** Developer requirements (for building the project): - [OpenCV Android SDK](https://opencv.org/android) **Requirements running** User requirements (to run the application on the phone): - the OpenCV package is required to run the application on the phone; on Google Play you can find [*OpenCV Manager*](https://play.google.com/store/apps/details?id=org.opencv.engine&feature=search_result#?t=W251bGwsMSwxLDEsIm9yZy5vcGVuY3YuZW5naW5lIl0.) that let you install easily the needed library **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone blob docking](https://play.google.com/store/apps/details?id=com.gctronic.android.blobDocking&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS5nY3Ryb25pYy5hbmRyb2lkLmJsb2JEb2NraW5nIl0.), or directly from [WheelphoneBlobDocking.apk](https://projects.gctronic.com/wheelphone/WheelphoneBlobDocking.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneBlobDocking WheelphoneBlobDocking ``` **How To** 1) once the application is started the robot start moving around with obstacle avoidance enabled looking for a docking station 2) take the robot in your hands and press the "Blob tab" that show you the camera view. Point the robot to the docking station and touch on the screen to select the blob to follow as shown in the following figure: ![Screenshot-WPBlobDocking1.png](https://www.gctronic.com/doc/images/8/84/Screenshot-WPBlobDocking1.png) 3) place the robot on the ground and press the "Calibrate sensors" button to calibrate the robot in your environment; be sure to remove any object near the robot 4) set a threshold corresponding to the value of the ground sensors related to the black line used to centering to the docking station; if the ground sensor value < threshold then the black line is detected 5) place the robot away from the charger (1 or 2 meters) and let it try to dock itself; when the robot reaches the charging station it will stay there There is also a web page you can navigate with any browser inserting the address given in the "Robot tab"; in this page you'll see 5 motion commands (forward, backward, left, right, stop); stop is used to stop the robot, the others to start the robot. ## Wheelphone target docking Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_target_docking **Summary** This demo uses the Vuforia Augmented Reality SDK to detect a frame target placed on the charging station; the target is used to give the robot a direction to follow to reach the docking station. With this library you get also the orientation of the robot respect to the target, that is respect to the charger; with this information it's easier for the robot to be aligned to the charging station before reaching it. The project contains also a stripped version of [Spydroid](https://code.google.com/p/spydroid-ipcamera/) (only HTTP server) that let the user start and stop the demo remotely from a PC or another phone. A video of the this demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Wheelphone_automatic_docking_with_marker). **Requirments building** Developer requirements (for building the project): - [Vuforia Augmented Reality SDK](https://developer.vuforia.com/resources/sdk/android) **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone target docking](https://play.google.com/store/apps/details?id=com.wheelphone.targetDocking&hl=en), or directly from [WheelphoneTargetDocking.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetDocking.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneTargetDocking WheelphoneTargetDocking ``` **How To** 1) prepare the docking station with the marker [charger station](https://projects.gctronic.com/wheelphone/frameMarkerChargerStation.pdf) as shown in the following figure: ![MarkerOnDocking.jpg](https://www.gctronic.com/doc/images/f/f6/MarkerOnDocking.jpg) 2) once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 3) the robot starts searching for the charging station rotating on place at little steps 4) take the robot on your hands, place it on the ground and press "Calibrate sensors" (remove any object near the robot); if the phone camera is not centered you can also set a camera offset (move the slider in the position of the phone camera) 5) place the robot away from the charger (1 or 2 meters) and let it try to dock itself; when the robot reaches the charging station it will stay there There is also a web page you can navigate with any browser inserting the address given in the "Robot tab"; in this page you'll see 5 motion commands (forward, backward, left, right, stop); stop is used to stop the robot, the others to start the robot. The "Target tab" shows the camera view and when a marker is detected a nice augmented reality letter is visualized; this can be used to know the maximum distance at which the charging station can be still detected. # Remote control Link: https://www.gctronic.com/doc/index.php?title=Android_software#Remote_control ## Telepresence with Skype Link: https://www.gctronic.com/doc/index.php?title=Android_software#Telepresence_with_Skype **Summary** Wheelphone allows worldwide telepresence simply using Skype. One can have a real time video feedback from a remote place where the robot is moving. To control the Wheelphone robot movement, just open the Skype numpad and pilot the robot while seeing the real time images. A video of the this demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Wheelphone_robot_telepresence_with_Skype_.28iPhone_and_Android.29). **How To** 1. start Skype application on the phone and login 2. connect the sound cable to the phone in order to send commands from Skype to the robot; make sure that Skype recognizes the robot as earphone, if this isn't the case try to disconnect and reconnect the audio cable 3. remove the micro USB cable from the phone because USB communication has priority over the audio communication at the moment 4. enable the "Answer call automatically" option in the Skype settings in order to automatically respond to incoming call and be able to immediately control the robot 5. start the Skype application in the computer (or alternatively from another phone), login and make a video call to the account you use on the phone connected to the robot (if you are in the same room disable the microphone) 6. now you should be able to get the robot view; open the Skype numpad on the computer side and use it to move the robot, the commands are shown in the following figure: ![skype-dialpad-cmd.jpg](https://www.gctronic.com/doc/images/8/8f/skype-dialpad-cmd.jpg) ## Wheelphone remote Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_remote **Summary** The robot can be easily controlled via a browser after having configured the computer and the robot to be in the same wifi network. The project is based on the *spydroid (v6.0)* application, refer to for more information. **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone remote](https://play.google.com/store/apps/details?id=com.wheelphone.remote&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJlbW90ZSJd), or directly from [WheelphoneRemote.apk](https://projects.gctronic.com/wheelphone/WheelphoneRemote.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneRemote WheelphoneRemote ``` **How To** 1) make sure to have the latest [VLC plugin](https://addons.videolan.org/) installed on the computer; unfortunately there is no VLC plugin for mobile phone so at the moment the video cannot be visualized if a connection *phone to robot* is performed (only movment commands are available). 2) connect the phone and the computer within the same network 3) once the application is started you'll see the address to be inserted in the browser to be able to control the robot; open a browser and insert the address; if all is working well you'll see the following html page: ![Screenshot-WPRemote.png](https://www.gctronic.com/doc/images/d/d5/Screenshot-WPRemote.png) 4) click on the "Connect" button in the html page and you should receive the video stream; on the right you've some commands to send to the robot, i.e. sounds, motions, ... ## Wheelphone remote mini Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_remote_mini **Summary** This is a stripped version of *Wheelphone remote* that contains only an HTTP server used to receive the motion commands for the robot. It is implemented to have a minimal interface to pilot the robot both from the PC and another phone. Moreover the [Vuforia Augmented Reality SDK](https://developer.vuforia.com/) is used to track a marker when it is in the robot view (pivot rotation at the moment). **APK** The android application can be downloaded from the [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone remote mini](https://play.google.com/store/apps/details?id=com.wheelphone.remotemini&feature=search_result#?t=W251bGwsMSwxLDEsImNvbS53aGVlbHBob25lLnJlbW90ZW1pbmkiXQ..), or directly from [WheelphoneRemoteMini.apk](https://projects.gctronic.com/wheelphone/WheelphoneRemoteMini.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneRemoteMini WheelphoneRemoteMini ``` it is based on the [Spydroid application](https://code.google.com/p/spydroid-ipcamera/). **How To** 1) connect the phone and the computer within the same network 2) once the application is started you'll see the address to be inserted in the browser to be able to control the robot; open a browser and insert the address; if all is working well you'll see the following html page: ![Screenshot1-WPRemoteMini.jpg](https://www.gctronic.com/doc/images/0/05/Screenshot1-WPRemoteMini.jpg) 3) press the "Start animation" button to start the visualization of various images that will change based on the commands sent to the robot through the html page; coupled with the images there will be also sounds related to motion commands If you try to raise the Wheelphone robot, or place an object near the front proximity sensors you'll see a reaction from the robot. Moreover you can place a marker (ID0 or ID1) on front of the robot and the robot will start to follow it (pivot rotation only), moreover information about the target will be shown on the screen, like in the following figure: ![Screenshot2-WPRemoteMini.jpg](https://www.gctronic.com/doc/images/3/3d/Screenshot2-WPRemoteMini.jpg) ## Telepresence with Skype and Wheelphone remote mini Link: https://www.gctronic.com/doc/index.php?title=Android_software#Telepresence_with_Skype_and_Wheelphone_remote_mini **Summary** Wheelphone allows worldwide telepresence by using Skype for audio/video coupled with the Wheelphone remote mini application to issue motion commands. In order to access the Wheelphone remote mini webserver from Internet, we configured the port forwarding rule on the router through the "UPnP - Internet Gateway Device" protocol; this is done automatically by an application (see following section for the source code). **Source** The source code of the "UPnP-IGD" application is available from [UPnP-IGD.zip](https://projects.gctronic.com/wheelphone/UPnP-IGD.zip). This application setup a forwarding rule to the current device on port 8080. **How To** 1. start Skype application on the phone and login 2. connect the micro USB cable to the phone and start the Wheelphone remote mini application 3. enable the "Answer call automatically" option in the Skype settings in order to automatically respond to incoming call and be able to immediately control the robot; if this option is not available you would need to answer manually the call 4. start the application "UPnP-IGD" (it requires that UPnP protocol is enabled in the router); the application will show the public address to enter in order to reach the Wheelphone remote mini webserver 5. start the Skype application in the computer (or alternatively from another phone), login and make a video call to the account you use on the phone connected to the robot 6. on the same computer open a browser and enter the public address given by the "UPnP-IGD" application 7. now you should be able to get the robot view from skype and you can control the robot through the browser # Interactive demos Link: https://www.gctronic.com/doc/index.php?title=Android_software#Interactive_demos ## Wheelphone Pet Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Pet **Summary** This is a PET application. It makes the robot behave like a pet. A behavior module allows it to show expressions and behave accordingly. Additionally has a face-tracking and text-to-speech modules to be able to interact with the environment. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) - Android NDK: r9 [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) **Building process:** - This application has some JNI code (C/C++), so it is necessary to have the android NDK to compile the C/C++ code. Once you have the NDK, the C/C++ code can be compiled by running (while at the jni folder of the project): ``` ${NDKROOT}/ndk-build –B ``` ***Note:*** Make sure that the NDKROOT environment variable is set to the NDK path **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) - Front facing camera **APK** [WheelphonePet.apk](https://projects.gctronic.com/wheelphone/WheelphonePet.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphonePet](https://play.google.com/store/apps/details?id=com.wheelphone.pet) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_pet Wheelphone_pet ``` **State:** - Speech recognition has been partially implemented using googles API. It would be better to use cmusphinx. - The FaceExpressions module, used to express the robot state, could be extended to support animations instead of static images. For this purpose, libgdx can be used. **How To** How to interact with the application: start the application and stand where the phone can see your face. ## Wheelphone Alarm Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Alarm **Summary** This is an alarm application that interfaces with the Wheelphone to provide a playful experience when the alarm rings. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) **Building process:** - Nothing special: download the code, import to Eclipse and run. **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) - Proximity sensor on the phone **APK** [Wheelphone alarm](https://projects.gctronic.com/wheelphone/WheelphoneAlarm.apk) [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)WheelphoneAlarm](https://play.google.com/store/apps/details?id=com.wheelphone.alarm) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_alarm Wheelphone_alarm ``` **State:** It is a concept app, so it actually does not actually ring. **How To** It is possible to set the alarm time, the escape speed and a delay in which the robot will be stopped before starting escaping around when ringing. The alarm can be set to anytime within the next 24 hours. When the alarm is ringing, the phone proximity sensor will also detect the approaching hand and will make the robot run away from the hand. In order to setup an alarm follow these steps: 1. once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 2. setup an alarm (or use the "quick alarm" button to set an alarm in the next 5 seconds); choose also the desired escape speed and waiting time 3. press the *home* button to leave the application running in the background, this way you can still use your phone to do others thinks; be aware not to press the *back* button because you'll terminate the application 4. press the *power* button to put the phone in sleep and put the phone on its charger station (hint: place the robot near your bed) 5. wake up! The alarm song that is played is the one chosen in the system. # Basic demos Link: https://www.gctronic.com/doc/index.php?title=Android_software#Basic_demos ## Monitor advanced Link: https://www.gctronic.com/doc/index.php?title=Android_software#Monitor_advanced **Summary** This is the Wheelphone demo that shows you all the sensors values (proximity, ground, battery) and let you move the robot and sets some onboard behaviors. This is the first application that you will probably install to start playing with the robot. **APK** The android application can be downloaded from the Google Play store [![google-play.png](https://www.gctronic.com/doc/images/4/43/google-play.png)Wheelphone](https://play.google.com/store/apps/details?id=com.wheelphone.wheelphone&feature=search_result#?t=W251bGwsMSwyLDEsImNvbS53aGVlbHBob25lLndoZWVscGhvbmUiXQ..), or directly from [Wheelphone.apk](https://projects.gctronic.com/wheelphone/Wheelphone.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone Wheelphone ``` **How To** The application has two tabs, in left one the sensors information are displayed, in the right one you can choose to start the "stay-on-the-table" behavior that basically let the robot move safely on any table (not a black one though) without the risk to falling down (put the robot on the table before starting the behavior). ## Wheelphone odometry Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_odometry **Summary** This is a demo that can be used as a starting point to work with the odometry information received from the robot. The application let the robot either rotate in place by an angle (degrees) specified by the user or move forward/backward for a distance (cm) specified by the user. **APK** The android application can be downloaded directly from [WheelphoneOdomMotion.apk](https://projects.gctronic.com/wheelphone/WheelphoneOdomMotion-rev163.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneOdomMotion WheelphoneOdomMotion ``` **How To** 1. once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 2. set the movement speed in the "Settings" section (given in mm/s) 3. now you can decide whether to do a rotation (robot rotates on place for the given degrees) or a linear movement (robot goes forward for the given distance in cm); set the desired value and press the related "GO" button based on the motion you want to do 4. if you want to stop the robot you can press the "Stop robot" button in any moment The following figure show the interface of the application: ![Screenshot-WPOdometryMotion.png](https://www.gctronic.com/doc/images/c/c7/Screenshot-WPOdometryMotion.png) In the "Robot status" section are visualized: current left and right speed given to the robot (mm/s); the absolute position X (mm, pointing forward), Y (mm, pointing left), theta (degrees); the battery level ## Wheelphone tag detection Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_tag_detection **Summary** This is a demo that can be used as a starting point to work with the vuforia tag detection library (). You can use this application to get useful information about the tag detected such as distance and angle; you can analyse the performance of the tag detection for instance setting a speed and seeing the maximum speed at which the robot can still detect the tag rotating in place, or seeing the maximum distance at which the phone can detect the tag. **APK** The android application can be downloaded directly from [WheelphoneTargetDebug.apk](https://projects.gctronic.com/wheelphone/WheelphoneTargetDebug-rev181.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneTargetDebug WheelphoneTargetDebug ``` **How To** 1. once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 2. now you can either take the robot in your hands and manually debug target detection or set motors speed and see how perform target detection at various speeds (e.g. max rotation speed in which the marker is still detected) Actually you can also start the application without being connected to the robot only for tracking debugging purposes. The following figure show the interface of the application: ![Screenshot-TargetDebug.png](https://www.gctronic.com/doc/images/2/25/Screenshot-TargetDebug.png) - in the "Speed status" you can set the motors speed (mm/s) - in the "Target status" you have the current marker id detected (from 0 to 49), the X and Y screen coordinates of the marker center, the distance (scene units) from the marker, the orientation of the robot (degrees) and the angle between the robot and the target (degrees); moreover you receive timing informations about the tracking processing (min, max, current, average in ms) - in the "Robot status" you can enable/disable speed control and soft acceleration and you have the battery value - in the "Phone status" you get information about CPU and RAM usage ## Wheelphone Follow Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Follow **Summary** This is a follow the leader application. It allows the robot to follow an object in front of it using the front facing proximity sensors. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) **Building process:** - Nothing special: download the code, import to Eclipse and run. **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) **APK** [Wheelphone follow](https://projects.gctronic.com/wheelphone/Wheelphone_follow-rev156.apk) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_follow Wheelphone_follow ``` **How To** Start the application and place something within 5cm in front of the robot. This will make the robot start following the object. ## Wheelphone Recorder Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Recorder **Summary** This is a recording application. It makes the robot record while it moves. The purpose of this application is to provide the perspective of the robot while it is moving. **Be aware that this application is not stable, take it as a starting point.** For a workaround on how to record a video directly from the robot refer to section []. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) - Back camera **Building process:** - Nothing special: download the code, import to Eclipse and run. **APK** [Wheelphone recorder](https://projects.gctronic.com/wheelphone/Wheelphone_recorder-rev159.apk) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_recorder Wheelphone_recorder ``` **How To** Tap on the screen to start and stop the recording/movement. The recorded video is QUALITY_480P (720 x 480 MP4), saved into the sdcard in the following path: /DCIM/wheelphone_capture.mp4. ## Wheelphone Faceme Link: https://www.gctronic.com/doc/index.php?title=Android_software#Wheelphone_Faceme **Summary** This is face-tracking application. It keeps track of the position of one face using the front facing camera, then controls the robot to try to face always the tracked face. **Requirements building** - Eclipse: 4.2 - Android SDK API level: 18 (JELLY_BEAN_MR2) - Android NDK: r9 [Android NDK](https://developer.android.com/tools/sdk/ndk/index.html) **Building process:** - This application has some JNI code (C/C++), so it is necessary to have the android NDK to compile the C/C++ code. Once you have the NDK, the C/C++ code can be compiled by running (while at the jni folder of the project): ``` ${NDKROOT}/ndk-build –B ``` ***Note:*** Make sure that the NDKROOT environment variable is set to the NDK path **Requirements running** - Android API version: 14 (ICE_CREAM_SANDWICH) - Front facing camera **APK** [Wheelphone faceme](https://projects.gctronic.com/wheelphone/Wheelphone_faceme-rev155.apk) **Source** ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/Wheelphone_faceme Wheelphone_faceme ``` **State:** Could be extended to allow setting the rotation/acceleration constant, and draw a square on top of the tracked face. **How To** How to interact with the application: start the application and stand where the phone can see your face. ## Blob following Link: https://www.gctronic.com/doc/index.php?title=Android_software#Blob_following **Summary** The demo shows the potentiality of having a mobile phone attached to the robot, in this example the phone is responsible of detecting a color blob and to send commands to the robot in order to follow it. A video of the this demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Wheelphone_following_a_color_blob.2C_based_on_OpenCV). **Requirements building** Developer requirements (for building the project): - [OpenCV Android SDK](https://opencv.org/android) **Requirements running** User requirements (to run the application on the phone): - the OpenCV package is required to run the application on the phone; on Google Play you can find [*OpenCV Manager*](https://play.google.com/store/apps/details?id=org.opencv.engine&feature=search_result#?t=W251bGwsMSwxLDEsIm9yZy5vcGVuY3YuZW5naW5lIl0.) that let you install easily the needed library **APK** The android application can be downloaded from [WheelphoneBlobDetection.apk](https://projects.gctronic.com/wheelphone/WheelphoneBlobDetection-rev160.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneBlobDetection WheelphoneBlobDetection ``` It's based on the *blob-detection* example contained in the *OpenCV-2.4.2-android-sdk*. **How To** Once the application is started you will see that all the values are 0; that's normal, you have to select the blob to follow in order to start the hunting. Select the "Blob tab" and touch on the blob you want to follow; the robot should start moving, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list). The following figures show the interface of the application: ![Screenshot1-BlobFollow.png](https://www.gctronic.com/doc/images/8/8f/Screenshot1-BlobFollow.png) ![Screenshot2-BlobFollow.png](https://www.gctronic.com/doc/images/9/90/Screenshot2-BlobFollow.png) ## Line following Link: https://www.gctronic.com/doc/index.php?title=Android_software#Line_following **Summary** This demo shows one of the possible behaviors that can be programmed on the phone, in particular it instructs the robot to follow a line. The threshold and logic (follow a black or a white line) can be choosen from the application. **APK** The android application can be downloaded from [WheelphoneLineFollowing.apk](https://projects.gctronic.com/wheelphone/WheelphoneLineFollowing-rev162.apk). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneLineFollowing WheelphoneLineFollowing ``` **How To** 1. once the application is started you should see "Connected" on top of the window, otherwise you need to restart the application (back button, turn off the robot, turn on the robot, select the app from the list) 2. the robot start moving immediately, thus take it in your hands for doing some settings 3. set the base speed of the robot in the bottom of the window, section "Settings" 4. set the threshold of the black line you want to follow, basically when the ground value is smaller than the threshold it means that a line is detected; use the ground sensors values reported in the "Ground sensors" section to help you choose the best value 5. place the robot on the ground and press the button "Calibrate sensors", remove all object near the robot before doing that; this is needed to be sure that the front proximity sensors are well calibrated since the onboard obstacle avoidance is also enabled by default 6. put the robot near a black line and check that it can follow it The following figure shows the interface of the application: ![Screenshot-LineFollow.png](https://www.gctronic.com/doc/images/3/35/Screenshot-LineFollow.png) # Webots Link: https://www.gctronic.com/doc/index.php?title=Android_software#Webots Webots allows you to simulate the Wheelphone robot and program different behaviors for the robot in simulation before transferring them onto the real robot. You can download the Wheelphone simulation files from [wheelphone.zip](https://www.cyberbotics.com/files/wheelphone/wheelphone.zip) (which includes several demo programs) as well as the corresponding student [report](https://www.cyberbotics.com/files/wheelphone/report.pdf). # Bootloader Link: https://www.gctronic.com/doc/index.php?title=Android_software#Bootloader The robot firmware can be easily updated through this app when a new version is available. Refer to the [getting started](https://www.gctronic.com/doc/index.php/Getting_started#Robot_firmware_update) guide for more information on how to update your robot. The project is based on the example *Web Bootloader Demo - OpenAccessory Framework* contained in the [Microchip Libraries for Applications](https://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=2680&dDocName=en547784). ## Newest firmware Link: https://www.gctronic.com/doc/index.php?title=Android_software#Newest_firmware This bootloader version has to be used to update the robot to the last developed firmware with all new features and bugs corrected. Pay attention that this version breaks compatibility with old applications, section [Apps shortcut list](https://www.gctronic.com/doc/index.php/Android_software#Apps_shortcut_list) shows the list of compatible applications that depend on the Wheelphone library. **APK** The android application can be downloaded directly from [WheelphoneBootloader.apk](https://projects.gctronic.com/wheelphone/WheelphoneBootloader.apk) (firmware rev 3.0). **Source** The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneBootloader WheelphoneBootloader ``` ## Older firmwares Link: https://www.gctronic.com/doc/index.php?title=Android_software#Older_firmwares This bootloader has to be used to return to the old firmware that is compatible with the applications developed before the Wheelphone Library release. The android application can be downloaded from [wheelphone-bootloader.apk](https://projects.gctronic.com/wheelphone/wheelphone-bootloader-rev2-rev96-12.06.13.apk) (firmware rev 2.0). The source code of the application can be download from [wheelphone-bootloader.zip](https://projects.gctronic.com/wheelphone/wheelphone-bootloader-rev2-rev96-12.06.13.zip) (Eclipse project) ## Hardware revision 0.1 Link: https://www.gctronic.com/doc/index.php?title=Android_software#Hardware_revision_0.1 This bootloader has to be used for robots numbered from 10 to 15; the firmware that will be uploaded to the robot is the same as described in section [Newest firmware](https://www.gctronic.com/doc/index.php/Android_software#Newest_firmware). The android application can be downloaded from [wheelphone-bootloader.apk](https://projects.gctronic.com/wheelphone/wheelphone-bootloader-hw0.1-rev98-13.06.13.zip.apk) (firmware rev 2.0). The source code of the application can be download from [wheelphone-bootloader.zip](https://projects.gctronic.com/wheelphone/wheelphone-bootloader-hw0.1-rev98-13.06.13.zip) (Eclipse project) # Calibration Link: https://www.gctronic.com/doc/index.php?title=Android_software#Calibration Since the motors can be slightly different a calibration can improve the behavior of the robot in terms of speed. An autonomous calibration process is implemented onboard: basically a calibration is performed for both the right and left wheels in three modes that are forward with speed control enabled, forward with speed control disabled and backward with speed control disabled. In order to let the robot calibrate istelf a white sheet in which a black line is drawed is needed; the robot will measure the time between detection of the line at various speed. The calibration sheet can be downloaded from the following link [calibration-sheet.pdf](https://projects.gctronic.com/wheelphone/calibration-sheet.pdf). A small application was developed to accomplish the calibration that can be downloaded from [WheelphoneCalibration.apk](https://projects.gctronic.com/wheelphone/WheelphoneCalibration-rev186.apk); simply follow the directions given. The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/android-applications/WheelphoneCalibration WheelphoneCalibration ``` ![wp-calibration-left.png](https://www.gctronic.com/doc/images/7/74/wp-calibration-left.png) ![wp-calibration-right.png](https://www.gctronic.com/doc/images/d/da/wp-calibration-right.png) --- # IPhone software Source: https://www.gctronic.com/doc/index.php?title=IPhone_software Last edited: 2026-04-22T09:08:52Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) # Tested phones Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Tested_phones The communication between the Wheelphone robot and the phone is accomplished using the sound interface (through sound cable of classic headphones), thus the software should run theoretically in all iPhone versions. Anyway here is a list of tested ones: - iPhone 3 - iPhone 4 - iPhone 5 - iPod Touch # Remote control Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Remote_control ## Telepresence with Skype Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Telepresence_with_Skype Wheelphone allows worldwide telepresence simply using Skype. One can have a real time video feedback from a remote place where the robot is moving. In addition to your Skype account, you only need to create another different one for the wheelphone. Now, to control the Wheelphone robot movement, just open the Skype numpad and pilot the robot while seeing the real time images. ![skype-dialpad-cmd.jpg](https://www.gctronic.com/doc/images/8/8f/skype-dialpad-cmd.jpg) The sound cable has to be connected to the phone in order to send commands from Skype to the robot; make sure that Skype recognizes the robot as earphone, if this isn't the case try to disconnect and reconnect the audio cable. # Wheelphone library Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Wheelphone_library Wheelphone library to be used in iOS applications development to communicate with the robot (get sensors data and send commands). The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-library/trunk/ios-wheelphone-library ios-wheelphone-library-read-only ``` # Basic demo Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Basic_demo This is a basic demo that shows how it's possible to send data from the iphone to the robot. Basically pre-recorded DTMF tones are sent to the robot that distinguish them as different commands. The app let you move the robot, calibrate the sensors and sets some behaviors. ![basic-wheelphone-demo-iphone-screenshot.png](https://www.gctronic.com/doc/images/d/d5/basic-wheelphone-demo-iphone-screenshot.png) The iOS application can be downloaded from the [App Store](https://itunes.apple.com/us/app/wheelphone/id619822093?mt=8). The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/ios-applications/WheelphoneBasic WheelphoneBasic-read-only ``` # Monitor application Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#Monitor_application This is the Wheelphone demo that shows you all the sensors values (proximity, ground, battery) and let you start two behaviors controlled from the phone: line following and cliff detection. This is one of the first applications that you will probably install to start playing with the robot. ![ios-monitor.png](https://www.gctronic.com/doc/images/f/fa/ios-monitor.png) The iOS application can be downloaded from the [App Store](https://itunes.apple.com/us/app/wp-monitor/id786102580?mt=8). The source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/ios-applications/WheelphoneMonitor WheelphoneMonitor-read-only ``` # iWheel semester project Link: https://www.gctronic.com/doc/index.php?title=IPhone_software#iWheel_semester_project The aim of the project is to use the Wheelphone to navigate in an indoor environment. The project starts by exploiting the odometry information given by the robot, then it improves the accuracy of the odometry by integrating the sensors of the phone and at the end some external tags are used to get absolute information within the environment. The first application let the robot perform a square path using various navigation methods (open loop, robot odomtery, phone sensors), the user can then compare the results: - the iOS application can be downloaded from the [App Store](https://itunes.apple.com/us/app/wheelphone-square-motion/id948588383?mt=8). - the source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/ios-applications/WPSquareMotion WPSquareMotion-read-only ``` In the second application the Wheelphone makes a tour of the apartment taking snapshot pictures and then returns back to the charging station. This application shows the potentiality of the Wheelphone robot in an home environment. With the help of some target points identified with different markers, the Wheelphone robot is able to navigate from one room to the other localizing itself; moreover it takes pictures and uploads them to a web page. When the Wheelphone battery is low it can automatically charge itself thanks to the docking station. A nice video of the demo can be seen here [video](https://www.gctronic.com/doc/index.php/Wheelphone-videos#Wheelphone_navigation_and_automatic_docking_with_markers_with_iPhone). - the iOS application can be downloaded from the [App Store](https://itunes.apple.com/us/app/wheelphone-markers-navigation/id949865537?mt=8). - the source code is available from the following repository: ``` svn checkout https://github.com/gctronic/wheelphone-applications/trunk/ios-applications/WPMarkersNavigation WPMarkersNavigation -read-only ``` A similar application was developed also for Android phones, have a look [here](https://www.gctronic.com/doc/index.php/Android_software#Wheelphone_markers_navigation) for more information. --- # Wheelphone-images Source: https://www.gctronic.com/doc/index.php?title=Wheelphone-images Last edited: 2026-04-22T09:45:49Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) | wheelphone-front-view.jpg | wheelphone-alone.jpg | wheelphone-iphone3.jpg | | --- | --- | --- | | wheelphone-iphone4.jpg | wheelphone-fleet.jpg | wheelphone-iphone4-app.jpg | | wheelphone-full-package.jpg | wheelphone-left-side3.jpg | wheelphone-left-side2.jpg | --- # Wheelphone-videos Source: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos Last edited: 2018-02-28T08:52:34Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) #### Wheelphone robot capabilities Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_robot_capabilities [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone navigation and automatic docking with markers Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_navigation_and_automatic_docking_with_markers [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone navigation and automatic docking with markers with iPhone Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_navigation_and_automatic_docking_with_markers_with_iPhone [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone automatic docking with marker Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_automatic_docking_with_marker [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone robot telepresence with Skype (**iPhone** and **Android**) Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_robot_telepresence_with_Skype_(iPhone_and_Android) [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Simulation of wheelphone in Webots Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Simulation_of_wheelphone_in_Webots [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone following a color blob, based on OpenCV Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_following_a_color_blob,_based_on_OpenCV [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone follows an apple Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_follows_an_apple [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone follows his Lord Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_follows_his_Lord [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Remote control with ROS Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Remote_control_with_ROS [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### Wheelphone overcomes obstacles Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#Wheelphone_overcomes_obstacles [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) #### iWheel project Link: https://www.gctronic.com/doc/index.php?title=Wheelphone-videos#iWheel_project [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) --- # Wheelphone technical specifications Source: https://www.gctronic.com/doc/index.php?title=Wheelphone_technical_specifications Last edited: 2026-04-22T09:34:28Z [Wheelphone main wiki](http://www.gctronic.com/doc/index.php?title=Wheelphone) # Hardware Link: https://www.gctronic.com/doc/index.php?title=Wheelphone_technical_specifications#Hardware The following figure shows the main components of the Wheelphone robot and where they are physically placed: ![wheelphone-schema.jpg](https://www.gctronic.com/doc/images/b/bd/wheelphone-schema.jpg) # Detailed features Link: https://www.gctronic.com/doc/index.php?title=Wheelphone_technical_specifications#Detailed_features | **Feature** | **Technical information** | | --- | --- | | Size, weight | 92 mm width, 102 mm length, 68 mm height, 200 g | | Battery, autonomy | LiPo rechargeable battery (1600 mAh, 3.7 V). About 3.5 hours autonomy (motors running at middle speed continuously). Recharging time about 1h45 | | 2 options to charge | with a micro USB female connector in front of the robot, 500mA with 2 golden contacts in front and the relative docking station, 1000mA | | Processor | Microchip PIC24FJ64GB004 @ 16MHz (8 MIPS); 16 bit microcontroller ... and the one of the phone | | Memory | RAM: 8 KB; Flash: 64 KB ... and the one of the phone | | Motors | 2 DC motors with gear; speed controlled (forward direction) with backEMF | | Speed | Max: 30 cm/s | | Mechanical structure | Molded plastic case, adaptable phone holder | | IR sensors | 4 infra-red sensors measuring ambient light and proximity of objects up to 6 cm (placed on the front-side of the robot) 4 ground sensors detecting cliffs or color differences (placed on the bottom-front-side of the robot) | | LEDs | 1 red/green LED (charging/charged indicator) | | Communication | Android: USB high speed; iPhone: sound cable. Both reaches 20 Hz sensor refresh | | Additional connectors | 1 USB connector (type A) as alternative to the micro USB cable | | Programming | Android SDK, iOS SDK | ======================================================================== TOPIC: RGB Panel RGB panel extension, compatible with both e-puck and e-puck2. Check which robot a statement refers to. ======================================================================== # RGB Panel Source: https://www.gctronic.com/doc/index.php?title=RGB_Panel Last edited: 2026-04-22T12:08:03Z # Overview Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Overview The RGB panel is a new module designed to be suitable for the e-puck robot. It is comprised of: - 9 RGB LEDs - 8 infrareds - [PIC18F6722 microcontroller](https://www.microchip.com/wwwproducts/Devices.aspx?dDocName=en010316) ([datasheet](https://ww1.microchip.com/downloads/en/DeviceDoc/39646c.pdf)) Every LED is independent from each other, so it's possible to turn on the LEDs with different colors in the RGB color space (additive color mixing), as shown in the following figures. ![RGBpanel1.png](https://www.gctronic.com/doc/images/b/be/RGBpanel1.png) ![RGBpanel2.png](https://www.gctronic.com/doc/images/5/5a/RGBpanel2.png) ![Rgb-panel1.jpg](https://www.gctronic.com/doc/images/8/8c/Rgb-panel1.jpg) ![Rgb-panel2.jpg](https://www.gctronic.com/doc/images/1/13/Rgb-panel2.jpg) The infrareds are thought as identification sensors, this means that the robots can be recognized by an external device such as a camera observing their combination of infrareds turned on and off; for instance using 8 IRs it's possible to identify 256 different robots. The communication between the e-puck and the module is via the I2C bus. Color commands are sent from the robot to the RGB panel (nothing is sent in the opposite way); this let us, for example, program the robot with a pre-fixed sequence of commands to send to the panel, resulting in a color animation. Other more elaborate demos could be implemented, reacting for example to the environment and nearby robots. Another possibility is to develop a demo running on a computer and connecting the computer to the e-puck through Bluetooth (the e-puck and the module are connected through I2C as before); in practice the robot receives commands from the PC and forwards them to the RGB panel. This forwarding is implemented in the e-puck firmware, presented afterwards. # Electrical schema Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Electrical_schema The circuit diagram of the rgb panel e-puck extension is available to the community on the following link [electrical schema](https://projects.gctronic.com/rgb-panel/rgb-ext-electrical-schema.pdf). # Software Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Software ## E-puck firmware Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#E-puck_firmware In order to play with the RGB extension for the e-puck robot you need to load the official e-puck firmware and set the selector on position 3 (advanced sercom protocol), refer to section [E-Puck Standard firmware](https://www.gctronic.com/doc/index.php/E-Puck#Standard_firmware). Basically the firmware contains a command to setup the color of each led and the state of each infrared sensor; in particular there are two commands (binary mode): 'W' and 'w'; the first one is used to set a single led or infrared sensor, the second is used to set all actuators at once. ## RGB panel firmware Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#RGB_panel_firmware Also the module requires a firmware running on it in order to handle the I2C communication and interpret the commands needed to turn on and off the sensors and color leds. The firmware can be downloaded from the following links ([panel-MPLAB](https://projects.gctronic.com/rgb-panel/panel-firmware.zip), [panel-hex](https://projects.gctronic.com/rgb-panel/panel-firmware.hex)). ## Demo - PC side Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Demo_-_PC_side A basic demo running on a computer was developed to control manually all the LEDs color and IRs state through a Bluetooth connection. The application is implemented with [Qt](https://www.qt.io/download). A snapshot of this demo is shown hereafter: ![LEDTurretDemo.png](https://www.gctronic.com/doc/images/a/a4/LEDTurretDemo.png) [Download RGB Panel Basic Demo (Multiplatform)](https://www.gctronic.com/doc/images/LEDsTurret1.7.zip), built with Qt-5.10.1. ## e-puck2 Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#e-puck2 To play with the e-puck2 robot and RGB extension you can run the same [PC side application](https://www.gctronic.com/doc/index.php?title=RGB_Panel#Demo_-_PC_side) that is used with the e-puck1. In this case the e-puck2 robot must be programmed with the [factory firmware](https://www.gctronic.com/doc/index.php?title=e-puck2#Factory_firmware) and the selector must be placed in position 3. A Python example is also available in the following link [set_rgb_panel.py](https://projects.gctronic.com/epuck2/set_rgb_panel.py) in order to control the RGB panel from the computer via Bluetooth. Beware that in order to change the selector postion, **both the e-puck2 and RGB panel must have the selector in the same position**, this means that if you want the position 3 selected, then both the selector of the robot and the selector of the RGB panel must be placed in position 3. If you want to control the RGB extension directly from the e-puck2, then you can do it by using the I2C bus (see chapter [Registers](https://www.gctronic.com/doc/index.php?title=RGB_Panel#Registers)). An example is provided to help you getting started, have a look at the following repository . # Programming Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Programming ## Registers Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Registers The LEDs and IRs are controlled by writing appropriate registers; the value within the registers represents the duty cycle that a LED/IR will reach, that is its brightness. The following table shows the registers used to configure the various LEDs and IRs. > | X | RedX | BlueX | GreenX | IRX | > | --- | --- | --- | --- | --- | > *Parameter registers* > > | 0 | 0x00 | 0x08 | 0x10 | 0xA4 | > | --- | --- | --- | --- | --- | > | 1 | 0x01 | 0x09 | 0x11 | 0xA5 | > | 2 | 0x02 | 0x0A | 0x12 | 0xA6 | > | 3 | 0x03 | 0x0B | 0x13 | 0xA7 | > | 4 | 0x04 | 0x0C | 0x14 | 0xA8 | > | 5 | 0x05 | 0x0D | 0x15 | 0xA9 | > | 6 | 0x06 | 0x0E | 0x16 | 0xAA | > | 7 | 0x07 | 0x0F | 0x17 | 0xAB | > | 8 | 0x92 | 0x93 | 0x94 | - | ## Example Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Example The RGB panel can be controlled through either ASCII or binary commands. The following example illustrates the sequence of commands that must be issued to turn on the LED0 at maximum brightness (all 3 R,G and B at maximum) using a terminal and the e-puck programmed with the standard firmware: ``` W, 176, 0, 128 [set red led0 max] W, 176, 8, 128 [set blue led0 max ] W, 176, 16, 128 [set green led0 max] W, 176, 145, 1 [set command register (command terminator)] ``` where in the first line *W* is the command (I2C write), *176* is the I2C address of the RGB panel (fixed), *0* is the register address and *128* the brightness value. The last line contains a special command that is sent to the module when it's required to update the LEDs and IRs with the new values; this means that even if the first command is sent to the RGB panel, nothing will change until the last command is sent. The binary version (a bit faster), using the *-w* command, of the previous sequence is: ``` ... init communication ... sprintf(buffer, 5, "%c%c%c%c",-‘W’, 176, 0, 128); sprintf(&buffer[5], 5, "%c%c%c%c",-‘W’, 176, 8, 128); sprintf(&buffer[10], 5, "%c%c%c%c",-‘W’, 176, 16, 128); sprintf(&buffer[15], 5, "%c%c%c%c",-‘W’, 176, 145, 1); ... send buffer ... ``` # Videos Link: https://www.gctronic.com/doc/index.php?title=RGB_Panel#Videos [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) The robot changes color basing itself on what his small camera sees, just like a real chameloen. This system is based on the standard e-puck on the bottom, the new 3x3 RGB display on top and a proper demo. You can download the source code of this demo in the following link [epuck-demo-chamaleon](https://projects.gctronic.com/rgb-panel/epuck-demo4.zip). [Video](https://www.youtube.com/howyoutubeworks/user-settings/privacy/) Artistic pattern formation with multiple robots.