%================================================================
\section{Extending MOOS-IvP By Example}
%================================================================
\wikisec{grp=extend,file=MOOSIvPExtend,short=Extending MOOS-IvP}

%================================================================
\subsection{Brief Overview}
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.

%================================================================
\subsection{Obtaining and Building the Example Extensions Folder}
\label{obtaining_extend}

The example extensions folder is available at the following URL:

\small
\begin{verbatim}
   http://www.moos-ivp.org/software/extensions.html
\end{verbatim}
\normalsize

\noindent
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: 

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-extend
 $ ls
 moos-ivp-extend/
    bin/
    docs/
    missions/
    src/
\end{consoleverb}
\normalsize
\vspace{0.1in}

\noindent
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:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-extend/src/
 $ cmake ./
 $ make 
\end{consoleverb}
\vspace{0.1in}

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

\vspace{0.1in}
\footnotesize
\begin{verbatim}
   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)
\end{verbatim}
\normalsize

\vspace{0.1in}
\noindent
After building the software there should be a new MOOS application
called \app{pXRelayTest} in the \var{bin/} directory, and a new IvP
Behavior in the directory \var{src/lib\_behaviors-test/} directory.
The new behavior is in the form of a shared object, having the name
\var{libBHV\_SimpleWaypoint.so} in Linux, and
\var{libBHV\_SimpleWaypoint.dylib} on the Mac OS X platform.

%====================================================================
\subsection{Using the New MOOS Application}

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

\vspace{0.1in}
\begin{consoleverb}
 $ which pXRelayTest
\end{consoleverb}
\vspace{0.1in}

\noindent
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 \var{"source .cshrc"}, or \var{"source
  .bashrc"}.

The \app{pXRelayTest} application is the same as the \app{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 \var{moos-ivp} tree. This example MOOS
application is described in detail in Section \ref{sec_pxrelay}. In
that section, an example mission file is described for running two
\app{pXRelay} processes to illustrate their function.  A similar
mission file is provided in:

\vspace{0.1in}
\begin{consoleverb}
 $ moos-ivp-extend/missions/xrelay/xrelay.moos 
\end{consoleverb}
\vspace{0.1in}


\noindent
that launches two processes, \app{pXRelay} and \app{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
\ref{sec_xrelay_uxms} and \ref{sec_poke_xrelay}.

%====================================================================
\subsection{Using the New IvP Helm Behavior}
\label{sec_bhv_extend}

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 \app{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,
\var{*.so} in Linux, and \var{*.dylib} in Mac OS X. The helm
references a path variable called \var{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 \var{.cshrc} or \var{.bashrc}
file for tcsh and bash users respectively. For example, the following
lines in the \var{.bashrc} file for bash users:

\vspace{0.1in}
\begin{fileverb}
  export IVP_BEHAVIOR_DIRS=/home/bob/moos-ivp-extend/src/lib_behaviors-test
\end{fileverb}
\vspace{0.1in}
    
\noindent
A mission file to test this is provided in:

\vspace{0.1in}
\begin{consoleverb}
  moos-ivp-extend/missions/alder/alder.moos 
\end{consoleverb}
\vspace{0.1in}

\noindent
The mission is launched with:

\vspace{0.1in}
\begin{consoleverb}
 $ cd moos-ivp-extend/missions/alder/
 $ pAntler alder.moos
\end{consoleverb}
\vspace{0.1in}

\noindent
The output produced in the helm terminal window should look like that
shown in Listing \ref{dyno-helm} below, and provides useful feedback
on whether the dynamically loadable behavior was loaded properly.

\vspace{0.2in}

\vspace{0.1in}
\begin{listing}{Example pHelmIvP terminal output when loading a dynamic behavior}
\label{dyno-helm}
\scriptsize
\begin{verbatim}
  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
\end{verbatim}
\normalsize
\end{listing}

\vspace{0.2in} 

\noindent
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 \app{pHelmIvP} application. In lines 16-19, the helm indicates
that the directories specified in the \var{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
(\var{.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.

\pskip

When the example is fully launched, the \app{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 \var{BHV\_SimpleWaypoint} and
is described in detail in Section \ref{sec_simple_wpt}.

%====================================================================
\subsection{Extending the Extensions}

To add further MOOS application modules, the simplest way by this
example is to create sibling directories to the \app{pXRelayTest}, and
add the corresponding entry to the \var{CMakeLists.txt} file in the
\var{src/} directory. Further IvP behaviors can be added within the
\var{lib\_behaviors-test} directory, or in a separate \var{lib\_*}
directory. In the former case, the \var{CMakeLists.txt} file in the 
behavior directory needs to be augmented for the new behavior. 
In the latter case, an extra entry in the \var{CMakeLists.txt} file
in the \var{src/} directory is required, as well as the addition of
another directory in the \var{IVP\_BEHAVIOR\_DIRS} variable as described
above in Section \ref{sec_bhv_extend}.
