Project of Fall 2024: "Capture and defend the flags game"

Mindstorms NXT(TM)/EV3 robots are robots made of a main unit and a set of sensors and actuators. They have been sold by Lego for several few years now, starting with the NXT version, and now with the ev3 version. Many very elaborate designs have been made using the standard kit (see for example "Mindstorms: Not just a kid's toy"). You may also watch interesting videos on youtube, such as a breakfast machine, marble conveyor, a car factory, a forklift truck, the "holononic drive", a rubik's cube solver, a printer, and a sumo game.

The project you will work on might not be as complex as some aforementioned systems, yet it requires spending quite a lot of design and programming time on the robot and its interfaces (sensors, actuators).

Once you have received your robot box, test your robot, motors, and sensors as soon as possible! We may be able to repair/order parts with a few weeks notice, but there is very little we can do the day before the competition.

Project description

The robot you have to build shall be the winner of a Capture and defend the flags game. This section includes a description of the game and then a specification of the robot.

Note that the rules might evolve during the next weeks until the final competition. I will always inform you whenever a rule evolves.

General description

The main objective of the game is to be the winner of a game. The winner is the robot capturing first one of the flags of the adversary robot. Capturing a flag means picking it up from the opponent's side, and releasing it in its side, at less than 10cm from its side's fence. "Releasing" means that the robot must not touch the released flag anymore, and the flag must be vertical, without touching the fence.

Scoring

Touching for the first time in a round one of the opponent's flag: 2 points.

Grabbing for the first time in a round the opponent's flag: 2 points.

Releasing the opponent's flag in the right area: 4 points (only 2 points if the flag is released on its side, one point is lost if the flag is not totally in the right area).

Wrongly entering into a forbidden area: 1 point for the opponent each time, with at most 2 points per round.

Not leaving its restricted area on time gives 2 points to the opponent.

Being the first to move our own flag ends the round. The opponent can then play a new round alone in the stadium, keeping the points it has scored in previous round.

Stadium specification

The stadium is explained in the following picture. The overall game area is delimited by a wooden fence on the four sides (see figure below). The flag itself is specified in this document. It is either red or white.

Specification of the stadium

General rules

The robot can be freely re-programmed between game rounds, but it is forbidden to remotely control your robot.

Robots have the right to release obstacles, e.g. throwing obstacles around its own flag or against the opponent robot is encouraged.

Robot must start in their designated area.

The attacking robot can contain as many obstacles as it wants when starting.

A round lasts 3 minutes. A round also ends as soon as a flag has been released in the correct area.

A robot can stay without losing point in its restricted area for at most 20 seconds after a round has started. After 20 seconds without leaving his area, the round is retsrated once. If again, the robot does not move, the game is replayed without the non moving robot. Also, if the robot successfully leaved its area on time, reentering this area without holding the opponent's flag gives points to the opponent.

Specification of the robot

The program you run should have been totally written in C.

The robot must be contained in width=30cm, length=30cm, height=35cm maximum at start-up.

Robots can use up to four sensors and up to four engines. You are free to use the sensors you want to among the following ones: touch sensor, light sensor, color sensor, ultrasonic sensor (i.e., distance sensor), compass sensor, gyroscope sensor, magnetic sensor.

The robot must contain an identifier flag (in paper), on which the number of your group is clearly readable from at least two sides of your robot. The flag dimension is at most 10x10cm. It may also contain a logo, a drawing, and the name of the robot.

A robot may change its shape (by deploying elements, or withdrawing them) during game phases.

Robots can contain a camera and send data over wifi to send out a video stream. We do not provide any camera for this, you have to do this on your own, for entertainment purpose only.

Destructive weapons are NOT allowed.

It is forbidden to send orders -remotely or not- to your robot while it is playing: it must be fully autonomous as soon as the game starts, and until it ends. Any kind of cheating will result in a 0 grade, just like for all exams at Eurecom.

Competitions and reports

There are two "competitions", as described after. Your project grade takes into account the two competitions.

Competition #1: the 7th of January, 2025: your website should be started with at least the name of your robot (I don't expect more in the website for this deadline), and you have have sent me a link to the gitlab you have setup to store source code. You can also use the gitlab as your website.

The following tests will be performed in the stadium. Tests are used to test "basic" functions in order to understand how well their work. They are not taken into account for the final grade, apart if your robot fails ion the final competition. You can validate multiple tests with one execution if you wish to. Last, your robot is tested alone in the stadium.

Test #1. Be able to pick up a flag located right in front of the robot.
Test #2. Be able to reach one of the opponent's flag from the starting point.
Test #3. Be able to pick up one of the flags from the starting position.
Test #4. Be able to bring back an opponent's flag, starting from the starting position.
Test #5. Be able to reach the opponent's flag in the presence of one obstacle on the path. This obstacle is a 15cmx15cmx15cm box. The box is placed by your favourite teacher before the test.

