Extending MOOS-IvP By Example


Maintained by: mikerb@mit.edu         Get PDF


src: project-pavlab/chapters/chap_moosivp_extend


1  Extending MOOS-IvP By Example
     1.1 Brief Overview
     1.2 Obtaining and Building the Example Extensions Folder
     1.3 Using the New MOOS Application
     1.4 Using the New IvP Helm Behavior
     1.5 Extending the Extensions

1   Extending MOOS-IvP By Example


1.1   Brief Overview    [top]


This section describes an example repository distributed with the MOOS-IvP software bundle at www.moos-ivp.org. This repository merely provides a template with an example MOOS application, IvP Behavior, and example mission. More importantly perhaps is that the CMake build files are provided. A cursory look at these files reveal the hooks to add a new behavior or application. This is meant to provide one easy way to begin extending the MOOS-IvP software capabilities with one's own modules.

1.2   Obtaining and Building the Example Extensions Folder    [top]


The example extensions folder is available at the following URL:

    http://www.moos-ivp.org/software/extensions.html

Instructions are provided for downloading the software from an SVN server with anonymous read-only access. After checking out the tree from the SVN server as prescribed at this link, the top level directory should have the following structure:

  $ cd moos-ivp-extend
  $ ls
  moos-ivp-extend/
     bin/
     docs/
     missions/
     src/

The build instructions are maintained in the README files and are probably more up to date than this document. In short building the software amounts to two steps:

  $ cd moos-ivp-extend/src/
  $ cmake ./
  $ make 

The build depends on the directory moos-ivp-extend being in the same directory as moos-ivp. If this needs to be different on your system, the file CMakeLists.txt in the src/ directory can be edited. The relevant lines are at the top of the file:

    GET_FILENAME_COMPONENT(MOOS_BASE_DIR_A    ../../moos-ivp/trunk/MOOS  ABSOLUTE)
    GET_FILENAME_COMPONENT(IVP_BASE_DIR_A     ../../moos-ivp/trunk/ivp   ABSOLUTE)
    GET_FILENAME_COMPONENT(MOOS_BASE_DIR_B    ../../moos-ivp/MOOS        ABSOLUTE)
    GET_FILENAME_COMPONENT(IVP_BASE_DIR_B     ../../moos-ivp/ivp         ABSOLUTE)

After building the software there should be a new MOOS application called pXRelayTest in the bin/ directory, and a new IvP Behavior in the directory src/lib_behaviors-test/ directory. The new behavior is in the form of a shared object, having the name libBHV_SimpleWaypoint.so in Linux, and libBHV_SimpleWaypoint.dylib on the Mac OS X platform.

1.3   Using the New MOOS Application    [top]


To use the new MOOS application, the directory moos-ivp-extend/bin/ needs to be added to the user's shell path. This is typically done in the .cshrc or .bashrc file for tcsh and bash users respectively. To confirm that things are ready to go, use the built-in shell command which:

  $ which pXRelayTest

which returns the directory where the executable resides if it is indeed in the shell's path. Otherwise it returns nothing. Don't forget that an edited path doesn't take effect until a new shell is launched or unless the user types "source .cshrc", or "source .bashrc".

The pXRelayTest application is the same as the pXRelay application distributed with the MOOS-IvP software bundle. It differs only in name for the sake of illustrating the process of building a new application outside the moos-ivp tree. This example MOOS application is described in detail in Section ???. In that section, an example mission file is described for running two pXRelay processes to illustrate their function. A similar mission file is provided in:

  $ moos-ivp-extend/missions/xrelay/xrelay.moos 

that launches two processes, pXRelay and pXRelayTest as a way of confirming that you are running a MOOS application from the extensions build alongside the build of the main moos-ivp repository. Information on how to work through this example is provided in Sections ??? and ???.

1.4   Using the New IvP Helm Behavior    [top]


To use the new IvP Helm behavior built in the extensions folder, the helm needs to know about it. The helm already contains a number of behaviors compiled in to the pHelmIvP executable, but the objective of adding behaviors in the manner outlined here, is to avoid any recompiling of the helm as new behaviors are added. Loosely speaking, there is a one-way dependency between repositories - new behaviors are layered onto the set of behaviors shipped with the helm with no modifications or re-build required of the basic moos-ivp software tree.

