Code-O-Soccer

User Manual

15th October 2012

Contents
1 Introduction 2 Installation and Setup 2.1 Windows . . . . . . . . . 2.2 Linux . . . . . . . . . . . 2.2.1 Installing Ubuntu . 2.2.2 Code Setup . . . . 3 The Robots 4 Architecture 5 Getting Started with Tactics 5.1 Introduction . . . . . . . . . . 5.2 Tactic and Tactic Parameter 5.3 Tactic Usage . . . . . . . . . 5.4 Make your own Tactic! . . . . 6 Belief State 6.1 Introduction . . . . . . . . . 6.2 State Parameters . . . . . . 6.3 Predicates . . . . . . . . . . 6.3.1 High level Predicates 6.3.2 Referee Commands . 2 2 2 2 2 2 3 4 5 5 5 6 8 9 9 10 10 10 11 12 12 12 12 12

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

7 Coordination Among Robots 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 Plays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Conclusion 9 Further Help

Introduction

This is a framework that denes an API for writing Strategy for autonomously playing three-a-side Robot Soccer. This user manual aims to make the user familiar with the API to develop code that runs the robots to play robot soccer. Code-O-Soccer API supplies a set of components that allows the user to write High-Level Strategy code and converts this to Low-Level commands for the robots. It also enables the user to implement coordination among robots playing soccer through use of a world model describing the robot states in the football eld.

2
2.1

Installation and Setup

Windows

Currently, Code-O-Soccer API is not available for windows. However, we are still trying to get it up and running and will post updates if and when it is made available.

2.2
2.2.1

Linux
Installing Ubuntu

For those who do not already have linux install, we recommend installing Ubuntu through wubi. Please refer to the following link for complete installation instructions: https://wiki.ubuntu.com/WubiGuide 2.2.2 Code Setup

Once you have a ubuntu set up, download the code archive from : https://github.com/downloads/jaigupta/CodeOSoccer/CodeOSoccer_32bit.tar.gz To install CodeLite: 1. Go to http://sourceforge.net/projects/codelite/files/Releases/codelite-3.5/ 2. Select codelite_3.5.5375-ubuntu0_i386.deb from the list. This will initiate the download. 3. Double click on the downloaded .deb le to start installation. Commands (Run in Terminal): 1. cd <Download-directory>/ 2. tar -xvf CodeOSoccer_32bit.tar.gz 3. cd CodeOSoccer_32bit/ 4. sudo bash setup.sh Open RobocupSSL.workspace using Codelite. The CodeOSoccer project will be opened in the workspace.

 Build the project using Codelite build

button.

Run simulator from the extracted folder to run grSim.

Run the code using Run

button from codelite.

You should see three robots of the blue team moving into a formation and then stopping.

The Robots

The robots used, both in the simulator and real-world matches, are omni-directional robots. This means that the robot has 3 degrees of freedom, and can move in any direction in its plane without having to turn. The simulator has 4-wheeled omni-robots, while the physical robots are 3-wheeled. Fig 1 shows the robots used in the Simulator. The center-circle identies the team of the robot, either blue or yellow. The magenta and green circles form a pattern, which is distinct for each 3

Figure 1: Top View of Simulator Robot robot and is used by the vision module for identication of robots The robots feature a dribbler and a solenoid kicker. The dribbler rotates in a backward direction, essentially capturing the ball with friction and allowing the robot to move backwards with the ball. The kicker can kick the ball upto the speed of 10m/s. Its power setting is adjustable. Robot controls for translation velocity, angular velocity, dribbler on/o and kicker power are all provided in the API. These will be explained alongside tactics in more detail. Fig 2 shows the actual 3-wheel robot.

Figure 2: 3-Wheel Robot

Architecture

The functioning of a generic program created through the CodeOSoccer API is shown in Fig 3. The Vision Module reads from a camera and provides robot locations. These are sent to the Belief State module which populates a world model. This data is provided to the Strategy code. The Skills and Tactics layers are high level abstractions for controlling the robots. They output lowlevel commands to be executed by the on-board microcontrollers of the robots. These commands are communicated wirelessly to the robots. A Referee Box also operates simultaneously, and sends referee commands such as Free Kick, Goal etc. to the Strategy code from time to time. This information is interpreted and updated in the Belief State for use by the Skill and Tactic layers. The Referee Box is not essential for running the robots.

Figure 3: Code Architecture

In the Code-O-Soccer API, source code to most of these abstraction layers (eg. Vision module, Skills) is hidden from the user. Furthermore, the Vision Module and actual robots are replaced by a Simulator (grSim) to allow the user to test his code. The user only needs to interact with the Tactic Layer and the Belief State world model to write high-level strategies. The same code, with some minor changes, may also be run on the actual robots. The following sections explain the Tactic Layer and the Belief State world model, and how the user must write code which complies with the API to run the robots on the simulator.

