Difference between revisions of "e-puck2 radio module development"

From GCtronic wiki
Jump to: navigation, search
(Usage)
(Usage)
Line 47: Line 47:
  
 
===Usage===
 
===Usage===
There are 2 roles available for the demo, the root node and childs node (can also be parent of others 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 http://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png): if the button is pressed while turning on the robot then this the root node, otherwise this a child node. Beware to have only one root.<br/>
+
There are 2 roles available for the demo, the root node and childs node (can also be parent of others 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 http://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png): if the button is pressed while turning on the robot then this the root node, otherwise this a child node. Beware to have only one root. <br/>
 
Once the robots are turned on they will build a network by themselves: the robot will blink  
 
Once the robots are turned on they will build a network by themselves: the robot will blink  
 
You can have a look at the following video as an example:
 
You can have a look at the following video as an example:

Revision as of 09:00, 24 August 2021

e-puck2 main wiki

1 Introduction

Espressif provides the Espressif IoT Development Framework (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.

2 Development environment

In order to build the firmware you need to install the toolchain for your OS, refer to http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain.
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 http://esp-idf.readthedocs.io/en/latest/get-started/#build-and-flash.

2.1 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 to know what ports are availables).

3 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

3.1 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

4 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.

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:

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:

4.1 Implementation

Refer to the WiFi branch 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.

5 Example projects

5.1 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 https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/esp-wifi-mesh.html.

5.1.1 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), refer to section Radio module - Firmware update 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.

5.1.2 Usage

There are 2 roles available for the demo, the root node and childs node (can also be parent of others 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 http://projects.gctronic.com/epuck2/wiki_images/epuck2-components-position.png): if the button is pressed while turning on the robot then this the root node, otherwise this a child node. Beware to have only one root.
Once the robots are turned on they will build a network by themselves: the robot will blink You can have a look at the following video as an example:

5.1.3 Building

In order to build the radio module firmware, follow these steps:

  1. install the toolchain for your OS, refer to http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain
  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). 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 to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names

5.2 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 (no actual code used from this repo).The following image shows a general overview of the architecture:

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)

5.2.1 Preparation

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:

On the computer you need to install Python 3 in order to run the server script that you can download from here server.py.
Prepare an arena big enough to contain all the robots that will move around avoiding obstacles once turned on.

5.2.2 Usage

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
  • 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 then turn it on (the robot must be turned on with the selector in position 15); 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 then turn it on (the robot must be turned on with the selector in position 15); 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; 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
  4. Take the robot chosen to be a no-DP-3T actor; put the selector in position 15 then turn it on (the robot must be turned on with the selector in position 15); 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; 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:

The following state diagrams illustrate the details of the simulation; you can analyze them to deeply understand what is happening for each role.

5.2.3 Building

In order to build the radio module firmware, follow these steps:

  1. install the toolchain for your OS, refer to http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain
  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)
  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 to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names

5.3 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.

5.3.1 Preparation

For running the demo you need to:

5.3.2 Building

In order to build the projet, follow these steps:

  1. install the toolchain for your OS, refer to http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain
  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 esp32_robot_control example repository into the examples directory of the ESP-IDF by issueing the command git clone https://github.com/e-puck2/esp32_robot_control.git
  4. move to the directory esp-idf/examples/esp32_robot_control 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)
  5. 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 to flash the radio module; beware that you need to change the programming script in order to reflect the correct file names