next up previous contents
Next: 10. libgazebo Interface Reference Up: 2 Developer Guide Previous: 8. Adding a New   Contents


9. libgazebo 

9.1 Introduction

External programs can use libgazebo to interact with the Gazebo simulator. libgazebo is a simple C library that allows other programs to peek and poke into a running simulation; through this library, programs may read sensor data from and send commands to simulated devices. The player device server, for example, uses libgazebo in this way.

Normal users will interact with Gazebo via player and need not be aware of this library. This chapter is included primarily to aid those who either wish to add a new type of interface to the simulator, or who wish to write their own custom control programs (by-passing player entirely).

9.2 Architecture

libgazebo uses interprocess communication (IPC) to allow a program to exchange data with a running simulator. Hereafter, we shall refer to the simulator as the server and the program as the client. Thus, for example, when using player to interact with Gazebo, Gazebo is the server and player is the client.

The details of the underlying IPC are entirely hidden by libgazebo , which should be treated as a black box for passing data back and forth to the server. Currently, the only limitation users need be aware of is that both server and client must reside on the same machine; they cannot be run in separate locations across a network.

9.3 Devices and Interfaces

libgazebo makes the familiar distinction between devices and interfaces. In Gazebo, a device is a fully parameterized model, representing a particular real-world object such as a Pioneer2AT robot or a SICK LMS200 laser. An interface, on the other hand, is a general specification for an entire class of devices, such as position or laser. Thus, a Pioneer2AT device will present a position interface, while the SICK LMS200 will present a laser interface.

The complete set of interfaces supported by libgazebo is described in Chapter 10. Note, however, that the set of interfaces defined by libgazebo should not be confused with those defined by player . Currently, these two sets of interfaces are fairly similar, but there is no guarantee that they will remain so in future.

9.4 Using libgazebo 

Client programs must connect both to a specific server and a specific set of devices within that server. The following code snippet illustrates the general behavior:

  // main.c - works with
  // compile with:
  //    g++ -Wall -c -o main.o main.c
  //    g++ main.o main -L. -lgazebo
  // Thanks to Kevin Knoedler for various fixes.

  #include <stdio.h>
  #include <gazebo.h>

  int main (inst argc, char *argv[])
    // Create a client object
    client = gz_client_alloc();  

    // Connect to the server

    // Create a position interface
    position = gz_position_alloc();

    // Connect to device on server
    gz_position_open(position, client, device_id);

    // Lock it
    gz_position_lock(position, 1);

    // Print the current odometric position
    printf("%0.3f %0.3f\n", 
           position->data->odo_pose[1], position->data->odo_pose[1]); 

    // Unlock it

    // Close the interface and free object

    // Close the connection and free the client object

    return 0;
Error checking has been removed from this example for the sake of clarity. There are several points to note:

9.5 Building Programs With libgazebo 

All public functions are declared in gazebo.h and defined in libgazebo.a. The default Gazebo install script will put these in sensible places, so your compiler should pick them up automatically.

next up previous contents
Next: 10. libgazebo Interface Reference Up: 2 Developer Guide Previous: 8. Adding a New   Contents