Mailing lists


Old news
Old stuff

Configuration files

Whenever you run Player, you supply a configuration file as the last argument (see Command line options). This file, which usually has a .cfg extension, instantiates drivers and attaches them to indexed interfaces, through which client programs can access them. The purpose of the configuration file is to map physical or simulated devices to logical Player devices.

For example, the following configuration file maps a physical SICK laser range-finder, connected to /dev/ttyS0 , to the Player device laser:0

driver ( name "sicklms200" provides ["laser:0"] port "/dev/ttyS0" )
Client programs can subscribe to laser:0 and receive scans from the SICK. For example, if you run player with this configuration file and then start playerv like so:
$ playerv --laser
then you will see the laser scan visualized in a GUI.

You can do the same thing with simulated devices in Gazebo:

driver ( name "gz_laser" provides ["laser:0"] gz_id "mylaser" )
In this case, the simulated laser identified within Gazebo as "mylaser" is mapped to laser:0 , and can be accessed by client programs in the same way as the physical laser referenced above.

Configuration files are composed of sections, each of which instantiates one driver. Within each section, a set of keyword-value options determines which interface(s) the driver supports and supplies driver-specific configuration.

The following keywords are special, in that they can be applied to any driver (see the documentation for each driver to find out what other options are supported):

  • name (string)
    • Default: none
    • The name of the driver to instantiate; you must supply this option.
  • provides (string tuple)
    • Default: none
    • The device(s) to be supported; you must supply this option.
  • requires (string tuple)
    • Default: [] (i.e., no required devices)
    • The device(s) on which this driver depends (i.e., those devices that the driver will read from or write to).
  • plugin (string)
    • Default none
    • Use this option to specify the filename of a plugin driver (see HOWTO: Creating a Plugin Driver) to load. This file should be a shared object (aka dynamic library) that implements the driver.
  • alwayson (integer)
    • Default: 0
    • If nonzero, then the driver is started when Player starts, rather than waiting for a client to connect. This option is useful in several settings:
      • Testing a driver; debugging is faster when you don't have to run a client program to start your driver
      • When a driver takes a long to time to start, you may want to incur this delay when Player starts, rather than when the first client connects.
      • When using the readlog or writelog drivers, you may want to start logging or playback when Player starts.

Each string in the provides and requires tuples is a fully-qualified device id, with the following form

  • key:port:interface:index (string:integer:string:integer)

The interface and index fields are mandatory.

The key and port fields are optional; if omitted, the key is taken to be NULL and the port is taken to be the primary port on which Player is listening (by default 6665, unless overridden by the -p argument on the command line).

For example, the following file instantiates two drivers. The rflex driver, which controls a mobile robot, is mapped to two interfaces, one corresponding to the robot's wheels and the other corresponding to the robot's bumper array. The sicklms200 driver, which provides access to a SICK laser range-finder, is mapped to a single interface.

driver ( name "rflex" provides ["position:0" "bumper:0"] ) driver ( name "sicklms200" provides ["laser:0"] )

A driver may support more than one interface of the same type. In this case, the key field is used to distinguish among them. For example, the p2os driver supports three different position interfaces: odometry, compass, and gyro. The following file instantiates this drivers and maps all three of its position interfaces, as well some others:

driver ( name "p2os" provides ["odometry::position:0" "compass::position:1" "gyro::position:2" "bumper:0" "sonar:0"] )

The requires keyword is used when one driver depends on another. For example, the following file instantiates the camera1394 driver, which reads images from a firewire camera, and the cameracompress driver, which takes such images and compresses them:

driver ( name "camera1394" provides ["camera:0"] ) driver ( name "cameracompress" provides ["camera:1"] requires ["camera:0"] )
Raw images are available via camera:0 and compressed images are available via camera:1.

The value of each keyword-value option has one of the following types:
  • integer : an integer
  • float : a floating point number
  • string : a string enclosed in double-quotes
  • length : a unit-sensitive floating point value
  • angle : a unit-sensitive floating point value
  • filename : a filename enclosed in double-quotes, which is considered to be a path relative to the location of the configuration file
  • color : a color specification

There can also be tuples of each of these types, enclosed in brackets. Tuples can be heterogeneous; i.e., not all elements in a single tuple need be the same type.

The interpretation of length and angle values depends on the units in use. By default, lengths are specified in meters and angles in degrees.

The length unit can be changed to centimeters (or millimeters) like so:

unit_length "cm"

The angle unit can be changed to radians like so:

unit_angle "radians"

These statements are made outside of any driver section, and are sticky.

Generated on Tue May 3 14:16:08 2005 for Player by doxygen 1.3.6