# e-puck2 — GCtronic wiki > 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. > > Generated 2026-10-08 13:11 UTC from https://www.gctronic.com/doc/index.php. Pages in this file: 8. > > 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. ## Contents - e-puck2 (https://www.gctronic.com/doc/index.php?title=e-puck2) - e-puck2 PC side development (https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development) - Advanced sercom protocol (https://www.gctronic.com/doc/index.php?title=Advanced_sercom_protocol) - Micropython API reference (https://www.gctronic.com/doc/index.php?title=Micropython_API_reference) - e-puck2 robot side development (https://www.gctronic.com/doc/index.php?title=e-puck2_robot_side_development) - e-puck2 programmer development (https://www.gctronic.com/doc/index.php?title=e-puck2_programmer_development) - e-puck2 radio module development (https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development) - e-puck2 mobile phone development (https://www.gctronic.com/doc/index.php?title=e-puck2_mobile_phone_development) --- # 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).