Final competition: the 21st of January, 2025: final competition. For the final competition, the website must be fully completed, and the gitlab up-to-date. Also, during the final competition, I may interview each member of the group, so as to understand the contribution of each group member.

Your report consists of a website (which could be integrated into your gitlab) and the source code of your robot. The website shall contain the following information:

Description of the architecture of the robot: sensors and actuators, etc. Pictures of your robot on the web site would be appreciated.

Algorithms used for the two most important points: strategy for the different rounds (attacker, defender). Don't provide source code here, just try to describe the algorithms using a pseudo C language. Also, do comment those algorithms, and explain why you think they are efficient.

Source code, and instructions on how to use that source code: how to compile it, how to download it on the robot, and how to start the robot. To protect you work, you can set a password to access to the code, but make sure to give us access in order to grade it (e.g., private git repository). You could even put a fake code on your website until the very last moment ;-). I strongly advise you to rely on a versioning system (git, hg) to work on the code. Also, frequently backup your code.

Videos / pictures of your robot in action [we may provide you with cameras and video recorders if necessary].

How you have worked in the group, i.e., who made what. Be clear about that. Each member of groups will get an individual grade. All members of a team must contribute to the source code. You source code must clearly indicate, with comments, who programmed which function.

Grading

Report: 5 points

Algorithms: 5 points

Code: 5 points

Competition (ranking): 5 points

Bonus, including test session: 2 points.

Don't forget to split the work. Also, I expect all students to work on the code, and to push in their projets's git in a regular way. A student not committing code nor being active in the project (this includes sessions of the schedule) will get a (much) lower grade than other members of the group.

Groups

(The group leader is listed first. Follows name of the other students, then the name of the robot and finally the link to the website).

Maxime SKROBALA, Hector PANABIERES. gitlab

Leonardo MOSQUEDA HERNANDEZ, Lilian VARINOT. gitlab

Matteo GHIA, khediri MOHAMED AMINE. gitlab

Sif-eddine LOUZAR

How do I borrow a robot?

Please, take care not to lose parts, especially cables and sensors. Also, a micro SD card and a wifi dongle come with the robot. The procedure to borrow a robot is as follows:

Make a group of 2 students, and decide on a group leader.
The group leader sends me an email with the list of students of the group. List of: first_name, LAST_NAME, email. The leader shall be the first student in the list.
I will validate the group. If the group is not validated for some reason I will provide, go back to stage 1. Otherwise, go to next step. Note that I validate groups with a First Come First Served policy (Date of email sent).
Once I've answered your group with "validated", the group leader can go to Marius SERRE or Tom ZENATTI's office (327), Marisu.Serre AT eurecom.fr or Tom.Zenatti AT eurecom.fr, in the IT Department. You will be granted an ev3 box. Only the group leader has the right to enter in the office of Mr Zenatti, and only during the morning or the afternoon breaks (do not go during lunch break).

Access to stadium

The stadium is located in room 52. You are free to use it whenever you want but please do take care about the arena, especially the accessories.

ev3

For the ev3 system, the idea is to flash on the provided SD card a Debian GNU/Linux system. Then, you will be able to use the C language to make your program.

Installing Linux on ev3

All information to install Linux on your ev3 is given here. This page also explains how to connect to your ev3 to your PC via the usb cable, bluetooth, or wifi.

Using and programming ev3

Connect to the EV3 by ssh

maker

$ ssh robot@192.168.2.2

robot

sudo

$ ping www.ev3dev.org

Now, update the robot with the latest packages

$ sudo apt-get update&&sudo apt-get upgrade

Install extra packages you will need for the project:

$ sudo apt-get install gcc make build-essential git

$ sudo apt edit-sources

debian stretch

deb http://archive.debian.org/debian stretch main contrib non-free
#deb-src http://archive.debian.org/debian stretch main contrib non-free

deb http://archive.ev3dev.org/debian stretch main
#deb-src http://archive.ev3dev.org/debian stretch main

$ sudo apt-get update&&sudo apt-get upgrade

You are now ready to compile a basic example, and to run it. To do so, you first need to install the development environment on the robot:

$ cd /home/robot
$ git clone https://github.com/in4lio/ev3dev-c.git
$ cd ev3dev-c
$ git submodule update --init --recursive
$ cd source/ev3/
$ make
$ sudo make install
$ make shared
$ sudo make shared-install

Now, you need to get the example. The tester file runs all 3 motors, then tests the color, touch, sonar, and compass sensors, and is provided on the project git. You can either clone the git with the code on the robot, or on your host computer.

$ GIT_SSL_NO_VERIFY=true git clone https://gitlab.eurecom.fr/ludovic.apvrille/OS_Robot_Project_Fall2020.git
$ cd OS_Robot_Project_Fall2020/client

