User guide to PLAYER/JADE robotic software architecture

Nils Ole Tippenhauer

August 16, 2005

Abstract
This guide will show how to execute the programs written for my research project on ”A
Multi-Robot Architecture for Autonomous Cooperative Behaviours” on the iRobot robots in
the PAMI lab using the PLAYER and JADE software. It is written for use by the researchers
working with the robots. Basic knowledge of the robots and the software used (see my project
report) is required, Linux experience definitely helpful.

Contents
1 General notes on the working environment 2

2 Robot hardware 2

3 Fedora Core 3 setup 3

3.0.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.0.2 Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.0.3 User setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

4 RobotMgr 3
4.1 RobotMgr on Min1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4.2 RobotMgr on the Magellans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5 PLAYER setup 4
5.1 Starting PLAYER server and clients . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.2 Starting PLAYER to use STAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

6 JADE setup 5
6.1 Starting JADE manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
6.2 Starting JADE using the bash scripts . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.3 Sending test messages to agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
6.4 Communication between PLAYER and JADE . . . . . . . . . . . . . . . . . . . . . 8

1
7 The PlayerAgent code 9
7.1 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.1 globalPeriod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.2 moveTimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.3 currentSpeed, currentAngle . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1.4 currentX, currentY, currentYaw . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1.5 AID[] playerAgents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1.6 HashMap agentData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

8 Immediate future work 10

8.1 PlayerAgentShadow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8.2 Adding own behaviours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.3 Remotely killing behaviours . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.4 Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

1 General notes on the working environment

I used a Linux operating system on my PC to develop the used software. I strongly suggest
this environment to make full use of client programs provided by PLAYER such as playerv, the
videoplayer program and last but not least STAGE and GAZEBO as simulators as there is no
native1 windows version of those programs. If you’re considering starting with Linux but are not
afraid of getting your hands dirty try Ubuntu Linux, I prefer Gentoo which is for a bit more
advanced users I guess (no installation assistant for example, you are basically configuring the
system by hand).

2 Robot hardware
I could not get the batteries for min2 and min3 to work, neither the spare ones. The BIOS
battery of min1 is empty so settings are reseted ever time the robot get disconnected from the
power supply. For this reason a keyboard need to be connected to min1 at the boot time and F1
has to be pressed to ignore a BIOS checksum error found. This is only the case with min1, the
magellans work fine.
The automatic shutdown via the rFlex interface/button on the robot is not powering down the
robot completely after it has been shutdown because it waits for the line ”System halted.” to
appear on the screen - which changed to a slightly different line in the newer kernels. I’m
sometimes having troubles to get the serial connection to the PTZ unit to work - but this is
solved in most of the times by rebooting/ reconnecting the hardware, the wiring is definitely OK.
1
To run Linux apps in Windows see [5] for an example

2
While I was testing PLAYER I also tried the stereo camera on min1 - it seems to work as I could
display its stream via PLAYER/videoplayer on my laptop.

3 Fedora Core 3 setup

3.0.1 General
Nothing too special about the installation, I tried to install only the minimum requirement
without the X server overhead for example to keep the image’s size small. The rights for the
serial connection had to be set, the shutdown per rFLex interface enabled as Ben describes it in
his INSTALL of the robotmgr. I’m having problems with the yum update system so I installed
most specialised packages on my own because I couldn’t find them with yum search foo. The
wireless card is managed by a special controller so its only necessary to include drivers for the
network interface, throughput is awfully slow though.
When you boot the robot it will probably try to run the redhat hardware detection to find new
devices, which is unreadable on the small screen of the robot. It will time out after 30 seconds
and continue to boot.

3.0.2 Firewall
The firewall can be modified with the Fedora tool system-configure-security. I enabled some
standard ports like HTTP (needed for JADE), ssh and ports for PLAYER and JADE.

3.0.3 User setup

Apart from the root user I added only one further user: mobility. The password for root and
mobility won’t be written here.

4 RobotMgr
4.1 RobotMgr on Min1
I didn’t try RobotMgr on the ATRVs but I assume that some changes have to be made for
it to work like on the Magellans. Like I described in my report the rFlex device uses its own
abstract units for distance and angle measurement which differ on the ATRVs and the Magellans.
PLAYER uses a variable to convert between those abstract values and the real values in mm
and degree - and those variables differ a lot between those two robot classes. This has to be
considered when using RobotMgr on the ATRVs.

