Writing a Player plugin driver

From The Player Project

Revision as of 09:38, 25 September 2007 by Stefan (Talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

If you want to know how to realize a non plugin driver look here

If you want to know which functions your driver must contain (plugin and non plugin) look here or in the /player/examples/plugins folder of your player installation.

The main difference between a normal player driver and plugin driver is, that player doesn't has to be recompiled if you compile your driver. The libary containing your plugin driver is linked to the player server at runtime. So if you develop a new driver a plugin driver is the better choice, because recompiling needs only seconds in comparison with 1-2 minutes if you have to recompile player each time. In difference to a normal player driver there is no entry in the players device table for this driver. Hence there must be a additional function in a player plugin driver to let the player server know that this driver exists and how to create it.

1 extern "C" {
2     int player_driver_init(DriverTable* table)
3     {
4         THE_NAME_OF_YOUR_DRIVER_Register(table);     ///call the registration function of your driver
5         return(0);
6     }
7 }

Beside this function you only have to add a additional line to the config file which you use to start the player server. See example.cfg or /player/examples/plugins/exampledriver/example.cfg.

Thats all.

The plugin driver's source code can be located anywhere on your file system except the player/server/drivers/ tree because there is a script that searches for object files and links them together and if you have more than one plugin driver in this tree is a linking error because of multiple definitions of the player_driver_init function.

The following file structure shows an example how to organize your plugins:

Example

There is a basic plugins folder to hold all your player plugins. There are subfolders for different types of drivers (planning, obstacle avoidance, hardware access,...)

 plugins/
   Makefile.am
   configure.ac
   autogen.sh
   example.cfg
   reconstruction/
     Makefile.am      
     hough3d.cc
     ransac.cc
     

To compile your driver run autogen.sh

Afterwards you have to do ./configure --prefix=YOUR_HOME_DIRECTORY/local for example (see ). This would install your plugin driver libs into $(prefix)/share/player/plugins/(see Makefile.am) == /YOUR_HOME_DIRECTORY/local/share/player/plugins

Since player links to this lib at runtime the directory has to be in the LD_LIBRARY_PATH variable. Look at Local_installation for more informations. (Look at Player_and_Automake for more information on automake tools)

autogen.sh

#!/bin/sh
libtoolize --force
autoheader  # creates config.h.in
touch NEWS README AUTHORS ChangeLog
touch stamp-h
aclocal # adds aclocal.m4 to directory. Defines some m4 macros used by the auto tools.
autoconf # creates configure from configure.ac
automake --add-missing # Creates Makefile.in from Makefile.am

Makefile.am in plugins

This Makefile.am contains all subfolders

SUBDIR = reconstruction

configure.ac in plugins

AC_INIT(plugins,1.0)
AM_INIT_AUTOMAKE(plugins,1.0)
AC_OUTPUT(Makefile reconstruction/Makefile)

Makefile.am in reconstruction

This Makefile creates the libs containing your drivers. Its important that each driver has its own lib. If not you get an linking error, that there are multiple definitions of the drivers registration functions player_driver_init(DriverTable* table).

houghdir = $(prefix)/share/player/plugins/
hough_LTLIBRARIES = libhough3d.la

ransacdir = $(prefix)/share/player/plugins/
ransac_LTLIBRARIES = libransac.la

AM_CPPFLAGS = -Wall -I$(top_srcdir)

libhough3d_la_SOURCES = hough3d.cc
libransac_la_SOURCES = ransac.cc 

hough3d.cc


// Initialization function
Driver* Hough3D_Init( ConfigFile* cf, int section)
{
    PLAYER_MSG0(1,"hough3d init");
    return ((Driver*) (new Hough3D( cf, section)));
}


// a driver registration function
void Hough3D_Register(DriverTable* table)
{
  table->AddDriver("hough3d", Hough3D_Init);
}


...
all functions of class Hough3D
...


extern "C" {
  int player_driver_init(DriverTable* table)
  {
    Hough3D_Register(table);     ///calls the above registration function
    return(0);
  }
}

ransac.cc


// Initialization function
Driver* RANSAC_Init( ConfigFile* cf, int section)
{
    PLAYER_MSG0(1,"ransac init");
    return ((Driver*) (new Ransac( cf, section)));
}


// a driver registration function
void Ransac_Register(DriverTable* table)
{
  table->AddDriver("ransac", Ransac_Init);
}


...
all functions of class Ransac 
...


extern "C" {
  int player_driver_init(DriverTable* table)
  {
    Ransac_Register(table);     ///calls the above registration function
    return(0);
  }
}

example.cfg

The second change except the player_driver_init function is a additional line in the configuration file. After you specify which driver to load ("name") you have to add the line (plugin "YOUR_PLUGIN_LIB"). Where "YOUR_PLUGIN_LIB" is the name of the libary that contains the driver (you specified this in the Makefile.am). (Look at Writing_configuration_files for additional information on config files).

driver                                 //another plugin driver (not mentioned in the above example
(
  name "pointcloudreader"
  plugin "libpointcloudreader"         //the lib name from the Makefile.am
  provides ["pointcloud3d:0"]          //a interface 
)
driver
(
  name "hough"
  plugin "libhough3d"         //the lib name from the Makefile.am
  requires ["pointcloud3d:0"]
  provides ["reconstruction:0"] //a interface 
)
driver
(
  name "ransac"
  plugin "libransac"         //the lib name from the Makefile.am
  requires ["pointcloud3d:0"]
  provides ["reconstruction:1"] //a interface 
)


Personal tools