Creating a Gazebo plugin

From The Player Project

Revision as of 16:05, 28 June 2010

Creating a Plugin for Gazebo

This tutorial will cover how to access and control the internals of Gazebo through a very simple plugin interface.

The original purpose of this plugin interface was to provide the ability to animate objects in a world. However, it's also possible to control almost every aspect of Gazebo.

An Example

This plugin interface allows you to directly insert (and remove) a chunk of code into a running Gazebo simulation.

The following is a stub for a plugin

#include <gazebo/gazeboserver.hh>

namespace gazebo
{
  class ExamplePlugin : public Plugin
  {
    /// Constructor
    public: ExamplePlugin() : Plugin() 
    {
    }
    /// Mandatory load function, needed by gazebo
    public: void Load()
    {
    }
  };

  /// Register this plugin with gazebo. This is mandatory
  GZ_REGISTER_PLUGIN("ExamplePlugin", ExamplePlugin)
}

The gazebo/gazeboserver.hh include will bring in everything needed to compile the plugin. Each plugin must inherit from the Plugin base class, define a Load function, and register itself using the GZ_REGISTER_PLUGIN macro.

A package config file is included in the Gazebo install called gazeboserver.pc that should make compilation easy:

pkg-config --libs --cflags gazeboserver

There is also an example cmake file located in the Gazebo sources in the plugins directory.

The following is an example plugin that works in conjunction with the elevator.world file that is located in the worlds directory in the sources.

#include <boost/bind.hpp>
#include <gazebo/gazeboserver.hh>

namespace gazebo
{
  class Elevator : public Plugin
  {
    /// Constructor
    public: Elevator() : Plugin() 
    {
      open_ = 0;
      raise_ = 0;
    }
    /// Mandatory load function, neded by gazebo
    public: void Load()
    {
      // Get the right and left doors, and the lift
      rightDoor_ = (Body*)World::Instance()->GetEntityByName("doors::right");
      leftDoor_ = (Body*)World::Instance()->GetEntityByName("doors::left");
      lift_ = (Body*)World::Instance()->GetEntityByName("lift::body");

      // Get the first contact sensor
      contact_ = (Geom*)World::Instance()->GetEntityByName("contact::body::COM_Entity::geom");
      contact_->SetContactsEnabled(true);
      contact_->ConnectContactCallback(boost::bind(&Elevator::ContactCB, this));


      // Get the second contact sensor
      contact2_ = (Geom*)World::Instance()->GetEntityByName("lift::body::COM_Entity::contact");
      contact2_->SetContactsEnabled(true);
      contact2_->ConnectContactCallback(boost::bind(&Elevator::Contact2CB, this));

      // Get an update callback
      World::Instance()->ConnectWorldUpdateStartSignal(boost::bind(&Elevator::UpdateCB, this));
    }

    /// Gazebo callback that contact occured on the plate in front of the door
    private: void ContactCB()
    {
      open_ = 1;
    }

    /// Gazebo callback that contact occured on the plate in the elevator
    private: void Contact2CB()
    {
      raise_ = 1;
    }

    /// Gazebo update callback
    public: void UpdateCB()
    {
      if (open_ == 1)
      {
        rightDoor_->SetLinearVel(Vector3(0, -0.5, 0));
        leftDoor_->SetLinearVel(Vector3(0, 0.5, 0));
      }

      if (raise_ == 1)
      {
        lift_->SetLinearVel(Vector3(0,0,0.5));
      }
    }


    private: int open_, raise_;
    private: Body *rightDoor_, *leftDoor_, *lift_;
    private: Geom *contact_, *contact2_;
  };

  /// Register this plugin with gazebo. This is mandatory
  GZ_REGISTER_PLUGIN("Elevator", Elevator)
}

This example plugin connects to the World's Update signal, which is called once every iteration of the simulation. Two geometries that act as contact sensors exist in the world. Within a running simulation, these two geoms are colored red. The elevator plugin connects to each of the geom's contact signals. When the first geom is hit, then the doors to the elevator are opened. When the second contact is hit, then the elevator is raised.

Examples of how to access bodies, geoms, and callbacks are provided in this example plugin. In order to use this plugin, use the follow steps:

1. Compile the elevator plugin (you should be in the directory containing the gazebo sources):

mkdir plugins/build

cd plugins/build

cmake ../

make

2. In another terminal, launch gazebo with the elevator.world:

gazebo worlds/elevator.world

3. In the terminal in which you compiled the plugins, load the elevator plugin:

gazeboplugin add ./libelevator.so elevator

The gazeboplugin command line tool allows you to insert, list, and remove plugins. The first parameter specifies the action (add or list or remove). When adding, the second argument is the location of the plugin file, and the third argument is a name for the plugin. It is also possible to list the currently running plugins:

gazeboplugin list

And to remove a plugin you only have to specify the name given to the plugin:

gazeboplugin remove elevator