Copyright Brian Gerkey and contributors 1999-2006, and beyond.
Part of the Player/Stage/Gazebo Project [http://playerstage.sourceforge.net] \section Overview
Player is a robot device interface. What does that mean? If you're familiar with operating systems (OS) terminology, Player is a hardware abstraction layer (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 interface. Programs such as word processors can (to a great extent) avoid knowing the details about your particular 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 driver.
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.
\section TransportsPlayer also provides transport 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 player 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.
\section repository Player as a code respositoryThough most Player drivers directly control hardware, recently a number of abstract 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.
\section VersionsThis document describes Player version 2.x, which represents a significant change from the 1.6.x line. The information contained herein does not apply to earlier versions of Player
\section LicensePlayer source and documentation is released under the terms of the GNU General Public License v2. A copy of the license is included with the sourcecode in the file COPYING. Copying and redistribution is permitted only under the terms of the license. Client libraries are simultaneously released under the terms of the GNU Lesser General Public License v2.1.
*/ /** @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 online documentation page to make sure you have the latest documentation. Also check the online FAQ page. Next, you should search the playerstage-users mailing list archive to see if your questions have already been answered. Next, you should probably spend a few minutes with Google. 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. Remember that these mails go to hundreds of people, so please be polite and give as much information as you can in your email. For more tips and hints on getting help, look here. */ /** @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 libplayererror libplayererror 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. Please contribute! 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 contributed libraries. */