Help

R2D2 Simulator

Introduction

This small simulator has been developed to let people perceive the issues in developing software for controlling robots. You can control R2D2 moving in our department either manually or with JavaScript programs.
The original game has been developed by two high school students (see the Credits section) as a stage in our Medialab laboratory.

Getting Started

The compass in the upper left corner of the window can be used for manual control of the robot. You can practice with it and play to move the robot. When you place the mouse cursor in the center of the compass the robot is stopped. When you move the cursor in some direction (Up, down, left right) the robot starts moving in that direction. A direction is made available in the square angle centered on the vertical/horizontal axis (this is the reason of the small cross rotated by 45deg).
The lesson you learn by controlling manually the robot towards goals is twofold: manual control is imprecise and faulty; the global knowledge you acquire from visual perception greatly help in driving the robot to the goal.

Toolbar controls

The toolbar is composed by buttons and information about the state of the game. Buttons can be used as follows:

Display provides counters with information about the simulation. Timer is a countdown that establish the maximum amount of time available to the robot to find the goals; it is started if you press the restart button. Collisions reports how many times the robot has collided with walls so far. Pxls represents the number of pixels traversed by the robot. Goal counts how many goals have been hit since the beginning. Pts provides a measure of how well the robot is performing (essentially goals reached minus collisions).
With the SPEED control you have control on the speed of the robot. Speed ranges from 1 to 4, although the corresponding speeds are respectively 1, 2, 4 and 6 pixels per step. The state of this control is affected by setspeed() method that a program can use for controlling R2D2's speed.

Programming the Robot

Once you've experimented with the compass it may seem that writing a program controlling the robot is an easy task. So you are ready now to discover the truth.
The essential loop performed by a software agent (i.e. a program that acts proactively in the environment in which it is situated) is perception (i.e. read sensors) and then action (i.e. send commands to the actuators like motors).
In this simulator R2D2 can percept only walls, and the goal.

R2D2 API

With R2D2 API you can control robot's movements with moveup(), movedown(), moveleft(), and moveright(). R2D2 can also control its own speed by using the setspeed(s) where s is a value ranging from 1 to 4.
Perception is mainly performed through sensewalls() and sensegoal(). The former function returns an integer that is a bitmask of values. This is because R2 may sense more than a wall at once. You can use the following constants to test the returned value:

NOWALL

WALL_UP

WALL_DOWN

WALL_LEFT

WALL_RIGHT

For instance if R2 is in the bottom-left corner of the building the sensewalls() will return the value

WALL_DOWN | 
	 WALL_RIGHT

. The sensegoal returns true if a goal has been hit. Beware that when you call this function the inside flag is reset so if you call it twice the first time it returns true and the second time false!
You can use debugout() function to write strings at the bottom of the editor window. This is useful to print values and debug your program.

How to program R2?

You use the JavaScript programming language to express a step of the perception/action loop of the robot. You can find several tutorial on the Internet about JavaScript so we don't add another one here. Anyway we describe the basics so that you can play with the game.
Variables are introduced using the var keyword. You can assign values to variables using '='. At the right side of an assignment you can use an expression. For instance:

	 var a = 2; // Declare a with 2 as initial value
	 a = 5;     // Assign 5 to a
	 a = 6 + 7; // Assign 13 to a
	 a = a * 2; // Double a

You can test the value of an expression e using the if construct, and execute different instructions depending on the value of e. Example:

	 var direction = 1;
         if (direction == 2) {
           // Do something
         } else {
	   // Do something else
	 }

You can loop using for construct:

	 var i;
	 for (i = 0; i < 10; i++) {
           if (direction == i) {
	     // Do something
           }
	 }

The for loop initializes i to 0 and then repeats the body (with the if inside) until the condition (in this case i < 10) is satisfied. At the end of each loop the i++ is executed.
If you have to test a variable (or a value returned by a function) against several integer values you can use the switch construct:

	 switch (sensewalls()) {
	 case NOWALL:
	   // Do something
	   break;
	 case WALL_LEFT | WALL_RIGHT: // I sense both left and right walls
	   // Do something else
	   break;
	 default:
	   // In all other cases
	   break;
	 }

A simple example

The following example is the program to make R2 perform a tour of our department:

if (sensegoal())
  alert("I've hit a goal!");
switch(sensewall()) {
case NOWALL:
  moveup();
  break;
case WALL_UP:
  moveleft();
  break;
case WALL_UP | WALL_DOWN:
  moveleft();
  break;
case WALL_UP | WALL_LEFT:
  movedown();
  break;
case WALL_LEFT:
  movedown();
  break;
case WALL_DOWN | WALL_LEFT:
  moveright();
  break;
case WALL_DOWN:
  moveright();
  break;
case WALL_DOWN | WALL_RIGHT:
  moveup();
  break;
case WALL_RIGHT:
  moveup();
  break;
case WALL_UP | WALL_RIGHT:
  moveleft();
  break;
default:
  debugout("Stopped in " + sensewall());
}

Remembering things

If you want to remember something across two actions (for instance how many cycles perception/action you've been through) you should use the pre-declared variable called state. For instance if you add the following lines to the end of the previous example you display in the debug output how many times your program has been called (you can show and hide the editor window while the robot is running):

if (!state.calls) {
  state.calls = 0;
}
state.calls = state.calls + 1;
debugout("Number of calls: " + state.calls);

And now?

Now you can try to program R2 as we're doing in the real setup. As you'll soon discover programming even a simple robot like the one in this simulation isn't trivial at all! When you can use your eyes to see the goal and the map is pretty easy, but when R2 moves should keep track of its own position, otherwise how he can move in a meaningful way?
Try to program R2 to find 5 goals in less than 120 secs!
Ups! We were forgetting to tell you a little detail... If you go too fast (more than 2) your perceptions may fail to sense a wall in front of you and you may crash... So beware on what you're doing...

Known issues

The game is in it's first release. There are bugs in handling the mouse movement over the compass mainly. There are also bugs in collision detections.

Credits

Original project by Edoardo Lazzarini & Stefano Paganucci (ITIS Fermi Lucca) during their stage (5-19/12/2003) at Medialab.
Reviewed and updated by Antonio Cisternino.
All the guys of the R2D2 project have helped to create this page.

Editor