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

From GCtronic wiki
Jump to: navigation, search
(Communication with main microcontroller)
(Controlling the robot)
(19 intermediate revisions by the same user not shown)
Line 23: Line 23:
  
 
=Communication with main microcontroller=
 
=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 received all sensors data and send commands.<br/>
+
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.<br/>
The UART communication protocol is based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol] and are compatible with e-puck1.x.<br/>
+
The UART communication protocol is based on the [http://www.gctronic.com/doc/index.php/Advanced_sercom_protocol advanced sercom protocol].<br/>
  
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 you can have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 WiFi communication protocol section]:
+
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 [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 WiFi communication protocol section]:
 
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
 
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-robot-to-pc.jpg">]</span><br/>
  
The following figure shows the packet format to send to the main microcontroller via UART. For more information about the values of each field you can have a look at the [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 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 [https://www.gctronic.com/doc/index.php?title=e-puck2_PC_side_development#WiFi_2 WiFi communication protocol section]:
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-esp-to-f407.png <img width=1150 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-esp-to-f407.png">]</span><br/>
+
<span class="plain links">[http://projects.gctronic.com/epuck2/wiki_images/packet-format-esp-to-f407.png <img width=700 src="http://projects.gctronic.com/epuck2/wiki_images/packet-format-esp-to-f407.png">]</span><br/>
 +
 
 +
==Implementation==
 +
Refer to the [https://www.gctronic.com/doc/index.php?title=e-puck2_radio_module_development#WiFi WiFi branch] of the radio module firmware as implementation reference.<br/>
 +
The UART communication is implemented in the <code>uart_e-puck2.c</code> (separated task). First of all you need to initialize the channel with <code>uart_init();</code>, then you can exchange data by using the functions <code>uart_set_actuators_state</code> and <code>uart_get_data_ptr</code> to respectively send commands to the robot and receive sensors information.
  
 
=Example projects=
 
=Example projects=
Line 75: Line 79:
 
# clone the COVID-19 example repository into the <code>examples</code> directory of the <code>ESP-IDF</code> by issueing the command <code>git clone https://github.com/e-puck2/COVID-19.git</code>
 
# clone the COVID-19 example repository into the <code>examples</code> directory of the <code>ESP-IDF</code> by issueing the command <code>git clone https://github.com/e-puck2/COVID-19.git</code>
 
# move to the directory <code>esp-idf/examples/COVID-19/esp32_covid</code> and issue the command <code>idf.py build</code> to build the project, beware that you need to set up the environment variables (refer to [https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#step-4-set-up-the-environment-variables step-4-set-up-the-environment-variables])
 
# move to the directory <code>esp-idf/examples/COVID-19/esp32_covid</code> and issue the command <code>idf.py build</code> to build the project, beware that you need to set up the environment variables (refer to [https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#step-4-set-up-the-environment-variables step-4-set-up-the-environment-variables])
# once the project is built, take the files <code>build/esp32_covid.bin</code>, <code>build/bootloader/bootloader.bin</code> and <code>build/partition-table/partition-table.bin</code> and follow the instructions in the following link [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
+
# once the project is built, take the files <code>build/esp32_covid.bin</code>, <code>build/bootloader/bootloader.bin</code> and <code>build/partition-table/partition-table.bin</code> and follow the instructions in the following link [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 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
 +
 
 +
==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===
 +
For running the demo you need to:
 +
* program the main microcontroller with the [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update factory firmware] and place the selector in position 15
 +
* program the radio module with the following firmware [http://projects.gctronic.com/epuck2/esp32_robot_control_17.02.21_aa84b65.zip esp32_robot_control.zip (17.02.21)], refer to section [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 Radio module - Firmware update] for more information on how to flash the radio module
 +
 
 +
===Building===
 +
In order to build the projet, follow these steps:
 +
# install the toolchain for your OS, refer to [http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain http://esp-idf.readthedocs.io/en/latest/get-started/#setup-toolchain]
 +
# clone the <code>ESP-IDF</code> (ESP32 framework) repository by issueing the command <code>git clone --recursive https://github.com/espressif/esp-idf.git</code>
 +
# clone the <code>esp32_robot_control</code> example repository into the <code>examples</code> directory of the <code>ESP-IDF</code> by issueing the command <code>git clone https://github.com/e-puck2/esp32_robot_control.git</code>
 +
# move to the directory <code>esp-idf/examples/esp32_robot_control</code> and issue the command <code>idf.py build</code> to build the project, beware that you need to set up the environment variables (refer to [https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#step-4-set-up-the-environment-variables step-4-set-up-the-environment-variables])
 +
# once the project is built, take the files <code>build/esp32_robot_control.bin</code>, <code>build/bootloader/bootloader.bin</code> and <code>build/partition-table/partition-table.bin</code> and follow the instructions in the following link [https://www.gctronic.com/doc/index.php?title=e-puck2#Firmware_update_2 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

Revision as of 09:42, 17 February 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 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.1.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.1.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.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 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.2 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.2.1 Preparation

For running the demo you need to:

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