Basic FAQ

From The Player Project

Jump to: navigation, search
(What's the right way to report bugs and ask questions on the mailing lists?: move to Getting help)
(How do I get the latest code?)
 
Line 4: Line 4:
=General=
=General=
== I have problems, documentation didn't help me, how can I get help? ==
== I have problems, documentation didn't help me, how can I get help? ==
-
See next question.
+
See [[Getting help]] page.
== What's the right way to report bugs and ask questions on the mailing lists? ==
== What's the right way to report bugs and ask questions on the mailing lists? ==
Line 18: Line 18:
==Where can I find binary packages?==
==Where can I find binary packages?==
-
We don't maintain binary packages, but some users do. Look on the [[Download]] page.  
+
We don't maintain binary packages for Unix-like systems, but some users and Linux distributions do. We do provide a binary installer for Windows. Look on the [[Download]] page for more details.  
==What's the story of Player's creation?==
==What's the story of Player's creation?==
-
The story of the Player/Stage project can be read in the [[PlayerHistory| player's history]] page.
+
The story of the Player/Stage project can be read in the [[PlayerHistory| Player's history]] page.
==What other information about the Player/Stage Project is available online?==
==What other information about the Player/Stage Project is available online?==
Line 54: Line 54:
=Player=
=Player=
==What is Player?==
==What is Player?==
-
Player is a device server that provides a powerful, flexible interface to a variety of sensors and actuators (e.g., robots). Because Player uses a TCP socket-based client/server model, robot control programs can be written in any programming language and can execute on any computer with network connectivity to the robot. In addition, Player supports multiple concurrent client connections to devices, creating new possibilities for distributed and collaborative sensing and control.  
+
[[Player]] is a device server that provides a powerful, flexible interface to a variety of sensors and actuators (e.g., robots). Because Player uses a TCP socket-based client/server model, robot control programs can be written in any programming language and can execute on any computer with network connectivity to the robot. In addition, Player supports multiple concurrent client connections to devices, creating new possibilities for distributed and collaborative sensing and control.  
More information on the [[Player]] page.
More information on the [[Player]] page.
==How is Player different from other robot interfaces?==
==How is Player different from other robot interfaces?==
-
Previous work in the area of robot programming interfaces has focused primarily on providing a development environment that suits a particular control philosophy. While such tools are very useful, we believe that implementing them at such a low level imposes unnecessary restrictions on the programmer, who should have the choice to build any kind of control system while still enjoying device abstraction and encapsulation.  
+
Previous work in the area of robot programming interfaces has focused primarily on providing a development environment that suits a particular control philosophy. While such tools are very useful, we believe that implementing them at such a low level imposes unnecessary restrictions on the programmer, who should have the choice to build any kind of control system while still benefiting from device abstraction and encapsulation.  
-
 
+
-
Thus in Player we make a clear distinction between the programming interface and the control structure, opting for a maximally general programming interface, with the belief that users will develop their own tools for building control systems. Further, most robot interfaces confine the programmer to a single language, providing a (generally closed-source) language-specific library to which the user must link his programs. In contrast, the TCP socket abstraction of Player allows for the use of virtually any programming language. In this way, it is much more "minimal" that other robot interfaces.
+
-
 
+
 +
Thus in Player we make a clear distinction between the programming interface and the control structure, opting for a maximally general programming interface, with the belief that users will develop their own tools for building control systems. Further, most robot interfaces confine the programmer to a single language, providing a (generally closed-source) language-specific library to which the user must link his programs. In contrast, the TCP socket abstraction of Player allows for the use of virtually any programming language. In this way, it is much more "minimal" that other robot interfaces.
==What hardware and software does Player support?==
==What hardware and software does Player support?==
-
There is a [http://playerstage.sourceforge.net/doc/Player-cvs/player/supported_hardware.html list of supported devices].
+
There is a [http://playerstage.sourceforge.net/doc/Player-svn/player/supported_hardware.html list of supported devices].
==How do I get/build/install Player?==
==How do I get/build/install Player?==
Line 72: Line 70:
==How do I cross-compile Player (e.g., for the iPAQ or Gumstix)?==
==How do I cross-compile Player (e.g., for the iPAQ or Gumstix)?==
-
Of course you can find the [http://playerstage.sourceforge.net/doc/Player-cvs/player/group__tutorial__crosscompiling.html proper tutorial] for this.
+
Of course you can. Tutorials are available for users of [[Cross_Compile_Player_with_Openembedded_and_BitBake | OpenEmbedded]], and for [[Cross-compiling]] Player from the command line.
 +
 
 +
==What is the difference between Player and Stage and Gazebo? What is the difference between Player device drivers and simulated device models in Stage or Gazebo?==
 +
 
 +
See the explanation on [[Player#How_Player_works | How Player works]]
==When I try to connect to Player, I get "connection refused."==
==When I try to connect to Player, I get "connection refused."==
Line 82: Line 84:
==How do I add a device driver to Player?==
==How do I add a device driver to Player?==
-
Read [http://playerstage.sourceforge.net/doc/Player-cvs/player/group__tutorial__plugins.html this tutorial].  
+
If you already have a working plugin driver and wish to integrate it, read [[Adding drivers to Player 3]]. If you want to create your own plugin driver, read [[Writing a Player driver]]
==When I run Player (possibly under Stage), it exits with the message "unknown host; probably should quit." What's the deal?==
==When I run Player (possibly under Stage), it exits with the message "unknown host; probably should quit." What's the deal?==
Line 93: Line 95:
==I have a syntax error involving PKG_CHECK_MODULES. What's the fix?==
==I have a syntax error involving PKG_CHECK_MODULES. What's the fix?==
-
If you get a syntax error involving PKG_CHECK_MODULES, it is likely that aclocal can't find the pkg.m4 file, which defines this macro. This is common on OS X with Fink, as the pkg-config package puts this file in /sw/share/aclocal, while the standard OS X aclocal program is looking in /usr/share/aclocal. Unfortunately, there is no reliable search path mechanism for aclocal, so the best fix is just to copy (or symlink) /sw/share/aclocal/pkg.m4 to /usr/share/aclocal. This FAQ taken from the [http://www.cs.sfu.ca/research/groups/autonomy Autonomy Lab's] [http://deckard.cs.sfu.ca:8080/Wiki/PkgCheckModules P/S Wiki].  
+
If you get a syntax error involving PKG_CHECK_MODULES, it is likely that aclocal can't find the pkg.m4 file, which defines this macro. This is common on OS X with Fink, as the pkg-config package puts this file in /sw/share/aclocal, while the standard OS X aclocal program is looking in /usr/share/aclocal. Unfortunately, there is no reliable search path mechanism for aclocal, so the best fix is just to copy (or symlink) /sw/share/aclocal/pkg.m4 to /usr/share/aclocal. This FAQ taken from the [http://www.cs.sfu.ca/research/groups/autonomy Autonomy Lab's] [http://deckard.cs.sfu.ca:8080/Wiki/PkgCheckModules P/S Wiki].
 +
 
 +
Note that this only applied to versions of Player before Player 3.0.0.  Player 3 uses the CMake build system.
==How can I get high data rates from my SICK LMS laser rangefinder?==
==How can I get high data rates from my SICK LMS laser rangefinder?==
-
It's possible to get scans at 75Hz from the SICK LMS, if you use an RS422 connection, which is a high-speed serial line. If you use a run-of-the-mill RS232 connection, the best you can expect is about 10Hz, depending on angular aperture and resolution.  
+
It's possible to get scans at 75Hz from the SICK LMS, if you use an RS422 connection, which is a high-speed serial line. If you use a run-of-the-mill RS232 connection, the best you can expect is about 10Hz, depending on angular aperture and resolution.
-
Look [http://sourceforge.net/mailarchive/message.php?msg_id=8966514 here] for one way to use a USB-RS422 converter to get high-speed laser scans.  
+
 
-
For a detailed explanation of how the LMS works, timing considerations, and what data rates can be expected, look here.  
+
Look [http://sourceforge.net/mailarchive/message.php?msg_id=8966514 here] for one way to use a USB-RS422 converter to get high-speed laser scans.
-
More info and tips on using Player to get high-speed laser scans can be found [http://www-robotics.cs.umass.edu/segway/sick.html here].  
+
 
 +
If you purchased the Quatech card, check out the tutorial [[High Speed Lidar]].
 +
 +
For a detailed explanation of how the LMS works, timing considerations, and what data rates can be expected, look [http://sourceforge.net/mailarchive/message.php?msg_id=9038591 here].
 +
 
 +
More info and tips on using Player to get high-speed laser scans can be found [http://www-robotics.cs.umass.edu/segway/sick.html here].
==How do I connect my (Sony or Canon) PTZ camera to a standard serial port (instead of, e.g., the AUX port on my Pioneer)?==
==How do I connect my (Sony or Canon) PTZ camera to a standard serial port (instead of, e.g., the AUX port on my Pioneer)?==
-
ActivMedia robots that are equipped with a PTZ camera often have the camera connected to the AUX port on the P2OS board in the robot. Player does not support control of the camera through this connection, for reasons explained [http://www-robotics.cs.umass.edu/segway/sick.html here]. Instead, Player requires a standard, direct, serial line to the camera.  
+
ActivMedia robots that are equipped with a PTZ camera often have the camera connected to the AUX port on the P2OS board in the robot. Player does not support control of the camera through this connection, for reasons explained [http://www-robotics.cs.umass.edu/ARCHIVE/segway/sick.html here]. Instead, Player requires a standard, direct, serial line to the camera.  
Line 108: Line 117:
-
Here are some detailed wiring instructions, courtesy of Jason L. Bryant at the [http://www.nrl.navy.mil/aic/index.php Navy Center for Applied research in Artificial Intelligence]:  
+
Here are some detailed wiring instructions for a Pioneer with a Canon camera and VSBC8 computer, courtesy of Jason L. Bryant at the [http://www.nrl.navy.mil/aic/index.php Navy Center for Applied research in Artificial Intelligence]:  
----
----
-
Instructions for rewiring a pioneer robot so that the PTZ camera device can be connected to a serial port (ttyS1) the on-board computer rather than to the robot's microcontroller.  
+
Instructions for rewiring a pioneer robot so that the Canon PTZ camera device can be connected to a serial port (ttyS1) the on-board VSBC8 computer rather than to the robot's microcontroller.  
Line 127: Line 136:
-
You can test that the connections work by running /usr/local/Aria/bin/demo on the robot, selecting 'C' for camera control, then the appropriate key for your particular camera (Sony, or Canon) connected to a serial port ('@' for a Canon), and finally '2' for serial port /dev/ttyS1.  
+
You can test that the connections work by running /usr/local/Aria/bin/demo on the robot, selecting 'C' for camera control, then the appropriate key for your particular camera (Sony, or Canon) connected to a serial port ('@' for a Canon), and finally '2' for serial port /dev/ttyS1.
-
 
+
==How can I read image data from a camera?==
==How can I read image data from a camera?==
Line 155: Line 163:
==What is the purpose of the key in a provides or requires field (e.g., the "odometry" in "odometry::position:0")?==
==What is the purpose of the key in a provides or requires field (e.g., the "odometry" in "odometry::position:0")?==
-
Look [http://playerstage.sourceforge.net/doc/Player-cvs/player/group__tutorial__config.html#device_key here].
+
This is explained in the [[Writing configuration files#The key field in a device address | Writing Confguration Files]] tutorial.
==What is set odometry, and what does set odometry do?==
==What is set odometry, and what does set odometry do?==
Line 164: Line 172:
odometry will be reported.
odometry will be reported.
-
==What is the difference between Player and Stage and Gazebo? What is the difference between Player device drivers and simulated device models in Stage or Gazebo?==
+
==Suppose I write a Plugin, how do I set it up to have its own messages?==
-
See the explanation on [[Player#How_Player_works | How Player works]]
+
The 'opaque' interface is designed for this purpose.  It allows you 
 +
to exchange messages with arbitrary content.  On the client side, 
 +
there's an OpaqueProxy.  Of course, there will not be XDR wrappers 
 +
for your custom messages, so you have to do your own (de)marshaling 
 +
on each side.
 +
The opaque interface is usually used to prototype new interfaces and/
 +
or extensions to existing interfaces.  If you would like to add a new
 +
interface, you have two options: create a plugin interface or add a
 +
new interface definition to player.  For custom applications, it's
 +
better to create a plugin interface.  If the interface needs to be
 +
integrated into player, you can follow the instructions at [[Writing_a_Player_interface]]
=Stage=
=Stage=
 +
==What is Stage?==
==What is Stage?==
-
Stage is a scaleable multiple robot simulator; it simulates a population of mobile robots moving in and sensing a two-dimensional bitmapped environment, controlled through Player. Stage provides virtual Player robots which interact with simulated rather than physical devices. Various sensor models are provided, including sonar, scanning laser rangefinder, pan-tilt-zoom camera with color blob detection and odometry.  
+
Stage is a scaleable multiple robot simulator; it simulates a population of mobile robots moving in and sensing a two-dimensional bitmapped environment. When used as a Player plugin, Stage provides virtual Player robots which interact with simulated rather than physical devices. Stage can also be used as link library to create custom simulations. Various sensor models are provided, including sonar, scanning laser rangefinder, pan-tilt-zoom camera with color blob detection and odometry.  
More information on the [[Stage]] page.
More information on the [[Stage]] page.
-
==How is Stage different from other robot simulators?==
 
-
==Where does Stage run?==
 
==How do I get/build/install Stage?==
==How do I get/build/install Stage?==
See the [[Download]] page.
See the [[Download]] page.
-
==How can I make movies of my Stage simulations?==
+
== When configuring Stage, Player is not found, but I just installed Player OK. What's up? ==
-
For Stage 1.6 and up, use the File:Export menu in the GUI to dump screenshots, then see "How can I make movies from screenshots?" question above.
+
Stage uses pkgconfig to find Player, so the problem probably lies with your pkg-config setup.
 +
First, make sure you have pkg-config installed. Then run it from the command line to make sure it finds Player.
-
For Stage 1.3.x see [http://playerstage.sourceforge.net/index.php?src=faq#top old FAQ].
+
Here's a successful manual run of pkg-config:
-
==What does it mean when Stage says "error executing player"?==
+
  $ pkg-config --cflags playercore
-
This usually means that Stage was unable to execute the Player server because it's not in your PATH. You must have the path to the server binary player (e.g., $HOME/player-1.3/bin) in your PATH.  
+
  -I/Users/vaughan/PS-2.0/include/player-2.0
-
==Stage is running but there's no GUI! ==
+
Here's an unsuccessful run, which produces a hint on how to fix it:
-
Well that's not actually a question, but the problem is likely that you didn't compile any GUI support into Stage. That's an installation problem, read again the installation instructions for Stage.
+
-
==How do I add an object to Stage 1.3 and later?==
+
  $ pkg-config --cflags playercore
-
(contributed by Alex Makarenko)
+
  Package playercore was not found in the pkg-config search path.
-
TODO: Is this outdated??
+
  Perhaps you should add the directory containing `playercore.pc'
-
#write the code: myobject.hh/cc
+
  to the PKG_CONFIG_PATH environment variable
-
##see a comment in file src/library.hh
+
  No package 'playercore' found
-
##start with an existing object, e.g. src/models/puck.hh/cc
+
-
#add two lines in file src/library.cc
+
-
## #include models/mydevice.hh
+
-
## add an item to libitem_t library_items[] = {...}
+
-
#add files to the project and compile
+
-
##copy myobject.hh/cc to src/models directory  
+
-
##add them to libstgmodels_a_SOURCES list in file src/models/Makefile.am
+
-
##make sure the files are actually added to the project, this may require some coercing, such as:
+
-
+
-
run autoconf (or possibly autoreconf ?)
+
-
run automake
+
So you need to add the path to Player's installed pkg-config metadata (*.pc) files. These 
 +
are in $(prefix)/lib/pkgconfig. $(prefix) defaults to /usr/local/ 
 +
unless you specified it differently on your configure command line. 
 +
So here's the fix for a default install:
-
run ./configure
+
  $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 +
  $ pkg-config --cflags playercore
 +
  -I/Users/vaughan/PS-2.0/include/player-2.0
-
*compile
+
==How can I make movies of my Stage simulations?==
 +
 
 +
For Stage 1.6 and up, use the File:Export menu in the GUI to dump screenshots, then see "How can I make movies from screenshots?" question above.
==Where is the "sonar" model in Stage?==  
==Where is the "sonar" model in Stage?==  
-
Stage does not have a "sonar" model, but it does have a "ranger" model. This model can be used to simulate any sensor which consists of a group of individual range-sensing models. Stage's "ranger" only simulates a single "beam", however, instead of (the potentially computentially expensize) cone shape of most sonar sensors.
+
 
 +
Stage does not have a "sonar" model, but it does have a "ranger" model that does a reasonable job of modeling sonar and IR rangefinders, or similar arrays of simple rangefinders. The ranger models a sonar or IR cone by raytracing a  configurable number of thin diverging beams.
=Gazebo=
=Gazebo=
 +
==Where can I find the full XML specification for gazebo world files?==
 +
Gazebo 0.9 -> THIS NEEDS TO BE INSERTED HERE
 +
==What is Gazebo?==
==What is Gazebo?==
Gazebo is a 3D, dynamic, multi-robot simulator. Whereas Stage is intended to simulate the behavior of very large populations of robots with moderate fidelity, Gazebo simulates the behavior of small populations of robots (less than 10) with high fidelity. Read the [[Gazebo]] page for more information.  
Gazebo is a 3D, dynamic, multi-robot simulator. Whereas Stage is intended to simulate the behavior of very large populations of robots with moderate fidelity, Gazebo simulates the behavior of small populations of robots (less than 10) with high fidelity. Read the [[Gazebo]] page for more information.  
Line 226: Line 244:
==How do I get/build/install Gazebo?==
==How do I get/build/install Gazebo?==
See the [[Download]] page.
See the [[Download]] page.
 +
See also [[Install]] page.
==How do I build Gazebo on OS X?==  
==How do I build Gazebo on OS X?==  
Directions for building on Gazebo on OS X can be found in the Gazebo manual, available from the  [http://playerstage.sourceforge.net/index.php?src=doc documentation page].  
Directions for building on Gazebo on OS X can be found in the Gazebo manual, available from the  [http://playerstage.sourceforge.net/index.php?src=doc documentation page].  
==How can I make movies of Gazebo?==  
==How can I make movies of Gazebo?==  
-
Gazebo will not make movies directly, but can be instructed to export still frames, which you can then animate (see how to make movies question above). In versions up to and including 0.3.0, click on the window you wish to export, then press the 'W' key'; frames are saved in PPM format in a directory named "frames-". Note that saving frames will significantly affect Gazebo's performance.  
+
===Gazebo 0.7===
 +
Gazebo will not make movies directly, but can be instructed to export still frames, which you can then animate (see how to make movies question above). In versions up to and including 0.3.0, click on the window you wish to export, then press the 'W' key'; frames are saved in PPM format in a directory named "frames-". Note that saving frames will significantly affect Gazebo's performance.
 +
 
 +
===Gazebo 0.8===
 +
Adding <saveFrames>true<saveFrames> to the camera sensor will save those frames. The frames will be saved in .jpg format.
==How can I read image data from a camera?==
==How can I read image data from a camera?==
Line 236: Line 259:
For Player users, see the FAQ entry on reading camera data; from Player's perspective, Gazebo cameras work just like real cameras (which means you can develop image processing algorithms using Gazebo-simulated images).
For Player users, see the FAQ entry on reading camera data; from Player's perspective, Gazebo cameras work just like real cameras (which means you can develop image processing algorithms using Gazebo-simulated images).
 +
 +
 +
=Developers=
 +
 +
==How do I get the latest code?==
 +
 +
All the code for Player is maintained in Subversion (SVN) repositories at SourceForge. Project-specific instructions for SVN access, both anonymous and read/write, are [http://sourceforge.net/svn/?group_id=42445 here].
 +
 +
Stage code is maintained in git repositories at Github. Project-specific instructions for git access, both anonymous and read/writem are [https://github.com/rtv/Stage here]
 +
 +
Player is in SVN.  To check out Player, use this command:
 +
<pre>
 +
svn checkout svn://svn.code.sf.net/p/playerstage/svn/code/player/trunk player
 +
</pre>
 +
 +
Stage is now hosted at Github. You can get the very latest Stage using this command:
 +
<pre>
 +
git clone http://github.com/rtv/Stage.git stage
 +
</pre>
 +
 +
Gazebo is now hosted at [http://www.gazebosim.org gazebosim.org].  Please see their [http://www.gazebosim.org/downloads.html Downloads] page for more information
 +
 +
===Branches===
 +
To check out a branch from SVN, say, the release-3-0-patches branch of Player:
 +
<pre>
 +
svn checkout svn://svn.code.sf.net/p/playerstage/svncode/player/branches/release-3-0-patches player-3.0.x
 +
</pre>
 +
 +
Recent releases of Stage are git tags in the Stage github repository.  After cloning the git repository with the directions above, you can check out tags like so:
 +
<pre>
 +
git checkout v4.0.0
 +
</pre>
 +
 +
Older release of Stage are still in subversion.  To check out Stage 3.2, use this command:
 +
<pre>
 +
svn checkout svn://svn.code.sf.net/p/playerstage/svn/code/stage/branches/release-3-2-patches stage_3.2
 +
</pre>
 +
 +
==How do I build from an SVN working copy?==
 +
 +
===Player===
 +
 +
The development version of Player uses [http://www.cmake.org CMake] for its build system. This is an entirely new build system, replacing the old GNU Autotools-based system we used in the past. It's simpler, cleaner and much, much faster to configure, compile and install using this new system. To build Player from SVN, you will need to install CMake (at least version 2.4 is required).
 +
 +
The better way to compile Player is using an out-of-source build (in-source builds pollute the source tree and are harder to clean up). In this configuration you will have two directories: the source directory, containing the Player source, and the build directory, containing the generated build scripts and compiled objects. Once you have the Player source checked out and CMake installed, create a directory anywhere on your system where you have write privileges and change to that directory. Typically, a subdirectory of the source is used for convenience. For example:
 +
 +
$ cd player/
 +
$ mkdir build
 +
$ cd build/'''
 +
 +
Within this directory, execute either cmake (for a text-only interface) or ccmake (for an ncurses-based UI), providing the path to the Player source. Continuing the above example, one of the following two lines would be used:
 +
 +
$ cmake ../
 +
$ ccmake ../
 +
 +
If you used cmake, the configuration will be completed in a single run. It will display output indicating the configuration Player will be built with (enabled/disabled drivers, client libraries, etc.). If you used ccmake, you will be presented with a set of configurable options. Press 'c' to run the configuration, and more options will appear. Configure Player to suit your needs (for example, change CMAKE_INSTALL_PREFIX to change the location to install to, and enable/disable drivers), then press 'c' repeatedly until the generate option appears at the bottom (usually two or three passes are required). Press 'g' to generate the build scripts.
 +
 +
You can now build and install Player using the build method of your system. This will typically be Make, so execute make:
 +
 +
$ make
 +
$ make install
 +
 +
CMake will re-run itself automatically when a CMakeLists.txt file changes. You will typically not have to run it again unless you remove the contents of your build directory. The CMake equivalent of a make clean is to remove the build directory (assuming an out-of-source build).
 +
 +
===Stage===
 +
 +
Stage uses a CMake build system similar to Player's.  Follow the directions for Player above.
 +
 +
===Gazebo===
 +
Instructions can be found in:
 +
*[http://playerstage.sourceforge.net/doc/Gazebo-manual-svn-html/install.html Installation guide for Gazebo 0.8]
 +
 +
==How do I contribute documentation?==
 +
To paraphrase [[Brian Gerkey]] in [http://sourceforge.net/mailarchive/message.php?msg_id=14969099 this] mailing list email.
 +
 +
Patches to fix up the docs would be most appreciated.
 +
Patches against SVN/GIT are always better.  There's some value to making patches against the latest release, as it's easier for users to apply them.  But if you only make one patch, please make it against SVN/GIT (and submit to the [http://sourceforge.net/tracker/?group_id=42445&atid=433166 patch tracker] at SourceForge; that way it won't get lost).
 +
 +
Please also read the [[Contributing]] page, the [[Roadmap]], and the [[Wishlist]].
 +
 +
 +
[[Category:Documentation]]
 +
 +
[http://custom-essay-writing-service.org/index.php custom essay writing]

Latest revision as of 03:06, 17 December 2012

Personal tools