8. Adding a New Model

This chapter describes the basic steps for creating a new model. It describes how the source files should be laid out, how to register models with the server and how to work with GNU Autotools.

N.B. These instructions assume you are working from CVS, not a source snap-shot or distribution.

Developers should consult Chapter 7 for detailed information on model class implementation. Developers are also advised to read Appendix B for Gazebo coding standards and conventions.

8.1 Model Source Files

Source code for models is located under server/models/, with a separate directory for each model. Model directory names should match model class names, i.e., the SickLMS200 model is found the server/models/SickLMS200/ directory. Layout of files within the model directory is at the developers discretion; by convention, however, models are comprised of a single header file containing the model class declarations, and one or more source files containing the class definitions. Thus, the SickLMS200 model is comprised of SickLMS200.hh and SickLMS200.cc.

The recommended way to create a new model is to copy an existing model with similar functionality, and perform some judicious search-and-replacing. In addition to changing the class name (e.g. from SickLMS200 to MyModel), developers must also change the model's naked New function. E.g., NewSickLMS200() becomes NewMyModel(). This function is used to create instances of the model class at run-time.

8.2 Registering the Model

Models must be registered with the server. Registration is handled by the ModelFactory class, which can be found in server/ModelFactory.cc. Registration is a two step process:

1. Add a declaration for the new models creation function; e.g.:

   #if INCLUDE_MYMODEL
   extern Model* NewMyModel( World *world );
   #endif
   

   The INCLUDE macro will be defined automagically by Autotools (see below) if and only if the model should be included in the build.
2. In the ModelFactory::NewModel() function, add a clause for the new model, e.g.:

   #ifdef INCLUDE_MYMODEL
     if (strcmp(classname, "MyModel") == 0)
       return NewMyModel(world);
   #endif
   

   This line allows the server to look up the model by name and construct an appropriate class instance at run-time.

8.3 Working with GNU Autotools

Gazebo uses GNU Autotools to managing the build process; while Autotools can be daunting for newcomers, the rewards are well worth the effort. When using Autotools, there are two key notions to bear in mind:

• Project-level configuration is controlled by configure.in found in the project top-level directory.
• Module-level configuration is controlled by Makefile.am found in every sub-directory.

These configuration files are used to generate the Makefile's that will ultimately control the build process (developers should never manipulate Makefile's directly).

The basic process for adding a new model to the Autotools setup is as follows.

1. Create Makefile.am for the new model:
   • Copy Makefile.am from another model into the new model directory.
   • Modify all entries describing the model name. For example, if you copied Makefile.am from the SickLMS200 model, replace all references to sicklms200 with mymodelname.
   • Modify the SOURCES line to list the new model's source files. Be sure to include header files in this list (so they will included in the final distribution).
2. Modify Makefile.am in the server/models directory.
   • Add the new model directory to the SUBDIRS line.
3. Modify configure.in in the top-level directory.
   • In the ``model tests'' section, add a GAZEBO_ADD_MODEL entry for the new model. The arguments are: model name (lower case), model path, whether or not the model should be included in the default build, a list of libraries to check for and a list of headers to check for. The model will not be built unless all of the library and header dependencies are satisfied.
   • In the ``create makefiles'' section, add the path of the Makefile that needs to be created.
4. Re-generate the Makefile's:
   • From the top-level directory, run:

       $ ./bootstrap
     

     with whatever arguments you would normally pass to configure.

Running make will now build the new driver.