3
4.2 RobotMgr on the Magellans
Because all of the libraries are in a newer version on the Fedora robots the already compiled
binaries from former projects are not running in the Fedora setup anymore and have to be re-
compiled. The two major upgrades are the change from libccgnu to libccgnu2 and RobotMgr
to RobotMgr2. Ben Miners kindly provided me versions of the Findandshoot and the RobotMgr-
Cooperation programs by Mazen and Mackram which compile on the Fedora setup - I put them
into the maze mackram folder of the mobility user.

5 PLAYER setup
5.1 Starting PLAYER server and clients
The only thing which is important for PLAYER[4] is the configuration file which is loaded when
starting it. I prepared two files, rflex.magellan and rflex.atrv for the robots with a bit
different configuration because of the devices on them. Also note that the conversion variables
for angles and distances are quite different on those robots. Those two values are not super exact
but measured experimentally and without a too high quality (due to lack of time to calibrate
everything). The only command to know for PLAYER is thus:
player rflex.magellan or player rflex.atrv
both issued in the home directory of the mobility user.
Connect to the robot with something like this from your PC:
playerv -h mag3
or using the videoplayer:
videoplayer mag3 6665 1
to connect to the compressed stream on device ”camera:1”

5.2 Starting PLAYER to use STAGE

To use the simulator the option attached to the player command is simply the name of the world
configuration file, for example:
player /usr/share/stage/worlds/everything.cfg
A GUI will show up looking like the one in figure 1, depending on the configuration file and map.
Now the PLAYER servers are simulated and listening on port 6665, 6666, 6667 etc. depending
on the amount of robots simulated. I used the modified everything.cfg which came with STAGE
as an example. I modified the map to be totally empty to have more room for the formation
and because the robots are not recognising any obstacles right now. I also modified the config
to start up 5 robots in the same coordinate which is the center of the map. This way they have
to be manually displaced before they can move, just like using the robots in real life where you
start them at the same position and move them afterwards.

4
Figure 1: Screenshot of a running STAGE GUI with a group of robots using their blobfinders to
detect the blue ghost

6 JADE setup
In this project JADE[1] is running on every robot, with one agent for each running PLAYER
server. Unless simulation is done with STAGE this means that one agent is running per JADE
container. To access the other agents on remote robots a common yellow pages server is used.
To achieve this one root container has to be started and the the other JADE installations have
to connect to this root container.
With my computer JADE was a bit picky with the DNS setup, it tries to get the local address
from the /etc/hosts on startup and will use this address as the reply-to- address for the messages
sent out by this platform. I finally got everything to work with this line in the /etc/hosts:
129.97.172.128 localhost pami-nt9.uwaterloo.ca
#127.0.0.1 localhost pami-nt9
#127.0.0.1 localhost pami-nt9.uwaterloo.ca
whereas the commented out lines are given as examples on how not to do it. This took quite
a while to find out and is not as trivial as it seems. Replace both the IP address and the DNS
name with your own data of course.

6.1 Starting JADE manually

The code for starting the root container is as following:
Java jade.Boot -gui \

5
 Figure 2: Screenshot of a running JADE GUI with connected containers and their agents

"player0:player.PlayerAgent.PlayerAgent(localhost 6665)"
if the environment is set up and you want to have the GUI (this will only work on local machines).
Now the JADE installation on the clients can connect by issuing this command:
java jade.Boot -container -host NAME OF HOST WITH MAIN CONTAINER \
"DISTINCT AGENT NAME :player.PlayerAgent.PlayerAgent(localhost 6665)"
A messages stating the new joint container will be displayed in the console of the running main
JADE container and the agent can be seen in the GUI like shown in figure 2.

