/* Player documentation file - parsed by Doxygen for the user
 * manual
 * $Id: player.txt 8004 2009-07-13 14:03:44Z thjc $
*/

/**
@mainpage The Player Robot Device Interface

<p>Copyright Brian Gerkey and contributors 1999-2007, and beyond.
<p>Part of the Player/Stage/Gazebo Project [http://playerstage.sourceforge.net]

\section Overview

<p>
Player is a <i>robot device interface</i>.  What does that mean?
If you're familiar with operating systems (OS) terminology, Player
is a <i>hardware abstraction layer</i> (HAL) for robotic devices.  Your OS
(Linux, Mac OS X, etc.) hides the details of your computer's hardware by
defining generic concepts such as "mouse" and "printer," with each having a
standard <i>interface</i>.  Programs such as word processors can (to
a great extent) avoid knowing the details about your <i>particular</i>
mouse or printer, as long each adheres to the appropriate interface.  The
details of making a particular mouse, say, support the standard "mouse"
interface are handled by a <i>driver</i>.
</p>

<p>
Player serves the same purpose for robotic devices, making it a kind of
robot OS.  Player defines a set of standard interfaces (@ref interfaces),
each of which is a specification of the ways that you can interact with some
class of devices.  For example the @ref interface_position2d interface
covers ground-based mobile robots, allowing them to accept commands
to make them move (either velocity or position targets) and to report
their state (current velocity and position).  Many drivers support the
@ref interface_position2d interface, including @ref driver_p2os, @ref
driver_obot, and @ref driver_rflex, each of which controls a different
kind of robot.  The job of the driver is to make the robot support the
standard interface.  This way, Player control code that works with one
robot will work (within reason) on another robot.
</p>

\section Transports
<p>
Player also provides <i>transport</i> mechanisms that allow data to
be exchanged among drivers and control programs that are executing on
different machines.  By far the most common transport in use now is a
client/server TCP socet-based transport (see @ref start for an example of
this usage).  In this setup, the @ref util_player is executed
with a configuration file (@ref tutorial_config) that defines which
drivers to instantiate and how to bind them to hardware.  The drivers
run inside the <b>player</b> server (often in multiple threads), and the
user's control program runs as a client to that server.  @ref clientlibs
are available in various languages to facilitate the development of such
control programs.  Other transports can be used instead; an experimental
JINI-based transport is also available.
</p>

\section repository Player as a code respository
<p>
Though most Player drivers directly control hardware, recently a number of
<i>abstract</i> drivers have been developed.  An abstract driver uses other
drivers, instead of hardware, as sources for data and sinks for commands.
The main use of abstract drivers is to encapsulate useful algorithms in a
way that they can be easily reused.  For example, the @ref driver_amcl
driver is an implementation of adaptive Monte Carlo localization, a
well-known algorithm for probabalistic localization of a mobile robot.
This driver supports both the @ref interface_position2d interface (so it
can be used directly in place of odometry) and the more sophisticated @ref
interface_localize interface (which allows for multiple pose hypotheses to
be considered).  In addition to providing this incredibly useful
implementation of a particular localization algorithm, by defining such
standard interfaces we build up an environment in which alternative
algorithms and implementations can be developed and tested.  Other abstract
drivers include @ref driver_vfh, @ref driver_wavefront, and @ref
driver_laserbarcode.  Ideally, Player will become a common development
platform and community code respository for such algorithms.
</p>

\section Versions

<p>This document describes Player version 2.1.x, which represents minor
changes from the 2.0.x line, and significant changes from the 1.6.x line.
The information contained herein does <b>not</b> apply to earlier versions
of Player.</p>

\section License

<p>All Player source code is distributed under the terms of the
GNU General Public License v2 ("GPL").  A copy of this license is included with
the sourcecode in the files COPYING.  

With the exception of the @ref libplayerdrivers library, all Player source
is simultaneously distributed under the terms of the GNU Lesser General
Public License v2.1 ("LGPL"). A copy of this license is included with
the sourcecode in the files COPYING.lib.  Users may use dual-licensed
portions of Player under the GPL or the LGPL, at their choosing.

Player documentation is distributed under the GNU Free Documentation
License ("FDL").
*/

/**
@page help Getting Help

If you're having problems and you can't find what you need in this manual,
there are several places to find help.

First, please check the <a
href="http://playerstage.sourceforge.net/index.php?src=doc">online
documentation page</a> to make sure you
have the latest documentation. Also check the <a
href="http://playerstage.sourceforge.net/index.php?src=faq">online
FAQ page</a>.

Next, you should search <a
href="http://sourceforge.net/mailarchive/forum.php?forum_id=8201">the
playerstage-users mailing list archive</a> to
see if your questions have already been answered.

Next, you should probably spend a few minutes with <a
href=http://www.google.com>Google</a>. This often works well, as it
picks up P/S/G conversations from all over the place.

If you still need help, you can send email to the mailing list
playerstage-users@lists.sourceforge.net and a user or developer may
reply to you. <b>Remember that these mails go to hundreds of people</b>, so
please be polite and give as much information as you can in your
email.

For more tips and hints on getting help, look <a href="http://playerstage.sourceforge.net/index.php?src=faq#reporting_bugs">here</a>.
*/

/**
@defgroup libplayercore libplayercore

\section synopsis Synopsis
This C++ library defines the device driver API, the message queues used to
move messages between devices, facilities for parsing configuration files
and for loading and instantiating drivers.

The primary components of libplayercore are:
  - @ref message_basics : The basics of Player-based messaging, including
    size limits, unit specifications, and address structures.
  - @ref interfaces : The syntax and semantics of all the messages for each
    Player interface.
  - @ref ConfigFile : Configuration file parsing
  - @ref Message : The basic object used to transfer information
  - @ref MessageQueue : Messages are delivered by being pushed onto queues;
    every driver has one
  - @ref Driver : The class from which all drivers inherit
  - @ref Device : An instantied driver that is bound to an interface; all
    external access to a driver is mediated through one or more Device
    objects

\section linking Example compilation and linkage
The most common usage of libplayercore is in building a plugin driver.  If
the code for your driver is in mydriver.cc, you can build it like this (on
Linux):
\code
  $ g++ `pkg-config --cflags playercore` -o -shared mydriver.so mydriver.cc `pkg-config --libs playercore`
\endcode


*/

/**
@defgroup libplayercommon libplayercommon

This C library provides error-reporting and debug output facilities.
Instead of calling directly into the stdio library (printf, puts, etc.),
use the macros defined in error.h, so that message verbosity can be
centrally controlled and so that all messsages get logged to .player.

*/

/** @defgroup tutorials Tutorials

Listed below are tutorials on various topics that may be of interest
to users of Player.  The goal of these documents is to provide the user
with concise explanations (with examples, wherever possible) of important
concepts and common tasks.

<b>Please contribute!</b>  If you have anything to add, whether it's to
fill out an empty tutorial, augment an existing tutorial, or suggest or
provide a new one, please let us know.  Send your contribution to the
users' mailing list: playerstage-users@lists.sourceforge.net.
*/

/** @defgroup utils Player utilities
@brief Player utilities

Several utilities are included with the Player distribution, listed below.
*/

/** @defgroup clientlibs Client Libraries 

Libraries are available in various languages to facilitate the development
of TCP client programs.   You would probably use one of these libraries to
develop your robot control program if, like most people, you're using the
@ref util_player (whether with hardware or simulation).

Be sure to also check for 
<a href="http://playerstage.sourceforge.net/wiki/PlayerClientLibraries">contributed
libraries</a>.
*/