Newly built behaviors are compiled in to shared object files, *.so in Linux, and *.dylib in Mac OS X. The helm references a path variable called IVP_BEHAVIOR_DIRS which contains a colon-separated list of all directories containing dynamically loadable behaviors. This variable is a shell environment variable and is typically set in the .cshrc or .bashrc file for tcsh and bash users respectively. For example, the following lines in the .bashrc file for bash users:

   export IVP_BEHAVIOR_DIRS=/home/bob/moos-ivp-extend/src/lib_behaviors-test

A mission file to test this is provided in:

   moos-ivp-extend/missions/alder/alder.moos 

The mission is launched with:

  $ cd moos-ivp-extend/missions/alder/
  $ pAntler alder.moos

The output produced in the helm terminal window should look like that shown in below, and provides useful feedback on whether the dynamically loadable behavior was loaded properly.

Listing 1.1 - Example pHelmIvP terminal output when loading a dynamic behavior.

   0  ****************************************************
   1  *                                                  *
   2  *       This is MOOS Client                        *
   3  *       c. P Newman 2001                           *
   4  *                                                  *
   5  ****************************************************
   6  
   7  ---------------MOOS CONNECT-----------------------
   8    contacting a MOOS server localhost:9000 -  try 00001 
   9    Contact Made
  10    Handshaking as "pHelmIvP"
  11    Handshaking Complete
  12    Invoking User OnConnect() callback...ok
  13  --------------------------------------------------
  14  
  15  The IvP Helm (pHelmIvP) is starting....
  16  Loading behavior dynamic libraries....
  17      Loading directory: /Users/mikerb/Research/moos-ivp-extend/src/lib_behaviors-test
  18          About to load behavior library: BHV_SimpleWaypoint ... SUCCESS
  19  Loading behavior dynamic libraries - FINISHED.
  20  Number of behavior files: 1
  21  Processing Behavior File: alder.bhv  START
  22      Successfully found file: alder.bhv
  23      InitializeBehavior: found dynamic behavior BHV_SimpleWaypoint
  24      InitializeBehavior: found dynamic behavior BHV_SimpleWaypoint
  25  Processing Behavior File: alder.bhv  END
  26  mode description: 
  27  pHelmIvP is Running:
  28           AppTick   @ 4.0 Hz
  29           CommsTick @ 4 Hz

The output prior to line 15 is standard MOOS output for an application connecting to the MOOSDB server. The lines thereafter are specific to the pHelmIvP application. In lines 16-19, the helm indicates that the directories specified in the IVP_BEHAVIOR_DIRS environment variable were found and indicates all dynamic behaviors loaded from those directories, regardless of whether they are used in this mission. Line 20 indicates the number of behavior files (.bhv files) comprising this mission. For each behavior file, output similar to lines 21-26 are generated which reports on the attempts to load individual behavior, noting for each whether they are a static behavior of a dynamically loaded behavior.

When the example is fully launched, the pMarineViewer should appear with a simulated vehicle, and two buttons at the lower right corner. The vehicle can be launched by clicking the "DEPLOY" button. The dynamically loaded behavior is called BHV_SimpleWaypoint and is described in detail in Section ???.

1.5   Extending the Extensions    [top]


To add further MOOS application modules, the simplest way by this example is to create sibling directories to the pXRelayTest, and add the corresponding entry to the CMakeLists.txt file in the src/ directory. Further IvP behaviors can be added within the lib_behaviors-test directory, or in a separate lib_* directory. In the former case, the CMakeLists.txt file in the behavior directory needs to be augmented for the new behavior. In the latter case, an extra entry in the CMakeLists.txt file in the src/ directory is required, as well as the addition of another directory in the IVP_BEHAVIOR_DIRS variable as described above in .


Document Maintained by: mikerb@mit.edu        
Page built from LaTeX source using texwiki, developed at MIT. Errata to issues@moos-ivp.org. Get PDF