5
5.1

Getting Started with Tactics

Introduction

Tactics are the topmost level of single-robot control. Each tactic encapsulates a single-robot behavior. Each tactic is parameterized, allowing for more general tactics to be created which are applicable to a wider range of world states. For example, a Velocity tactic would have speed and direction as parameters, and a Shoot tactic would have kick strength as a parameter. Some tactics are simple in functioning (eg. Velocity tactic simply gives a translational and rotational velocity to the robot) while others have more complex functions (eg. KickToGoal makes the robot move toward the ball and then kick it towards the goal).

5.2

Tactic and Tactic Parameter

Table 5.2 provides a list of important tactics implemented in the API. For a list of all tactics and their implementations, please refer to the documentation of tactic.h as well as headers of individual tactics.

Tactic Block Command Defend DefendLine DefendPoint GoalieOur KickToGoal MarkBot

Position Steal Stop Velocity

Description Defend the goal a particular distance from the goal Sends users command directly to bot Defend the ball from coming to our side Defend the ball from crossing a particular line on the eld Defend the ball from a particular point on the eld A special tactic just for the goalie for our side Moves toward the ball and kicks it to the goal. Mark an opponent preventing them from getting the ball, getting to the goal, blocking a shot Go to the given position Manipulate the ball to remove possession of it from another robot Stop the bot Move at a xed velocity

Tactic Parameter TBlockP TCommandP TDefendP TDefendLineP TDefendPointP TDefaultP TKickToGoalP TMarkBotP

TPositionP TDefaultP TDefaultP TVelocityP

As mentioned before, each tactic has its own parameter. For example, the Velocity tactic uses the parameter TVelocityP. The members of TVelocityP are : v_x(lateral speed), v_y(forward speed) and v_t(angular speed). In general, the parameter of a tactic xxx is given by TxxxP, and has relevant members. The header le tparamlist.h describes parameters for each tactic and their members. Please refer to the documentation for the complete list of tactic parameters.

5.3

Tactic Usage

We now describe how to use tactics. Open the RobocupSSL workspace in CodeLite. The CodeOSoccer project will be set as active.

The startgame call is necessary to start the game. The second parameter may be either BLUE or YELLOW depending on the team you wish to play as. From the workspace view on the lefthand-side, open the le bot.cpp from src folder.