6
6.2 Starting JADE using the bash scripts
I always used small bash script to fire up JADE. They usually only contain oneliners so I don’t
have to remember them...
To let JADE connect to my laptop (pami-nt9.uwaterloo.ca) I wrote this two-liner:
#!/bin/bash
java jade.Boot -container -host pami-nt9.uwaterloo.ca \
"DISTINCT AGENT NAME :player.PlayerAgent.PlayerAgent(localhost 6665)"
where DISTINCT AGENT NAME is replaced with the robot’s name to identify them easier and
\ denotes a line wrap for this document.
On my laptop I usually recompiled the Java stuff, copied it to the right place and started JADE
with multiple agents with a script like this:
#!/bin/bash
javac PlayerAgent.java
cp *.class /usr/share/jade/lib/player/PlayerAgent/
java jade.Boot -gui \
"player0:player.PlayerAgent.PlayerAgent(localhost 6665)" \
"player1:player.PlayerAgent.PlayerAgent(localhost 6666)" \
"player2:player.PlayerAgent.PlayerAgent(localhost 6667)" \
"player3:player.PlayerAgent.PlayerAgent(localhost 6668)" \
"player4:player.PlayerAgent.PlayerAgent(localhost 6669)"
in which the position of the library files should be set in the CLASSPATH and match the setup
in the Java files.

6.3 Sending test messages to agents

To send messages to the agents manually I usually use either the ”send message” icon for a single
simple message or the dummy agent as described in the JADE documentation. The dummy
agent is able to save and restore messages so complicated messages (for example with multiple
receivers) can be resent easily. The dummy agent also allows to display the answer message of
the agent which I use more to acknowledge the correct reception of the message. Figure 3 shows
a small screenshot of the most important elements of the dummy agent ready to send a message
to a group of agents. The type of message used by me so far is ”query-ref” for the simple reason
because it allows to send reply messages really easy which gives a feedback if the agents received
the message correctly - and it was used in the PingAgent example on which my code was initially
based. The update messages about the position in the final complex behaviour are of the type
”inform” because reply messages are useless in this case - and they are handled by a different
behaviour, WaitForAll. So far only those two types of messages are used and filtered out of the
incoming queue by their behaviours, so any kind of new additions can be made.

7
Figure 3: Screenshot of the dummy agent in JADE ready to send out a message to multiple
recipients

6.4 Communication between PLAYER and JADE

Sending commands to the PLAYER server from JADE is very easy using the Java-Client[3] for
PLAYER. After the client has been compiled with ant and added to the CLASSPATH it has to be
included in the JADE agent code:

import javaclient.*;
import javaclient.structures.Blob;

Then the proxy object have to be instantiated for every PLAYER interface to use. That looks
like in the following code taken from my project. The first 3 variables are global for the Agent
and the setup() method is a standard JADE agent function called on startup of the agent. In it
I will start with processing the command line options which were given like specified in section
6.1.

private PlayerClient player;

private PositionInterface position;
private BlobfinderInterface blobfinder;

protected void setup() {

//get the arguments which specify the host and port of the player server

8
 Object[] args = getArguments();
String arg1 = args[0].toString(); // this returns the String with the hostname
of the robot
String arg2 = args[1].toString(); // this returns the String of the portnumber
of the player server
player = new PlayerClient(arg1,Integer.parseInt(arg2));
position = player.requestInterfacePosition(0, ’a’); //a, r or w
blobfinder = player.requestInterfaceBlobfinder(0, ’r’); //a, r or w
player.runThreaded (-1, -1);
}
To find out more about the JavaClient try the excellent automatic documentation on the Java-
Client webpage[3].
After the setup is done commands can be sent to the robot like this:
position.setSpeed(currentSpeed,currentAngle);
Sensor data can be accessed like this:
currentX=position.getX();
currentY=position.getY();
currentYaw_temp=position.getYaw();

7 The PlayerAgent code

7.1 Variables
Here I will explain the most important variables in the PlayerAgent code:

7.1.1 globalPeriod
This is the time in ms in which the report behaviour interacts with the Player server using the
Java-Client proxy. Because this is the minimum time in which commands are sent all Ticker-
Behaviours should not be called more often than this value, in fact I used a period time of
5*globalPeriod for most other ticker behaviours.

7.1.2 moveTimer
This variable saves the time the current movement should continue and is independent from the
speed values themselves, but should be set everytime the speed is changed to prevent to robot
from driving with full force for 10 minutes! It is decremented by 1 everytime Report is called, so
every globalPeriod ms. To drive for 1 second I used code like this:
moveTimer=1000/globalPeriod;

