/** @page configfile Configuration files

Whenever you run Player, you supply a configuration file as the last
argument.  This file, which usually has a @p .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 @p /dev/ttyS0 , to the Player device
@p laser:0
@verbatim
driver
(
  name "sicklms200"
  provides ["laser:0"]
  port "/dev/ttyS0"
)
@endverbatim
Client programs can subscribe to @p laser:0 and receive scans from the
SICK.  For example, if you run player with this configuration file and 
then start @ref player_util_playerv like so:
@verbatim
$ playerv --laser
@endverbatim
then you will see the laser scan visualized in a GUI.

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

@par Syntax

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 @ref
      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 @ref player_driver_readlog or @ref
          player_driver_writelog drivers, you may want to start logging or
          playback when Player starts.

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

  - @p key:port:interface:index (string:integer:string:integer)

The @p interface and @p index fields are mandatory.

The @p key and @p port fields are optional; if omitted, the @p key is
taken to be NULL and the @p 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 @ref
player_driver_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 @ref
player_driver_sicklms200 driver, which provides access to a SICK laser
range-finder, is mapped to a single interface.

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

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

@verbatim
driver
(
  name "p2os"
  provides ["odometry::position2d:0" 
            "compass::position2d:1" 
            "gyro::position2d:2"
            "bumper:0"
            "sonar:0"]
)
@endverbatim

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

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

@par Types

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:
@verbatim
unit_length "cm"
@endverbatim

The angle unit can be changed to radians like so:
@verbatim
unit_angle "radians"
@endverbatim

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

*/