Player/Stage: Getting Started Guide

(UTK-specific, as of Oct. '07)

Official Player/Stage documentation

Player/Stage is an open software project built and maintained by the international academic robotics community, available through SourceForge. The objective is to enable research in robots and sensor systems. The Player robot server is probably the most widely used robot control interface in the world. Its simulation backends, Stage (2D) and Gazebo (3D), are also very widely used.

Here is the official Player/Stage home page.

Here is the official Player/Stage documentation.

Higher-level information on the design of Player can be found in the following paper: "Most Valuable Player: A Robot Device Server for Distributed Control", by Gerkey, et al.

What is Player?

Player is a network server for robot control. Player can be running on your physical robot, or on your simulated robot through the Stage or Gazebo simulators. Player provides a clean and simple interface to the robot's sensors and actuators. Your client program talks to Player over a TCP socket, reading data from sensors, writing commands to actuators, and configuring devices on the fly. Client program can be written in any of the following languages: C++, Tcl, JAVA, and Python. (Note, however, that most examples of operational code are only for C++.) In addition, the client program can be run from any machine that has a network connection to your robot or to the machine on which your simulator is running.

Here's a link to the official Player Robot Device documentation.

What is Stage?

Stage is a 2D physics-based simulation environment that can be used to simulate a variety of different robots (or sets of robots) using a variety of different sensors in a variety of different environments. Stage provides several different physics-based models for robot sensors and actuators. The following are some of the currently supported models: sonar and infrared rangers, 2D scanning laser rangefinder, color-blob tracking, fiducial tracking, bumpers, grippers, and mobile robot bases with odometric and global localization. Note that Stage is not a program that you run stand-alone, so there is no binary called "Stage". Instead, you activate it by using Player (details to follow).

Here's a link to the official Stage documentation.

Setting up to use Player/Stage

You don’t need to (and should not!) install Player/Stage yourself. A shared version is available on our UTK CS Linux machines (e.g., in Hydra and Cetus). If you login remotely using ssh, make sure to enable X11 forwarding with the –X option so that the simulation window can be displayed on your screen. Depending on your system, you may need to also use the –Y option to enable trusted X11 forwarding. For example:

ssh –XY <username>@cetus15.cs.utk.edu

If you’re using a Windows machine to login remotely, you won’t be able to run the simulator unless you’ve installed an X server. For instructions on how to do this, see www.cs.utk.edu/~cs302/hints/Xhelp.html

The following instructions show you how to set up your shell environment, start the Player/Stage simulator, and run an example program.

The Player binary is located in /usr/local/bin, so be sure this is in your PATH environment variable. (Note: There is also a version of player in /research/playerstage, but this is an older version. Please use the version in /usr/local/bin.)
When we start Player, it will try to load the Stage plugin module. We tell it where to look with the PLAYERPATH environment variable.
For .bashrc or .zshrc:
export PLAYERPATH=”/usr/local/lib”
For .cshrc or .tcshrc:
setenv PLAYERPATH /usr/local/lib
If you don’t plan to use Python or Java, you can skip this step. If you plan to write your program in Python, you need to tell it where to find Player’s Python modules by modifying PYTHONPATH. If you will be using Java, the location of Player’s Java class files needs to be added to CLASSPATH.
For .bashrc or .zshrc:
export PYTHONPATH=”$PYTHONPATH:/usr/local/lib/python2.4/site-packages”
export CLASSPATH=”$CLASSPATH:/usr/local/src/javaclient/classes:.”
For .cshrc or .tcshrc:
setenv PYTHONPATH $PYTHONPATH:/usr/local/lib/python2.4/site-packages
setenv CLASSPATH $CLASSPATH:/usr/local/src/javaclient/classes:.
Now copy the examples to your home area, so that you can experiment with them. These examples come from within the "share" directory in /usr/local (in particular the "player" and "stage" subdirectories). To make it easier for you to begin with, I have packaged these files together in the tar file here: Player/Stage examples. Download this file to your own directory and unpack it ("tar xvf P-S-examples.tar"). You will find two subdirectories:
worlds: This contains the maps and configuration files for various examples.
examples: This contains example programs in C++.

Testing Player/Stage

At this point, we assume you've followed all the previous steps above. Now, we'll start up Player/Stage, so that you can see the system in operation.

Follow these instructions:

Let’s verify that we can start the Player/Stage simulator and get the Stage window to show up on the screen. Player should be run from the worlds directory (mentioned earlier) since it requires a configuration file on startup. So go to the worlds directory and type the following command:
player simple.cfg
This should open a Stage simulator window with a robot in the lower left of the map.
At this point, the Player server running on the simulated robot is waiting for a client program to connect and begin accessing the sensor data and sending movement commands. For now, we’ll use the client program in the examples/libplayerc++ directory. In another terminal window, go to this directory and run the executable:
./laserobstacleavoid
If you see the robot moving through the environment, everything is set up correctly.

Note that there are several pull-down menus in the Stage simulator that allow you to turn on and off various options. Some of the options you'll find particularly handy are turning on the robot trace (View->Show trails), which shows you the path the robot has taken, and obtaining a screen shot (File->Screenshot->Single frame), which saves a snapshot of the current simulation screen in files called stage-001.png or stage-002.jpg, etc. (These screenshots are handy for presenting results of your project!) You can also turn on/off the activated sensor displays, etc. Explore the pull-down menus to see what features are available to you.

Note also that you can click on the robot and drag and release it somewhere else in the environment, and the robot will continue in that new location. This can be handy when testing your robot control code.

Creating configuration files (.cfg) for Player

A "driver" in Player is a piece of code that provides an interface to a sensor or motor device (see the Player Robot Device documentation). We specify which device drivers Player should instantiate via a configuration file. This configuration file is a plain text file with *.cfg extension, and it is composed of one or more driver sections. (Note that you used a configuration file earlier (called simple.cfg) when you tried out Player/Stage.)

For each driver we can specify following options:

name: The name of a driver to instantiate (required).
plugin : The name of a shared library that contains the driver (optional).
provides: The device address(es) through which the driver can be accessed. Can be combination of strings. (required).
requires: The device address(es) to which the driver will subscribe. Can be combination of strings. (optional).
alwayson: If 1, then the driver will be setup when the player server starts, without waiting for any client connection. (optional).

Below is an example configuration file that could be run on a physical robot. Note that comments are prefaced by '#'.

# example.cfg
# Loads a driver for SICK laser
driver
(
   name "sicklms200" # The driver's name
   provides ["laser:0"] # The device address
)
# Loads a vfh (vector field histogram) driver used for
# local navigation and obstacle avoidance
driver
(
   name "vfh"
   provides ["position2d:1"]
   requires ["position2d:0" "laser:0"]
)

As previously noted, Stage is not a program that you run standalone, so there is no binary called "Stage". Instead, Stage provides a Player extension, or "plugin", which adds simulated robots to Player. To use the Player/Stage system, you run the "player" program with an appropriate configuration file. The following is how we define the stage driver in the configuration file:

#simple.cfg
# load the Stage plugin simulation driver
driver
(
   name "stage"
   provides ["simulation:0" ]
   plugin "libstageplugin"
   # load the named file into the simulator
   worldfile "simple.world"
)
# Create a Stage driver and attach position2d and laser
# interfaces to the model "robot1"
driver
(
   name "stage"
   provides ["position2d:0" "laser:0" ]
   model "robot1"
)

Note that the above configuration file makes use of a world file called "simple.world". Creating a world file is explained in the next section. Once the configuration file and world file are created, we just need to run following command:

linux:~>/working_directory/player example.cfg

linux:~>/working_directory/player simple.cfg

Here is documentation on all the supported devices available for Player

Here is documentation on all the drivers available for Player.

Creating world files (.world) for Stage

Stage simulates a 2D environment the robot operates in, as well as the models defined in a "world" file. In an *.world file, we define all the necessary information about the "world" in which our robots are operating.

For example, we need to define the map of the environment the robot is using, as well as the sensor and effector models we want to use and parameters of the simulation. Example simulation parameters include the resolution of the simulation (i.e., the size of a pixel in meters), and the time step size for simulation (interval_sim and interval_real, which represent milliseconds per update step for both simulation and real time).

Here is an example world file:

# simple.world

# the size of a pixel in Stage's (in meters)
resolution 0.02

# milliseconds per update step
interval_sim 100

# real-time milliseconds per update step
interval_real 100

# defines Pioneer-like robots
include "pioneer.inc"

# defines 'map' object used for floorplans
include "map.inc"

# defines the laser model `sick_laser' (Sick LMS-200)
include "sick.inc"

# Size of the world in meters
size [40 20 ]

# GUI options
gui_disable 0
gui_interval 100
gui_menu_interval 20

# Configure GUI window
window(
   size [ 755.000 684.000 ]
   center [-7.707 2.553]
   scale 0.009
)
# Load an environment bitmap
map(
   bitmap "sample.png"
   map_resolution 0.02
   size [40 18]
   name "sample"
)

Here, the specific map to be used is given in the file "sample.png", which is simply a bitmap image of the environment. Once we have created both simple.world and simple.cfg we just need to execute the following command in order to start the simulation:

linux:~>/working_directory/player simple.cfg

Player client programs (i.e., code to control your robot)

Earlier, you saw an example client program called "laserobstacleavoid" in the examples/libplayerc++ directory that causes the robot to move through its environment while avoiding obstacles. Other examples of robot control code are available in that same directory (available through the tar file of Player/Stage examples mentioned earlier.

To get started, you can use one of these example files and alter it as needed to make your own robot control program.

To recompile your code, you can make use of this example Makefile. Then, when running your code, you start up player with your configuration file in one window, and in another window you start up your robot control code (just like the example you stepped through earlier).

Have Fun!!