$ scp tester.c Makefile robot@192.168.2.2:

Then, on the robot, you can compile the example main file, and then run it. You need tachos and sensors to be connected to the brick if you want the program to correctly execute.

$ make tester

$gcc -I./ev3dev-c/source/ev3 -O2 -std=gnu99 -W -Wall -Wno-comment -c tester.c -o tester.o

$ make

$ ./tester

$ make tester

note that the code and Makefile I provide are for the version of Debian Jessie that I have installed on my robot. the code and/or Makfile may fail for your robot: in that case, try to understand the error(s) you get and accordingly adapt the Makefile or the code.

Other examples

Sample code is also provided in the ev3c-master repository. Samples of how to control the motors and sensors are included in tester.c. The Ultrasonic Sensor is described here.

If your compass sensor does not correctly work with the test_sensor program, we provide a code specific to the use of this sensor. Use the "i2c" target of the provided Makefile to compile the file.

Other examples can be downloaded from the ev3dev C library here. Examples are provided in eg/tacho and eg/sensor.

rfcomm-client.c is an example of how to communicate with the server over wifi. Compile with gcc rfcomm-client.c -o rfcomm-client.

If you can't get your robot working, bring it along to course staff.

Cross compilation

Basic

You have to compile your source code on your laptop, e.g. to check the syntax of your code and to speed up the compilation process. Indeed, if small examples are fast to compile on the robot, your final code will takes minutes to compile, maybe event 5 to 10 minutes, making it too slow to iterate on your code. This is why cross-compilation is really necessary. Cross-compilation for ev3 is available as an ev3 docker image. Here is what I've made to make this work on my Debian GNU/Linux computer:

I have first installed docker, created a docker group, added myself to the docker group, and started the docker service. Installing docker may require more than a simple apt-get, so please refer to the documentation of your OS, e.g. for the one for ubuntu

$ sudo apt-get install docker-engine
$ sudo groupadd docker
$ sudo gpasswd -a ${USER} docker
$ sudo service docker start

Then, I have installed the ev3 docker image:

$ docker pull ev3dev/debian-stretch-cross

Once done, I've created a helloworld in C:

$ cat > /tmp/hello.c
#include 

int main(int argc, const char *argv[])
{
    printf("OS is fantastic!!\n");

    return 0;
}

(do "CTRL D" at the end of this command).

I've compiled the file using the cross compiler provided within the docker image, and tested the generated file. The following command assumes that hello.c is located in /tmp on your host system (but you can place it wherever you want: update the following command accordingly). The following instructions are the one that I have used on my debian/jessie GNU/Linux PC.

$ docker run -e LOCAL_USER_ID=`id -u $USER`  --rm -it -v /tmp:/src -w /src ev3dev/debian-stretch-cross
[Shell in container]$ cd src
[Shell in container]$ arm-linux-gnueabi-gcc -o hello hello.c

$ sudo apt-get install qemu-user-static
[Shell in container]$ ./hello
OS is fantastic!!

For handling the compilation for your ev3, you need to make additional stages (thanks to Paolo!):

Tag the docker image:

$ docker tag ev3dev/debian-stretch-cross ev3cc

Install ev3 lib, put them in the project directory, and start the docker image:

$ git clone https://github.com/in4lio/ev3dev-c
$ docker run --rm -it -h ev3 -v PATH/TO/PROJECT/:/src -w /src ev3cc /bin/bash

In the container, run the following commands:

[Shell in container]$ cd ev3dev-c/source/ev3/&&make&&sudo make install&&make shared&&sudo make shared-install

your code

Another way to do

(Way suggested by Fredrik Flornes Ellertsen. Note: on our side, for the tester.c file, we had to put the exact location of included files such as ev3.h. And also we had to remove the lines that use 'ev3_brick_addr', which the compiler cannot understand)

This has been tested on native Ubuntu 17.04 and on Windows using the Windows Subsystem for Linux.

In an empty folder (here called robot_code/) on your computer, clone the ev3dev repository:

$ git clone https://github.com/in4lio/ev3dev-c

Install the cross compiler (source: https://www.acmesystems.it/arm9_toolchain):

$ sudo apt-get install gcc-arm-linux-gnueabi

In order to compile code that links to the ev3dev-c and/or other libraries, we need to use the robot's own versions of these libraries e.g. libev3dev-c.a. By linking statically we eliminate the need to install anything on the robot itself. Place these files in robot_code/libraries.

Create a Makefile to simplify the compilation process. The following example Makefile expects the project to be organized like illustrated below, but will naturally depend on the group's project:

	robot_code/
		Makefile
		ev3dev-c/
		libraries/
			libev3dev-c.a
		include/
			movement.h
			sensors.h
		source/
			movement.c
			sensors.c
			main.c