bot_execute.h contains denitions of some macros as well as all the necessary headers. The void run_bot(MyBot*, BeliefState*) function is the primary function to be used. The function is called repeatedly in a main while(1) loop. All the user code for robot control should be called in this function. We now go into a line-by-line analysis of the function. void run_bot(MyBot* bot, BeliefState *state) { MyBot is a class which essentially denes the tactics that may be used by each bot. The user need not go into the specics of this class. It is sucient to know that a single of copy of a MyBot object (which is passed to the function) should be maintained throughout. BeliefState is a class that denes the world model of the football eld. An object of this class contains information about the positions, orientations and velocity of all the robots, position and velocity of the ball, eld conguration etc.. It also contains some predicates, which identify the game situation. These will be discussed in detail in Section 6. TPositionP param0; TPositionP is the parameter structure for the tactic Position. We dene an instance param0. param0.x = ForwardX(-1000); param0.y = 0; param0.align = false; param0.finalSlope = 0; param0.finalVelocity = 0; TPositionP object has members x, y, align, nalSlope and nalVelocity. x and y identify the coordinate to which we wish to move the bot. The ForwardX(x) macro gives the coordinate +x or -x depending on which team is playing (see eldCong.h). nalSlope is the direction which the robot should face after reaching (x,y). align species whether nalSlope should be considered. nalVelocity is the ending velocity to be given to the robot. EXECUTE_BOT(bot, 0, Tactic::Position, param0);

This statement executes a tactic on a robot. 1st parameter is the MyBot* argument. 2nd parameter is the bot ID (in this case bot 0). 3rd parameter is the tactic to be executed. In our case it is Tactic::Position. The last parameter is the tactic parameter. The user should be careful in passing the appropriate parameter type for the tactic, ie TPositionP type for Position, TVelocityP type for Velocity etc.. TPositionP param1; param1.x = ForwardX(0); param1.y = 1000; param1.align = false; param1.finalSlope = 0; param1.finalVelocity = 0; EXECUTE_BOT(bot, 1, Tactic::Position, param1); //Position tactic being executed on robot 1 TPositionP param2; param2.x = ForwardX(1000); param2.y = 0; param2.align = false; param2.finalSlope = 0; param2.finalVelocity = 0; EXECUTE_BOT(bot, 2, Tactic::Position, param2); //Position tactic being executed on robot 2 The rest of the statements in the function have similar functionality, except they are directed towards bot 1 and bot 2. Similarly, other tactics may be executed on the robots. Fore example, the following simple code would make bot 0 move forward: void run_bot(MyBot* bot, BeliefState *state) { TVelocityP param; param.v_t = 0; param.v_x = 0; param.v_y = MAX_BOT_SPEED; EXECUTE_BOT(bot, 0, Tactic::Velocity, param); //Velocity tactic being executed on robot 0 }

5.4

Make your own Tactic!

Unfortunately, due to the abstraction in the API, the user cannot directly add new Tactics among the existing ones. The user has the ability to edit existing tactics, but is strongly advised NOT to unless they are completely uent with the API as it may lead to corruption of code. Nevertheless, we have provided a special Tactic Command which allows the user to control the robots directly, and write his/her own tactic in the form a function. Command simply gives the robot a translational and rotational velocity, activates the dribbler and triggers the kicker depending on the parameters passed. TCommandP is as follows: typedef struct TCommandP { float v_x; /*Velocity x component.*/ float v_y; /*Velocity y component.*/ float v_t; /* Angular Velocity component.*/ float power; /*Power with which to hit the ball.*/ bool dribble; /*Whether dribbler is running or not.*/ 8

} TCommandP; Using this tactic the user can write his own function to move the robot. A sample function to move the robot towards the ball is as follows: void myTactic_goToBall(MyBot *bot, int botID, BeliefState *state) { TCommandP param; param.dribble = false; param.power = 0; Vector2D<int> pt(state->ballPos); //pt is now the (x,y) coordinate of the ball float motionAngle = Vector2D<int>::angle(pt,state->homePos[botID]); /* homePos[botID] is the (x,y) coordinate of [botID] robot. * motionAngle is now the angle formed between pt * and homePos[botID] vectors. */ float theta = motionAngle - state->homeAngle[botID]; //homeAngle[botID] is the orientation of [botID] robot. param.v_y = MAX_BOT_SPEED/2*cos(-theta); param.v_x = MAX_BOT_SPEED/2*sin(-theta); param.v_t = 0; EXECUTE_BOT(bot, botID, Tactic::Command, param); } It should be noted how ball position, robot position, robot orientation etc. information is extracted from the BeliefState object state (through members ballPos, homePos and homeAngle respectively). Detailed information of this class and its members is given in Section 6. Also, Vector2D template class is dened in geometry.hpp for the convenience of the user. It contains basic operations related to 2D Vectors. The eld coordinates, robot coordinates, ball coordinates etc. are expressed as 2D Vectors only. Now with this function dened, the run_bot function to make all 3 robots move towards the ball would look like: void run_bot(MyBot* bot, BeliefState *state) { myTactic_goToBall(bot, 0, state); myTactic_goToBall(bot, 1, state); myTactic_goToBall(bot, 2, state); } Now we shall look into the BeliefState class and how to use its predicates.

6
6.1

Belief State
Introduction

As mentioned before, Belief State denes the world model of the football eld. It contains information about the positions, orientations and velocity of all the robots, position and velocity of the ball, eld conguration etc.. These will be called State Parameters. Additionally, it contains certain perceived information of the game: which team is in possession of the ball, is in attack, is in a particular role etc.. These are called High-Level Predicates. There are also predicates that contain Referee Commands which are given to the code in case of special circumstances, eg. Free Kick, Goal etc..

6.2

State Parameters

Table 6.2 shows a list of state parameters present in BeliefState class and their use. State Param Point2D<int> Point2D<int> Vector2D<oat> Vector2D<oat> oat oat oat Point2D<int> Vector2D<oat> Vector2D<oat> oat oat oat Point2D<int> Vector2D<oat> Vector2D<oat> Description Array which stores home team members positions. Stores eld centre coordinates. Array which holds our bots velocity components Array which holds our bots acceleration components. Array which holds angle of each bot with respect to positive x axis. Array which holds our team members angular velocity. Array which holds our team members angular acceleration. Array which stores opponent team members positions. Array to hold opponent bots velocity components. Array to hold opponent bots acceleration components. Array which holds angle of each opponent bot with respect to positive x axis. Array to hold opponents team members angular velocity. Array to hold opponents team members angular acceleration. Holds position of ball at that time. Holds velocity of ball at that time. Holds accleration of ball at that time.

homePos[HomeTeam::SIZE] eldCentre homeVel[HomeTeam::SIZE] homeAcc[HomeTeam::SIZE] homeAngle[HomeTeam::SIZE] homeOmega[HomeTeam::SIZE] homeAngAcc[HomeTeam::SIZE] awayPos[HomeTeam::SIZE] awayVel[HomeTeam::SIZE] awayAcc[HomeTeam::SIZE] awayAngle[HomeTeam::SIZE] awayOmega[HomeTeam::SIZE] awayAngAcc[HomeTeam::SIZE] ballPos ballVel ballAcc

The run_bot function is passed a BeliefState object state. This BeliefState object is continually updated in the background. The State Parameters can be accessed through this object. For example, (x,y) coordinate of the 2nd (0 base indexing) robot of opponent team can be accessed from state->awayPos[2].

6.3

Predicates

As mentioned before, there are two types of predicates: Referee Commands and High-level Predicates. We briey describe both types of predicates. 6.3.1 High level Predicates

Table 6.3.1 shows a list of high-level predicates. Predicate int int bool bool bool bool bool bool bool bool bool bool ourBotNearestToBall oppBotNearestToBall pr_ball_in_our_dbox pr_ball_in_opp_dbox pr_oppBall pr_ourBall pr_looseBall pr_ballOppSide pr_ballOurSide pr_ballMidField pr_ballInOurCorner pr_ballInOppCorner Description Holds botid of our bot nearest to ball. Holds botid of opponent bot nearest to ball. True when ball in our D box. Computed in computeBallInDBox(). True when ball in opponent D box. Computed in computeBallInDBox(). True when ball is with opponent. True when ball is with us. True when no one possesses the ball. True when ball is in opponent half. True when ball in our half. True when ball is in region dened as mideld. True when ball in our corner . Predicate true when ball in opponent corner.

10

All predicates (with the exception of ourBotNearestToBall and oppBotNearestToBall) are boolean variables. Again, the BeliefState object passed to run_bot is continually updated in the background, and hence the predicates are being re-evaluated in the background. The following is an example of using predicates to change the tactic executed by robot 0: void run_bot(MyBot* bot, BeliefState *state) { if(!state->pr_oppBall) { TKickToGoalP param0; param0.power = 7; EXECUTE_BOT(bot, 0, Tactic::KickToGoal, param0); //KickToGoal Tactic being executed by robot 0 } else { TDefaultP param0; EXECUTE_BOT(bot, 0, Tactic::GoalieOur, param0); //GoalieOur Tactic being executed by robot 0 } } When the ball is not in the opponents possession, robot 0 is instructed to go towards the ball and kick it towards their goal. However, if it is in the opponents possession, robot 0 becomes a goalkeeper. 6.3.2 Referee Commands

Table 6.3.2 shows a list of referee commmand predicates. Predicates int int int bool bool bool bool bool bool bool bool bool ourGoalCount oppGoalCount timeRemaining pr_gameHalted pr_gameRunning pr_ourGoalKick pr_oppGoalKick pr_ourFreeKick pr_oppFreeKick pr_goalscored pr_ourGoal pr_oppGoal Description Integer type variable to hold our goal count. Integer type variable to hold opponent goal count. Integer type variable to hold time remaining for the half to end. Boolean type variable to halt play. Boolean type, true when game running. Boolean type, true when our goal kick. Boolean type, true when opponents goal kick. Boolean type, true when our free kick. Boolean type, true when opponents free kick. Predicate for goal scored. Boolean type, true when our Goal scored. Boolean type, true when opp Goal scored.

All predicates (with the exception of GoalCount and timeRemaining) are boolean variables. In normal play, the referee box would not send any commands to change these predicates (except timeRemaining predicate). However, in special circumstances, the user must be able to handle these commands. Like state parameters, these predicates can be accessed through the BeliefState object passed to run_bot.

11

7
7.1

Coordination Among Robots

Introduction

The prime goal of a soccer strategy is to be able to coordinate among dierent robots. This is not possible at the Tactic level, since it encodes single-robot behaviour. Hence an abstraction above the Tactic layer is required. Full description of such an abstraction is outside the scope of this manual. However, we provide a brief introduction to a multi-robot control strategy called a Play.

7.2

Plays

Plays form the highest level in the control hierarchy providing strategic level control of the entire team. Plays encode how the team of robots should coordinate their execution of tactics in order to achieve the teams overall goals. A play is multi-agent plan and hence contains certain role assignments for each of the team members. The design of a play architecture should aim for the following: 1. Coordinated team behaviour. 2. Inclusion of special purpose behaviour for special circumstances. 3. Ease of human design and augmentation. 4. Ability to exploit short term opportunities.

Conclusion

We have provided a detailed description with working example of building code in the Code-OSoccer API. A complete knowledge of all that is covered in this manual is not necessarily required by the user to build his/her code. Specically, sections on Referee Commands and Plays may be skipped without harm. We wish the user an enjoyable experience in coding for Code-O-Soccer!

Further Help

The complete documentation is available at doc.krssg.in. If you have any doubts, feel free to post them on our forum discuss.krssg.in.

12