9
7.1.3 currentSpeed, currentAngle
These two variable contain the speed values which will be sent to the Player server and thus the
hardware next time the Report behaviour is called. They should always be set together and with
the moveTimer variable to prevent unwanted movements. Because of this only one behaviour
should set these variable at a time but this is not enforced by the framework so far. These values
have a maximum limit defined in MAX SPEED and MAX SPEED ANGLE. This limit is enforced just
before the values are passed to the hardware.

7.1.4 currentX, currentY, currentYaw

These global variables are filled with the actual position of the robot by the report behaviour. I
used them instead of a direct call to position.getX() to have the same values among behaviours
and keep the amount of calls to the Player server low.

7.1.5 AID[] playerAgents

This array is filled with the AIDs replied by the DF as answer to the query in the QueryNS
behaviour. The QueryNS behaviour is called every 2 seconds so at the startup of the software it
takes 2 seconds to get the addresses of the other robots.

7.1.6 HashMap agentData

This is the central data storage for my complex behaviour. It is filled by the WaitForAll behaviour
and contains all data from one robot in a row. The key is the Robot’s AID which is taken from
the playerAgents array in my case to cycle through the hashmap. The data field contains a
colon separated string as described in my report in the implementation section.

8 Immediate future work

This section contains mostly small changes that are either really easy or already mostly done -
they could be a good starting point to work with the code.

8.1 PlayerAgentShadow
PlayerAgentShadow is a unfinished project by me to use one agent to communicate with two
player instances - one simulated and one real. The ideas is to use this agent to visualize the
existing robot when it interact with the simulated robots - in a formation for example. To get
this behaviour the agent is using the Report function to query the player instance on the real
robot and then sets the 2DPose of the robot using the simulation interface of STAGE.
The code is running and displaying the movements of the real robots right now, but the simulated

10
robot seem to turn and move greater distances than the real one - this is probably only a unit
conversion problem. To use the PlayerAgentShadow it must be started with 4 options: DNS
name of real robot, its port, DNS name of simulated robot, its port. This is in my case something
like
java jade.Boot -gui "player0:player.PlayerAgent.PlayerAgent(localhost 6665)" \
"min1Sim:player.PlayerAgentShadow.PlayerAgentShadow(min1 6665 localhost 6669)"
to get an agent called min1Sim which controls the 5th simulated robot and uses the data from
the PLAYER server running on min1. I modified the everything.cfg for STAGE to make this last
simulated robot black for easier identification, you can use this file if you wish.

8.2 Adding own behaviours

Adding own behaviours to my architecture is simple. Just add another behaviour object using
one of the JADE templates and modify the HandleQuerys behaviour to accept a command to
start that behaviour if you want to do that. Look at the Stop behaviour for reference. Here is
an example of a very simple behaviour:

class Move extends OneShotBehaviour {

int angle,distance;
public Move(Agent a,int in_distance, int in_angle) {
super(a);
distance=in_distance;
angle=in_angle;
}
public void action() {
currentAngle=angle;
currentSpeed=distance;
moveTimer=1000/globalPeriod; //let the movement go on for 1 second
}
}

8.3 Remotely killing behaviours

So far there is no way to remotely stop a running behaviour on a robot. I was thinking about
this to change that: A hashtable where every started behaviour get an entry with its address
as key and a colon separated string as the data value just like in my complex behaviour. The
string would contain a ”type” field where the type of the behaviour (for example ”Lead”) would
be saved. Then a message like ”killall:Lead” should start a behaviour which cycles through the
hashtable and calls .stop() for all of them and removes the entry from the hashtable - thats it!

11
8.4 Error handling
So far not too many error are caught - simply because I have not too much experience with Java
error handling. This should be improved.

References
[1] Java Agent DEvelopment framework http://jade.tilab.com/

[2] JADE Tutorial, JADE programming for beginners, Giovanni Caire,

http://jade.cselt.it/doc/programmersguide.pdf

[3] Java client for PLAYER http://java-player.sourceforge.net/

[4] The Player/Stage Project: Tools for Multi-Robot and Distributed Sensor Systems. Proceed-
ings of the International Conference on Advanced Robotics (ICAR 2003),pages 317-323

[5] Article about running Linux apps on Windows:

http://www.redmondmag.com/features/article.asp?EditorialsID=503 ,August 2005

12