<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">\documentclass[onecolumn,letterpaper,11pt]{article}

%===================================================================
\input{common_latex/common_latex_packages}
\input{common_latex/common_latex_definitions}
\input{common_latex/common_latex_help_format}
%===================================================================

\begin{document}

\begin{labcover}
\labtitle{pExample - An Example Application Documented}
\vspace{0.1in}
\labdate{Fall 2017}
\vspace{0.1in}
\labauth{Francis Underwood, underwood@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

% Wikifile naming convention:
% prefix=PavLab.
% suffix is app name with first letter uppercase
\wikidoc{file=IvPTools.PExample}
\wikidoc{bugz=pExample}
\wikidoc{auth=underwood@mit.edu}

%====================================================================
\section{pExample Overview}
%====================================================================
\label{sec_pExample}
\index{pExample}

In this section a short description, 1-2 paragraphs at most, is typical.
Describe what problem this app addresses. If it makes sense, perhaps
show the intended topology, i.e., where the module fits in during its
typical usage:

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.4\textwidth]{figures/topology.png}
  \caption{{\bf Typical uFldHazardMetric Topology:} This module runs on
    the shoreside, alongside the hazard sensor typically, and receives
    hazazardset reports from the vehicle bridge with the
    \mvvar{HAZARDSET\_REPORT} variable. Evaluations may be seen via the
    appcast output of \app{uFldHazardMetric}, or in the log file.}
  \label{fig_pexample_overview}
\end{figure}


%====================================================================
\section{Using the pExample Application}
%====================================================================
\label{subsec_using_pExample}

This section is typically where the details of the app are described.
If it has modes, or state, they can be described here.

%====================================================================
\subsection{Mail Handled by pExample}

If this app ingests certain incoming mail, this would be a good place
to describe what those mail messages are, who produces them, the
incoming mail message format, and what happens upon mail receipt.

%-------------------------------------------------------------------
\subsubsection{The \mvar{SETUP\_INFO} Mail Message}
\label{sec_pex_setup_mail}

The \mvar{SETUP\_INFO} mail is typically generated by \app{pFooBar} and
contains key information for \app{pExample}. A typical message may
look like:

\vspace{0.1in}
\noindent
\mvar{SETUP\_INFO}\var{ = "vname=henry,top\_speed=3.4,mode=alpha"}

\vspace{0.1in}
\noindent
The \var{vname} component names the vehicle of interest for \app{pExample}.
The \var{top\_speed} component notes the maximum speed allowed for the
contact vehicle. The \var{mode} component is the contact's last
known search mode.


%====================================================================
\subsection{Configuration Parameters of pExample}

If this app has configuration parameters, this would be a good place
to describe what those parameters are, legal values accepted, the
default value, and what get happens under the hood when certain
parameter values are used.

\vspace{0.1in}
\noindent
Note the quick-listing of parameters is given in Section
\ref{sec_pex_params}.

%-------------------------------------------------------------------
\subsubsection{The \pvar{port\_number} Configuration Parameter}
\label{sec_pex_port_param}

Here we provide full details of this parameter.

%-------------------------------------------------------------------
\subsubsection{The \pvar{ip\_address} Configuration Parameter}
\label{sec_pex_ipaddr_param}

Here we provide full details of this parameter.


%===================================================================
\section{Configuration Parameters for pExample}
\label{sec_pex_params}
% The index info is included if this document becomes part of a larger work
\index{pExample!Configuration Parameters}
\index{Configuration Parameters!pExample}

The \app{pExample} application may be configured with a configuration
block within a MOOS mission file, typically with a \var{.moos} file
suffix. The following parameters are defined for \app{pExample}:

\vspace{0.15in}
\begin{listing}{Configuration Parameters for iM200}
  \label{lst_mtwo_params}
  \renewcommand{\arraystretch}{1.1}
  \begin{longtable}{rp{0.76\textwidth}} 
    
    \pvar{ip\_address}: &amp; The IPv4 address of the front-seat computer
    that is being interfaced with. Default value is \pvar{localhost},
    which implies that the \app{pExample} application is being run on
    the front-seat vehicle itself. See Section
    \ref{sec_pex_ipaddr_param}. \\
    
    \pvar{port\_number}: &amp; At the defined \pvar{ip\_address}, this is
    the port number to communicate with the vehicle. Default is Port
    9000.  See Section \ref{sec_pex_port_param} \\
        
  \end{longtable}
\end{listing}

%====================================================================
\subsection{An Example MOOS Configuration Block}

An example MOOS configuration block is provided in Listing
\ref{lst_pex_econfig} below. This can also be obtained from a terminal
window with:

\vspace{0.1in}
\begin{consoleverb}
$ pExample --example or -e
\end{consoleverb}
\vspace{0.1in}

\vspace{0.25in}
\begin{listing}{Example configuration of the pExample application}
\label{lst_pex_econfig}
\footnotesize
\begin{verbatim}
1   ============================================================================
2   pExample Example MOOS Configuration
3   ============================================================================
4
5   ProcessConfig = pExample
6   {
7     AppTick        = 10
8     CommsTick      = 10
9
10    port_number    = 29500
11    ip_address     = localhost // Default is 'localhost'
23  }
\end{verbatim}
\normalsize
\end{listing}

%=============================================================
\section{Publications and Subscriptions for pExample}
\index{pExample!Publications and Subscriptions}
\index{Publications and Subscriptions!pExample}
\label{sec_pex_interface}

The interface for \app{pExample}, in terms of publications and
subscriptions, is described below. This same information may also be
obtained from the terminal with:

\vspace{0.1in}
\begin{consoleverb}
$ pExample --interface or -i
\end{consoleverb}
\vspace{0.05in}

%---------------------------------------------------------------------
\subsection{Variables Published by pExample}
\label{sec_pex_pubs}

\begin{packed_itemize}[2]
	
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Reports are posted only in response to an appcast
  request messages.
  
\item \mvar{EXAMPLE\_OUTPUT}: Last reported position of the vehicle, in
  meters east or west of the MOOS origin.
  
\item \mvar{BATTERY\_VOLTAGE}: Last reported battery voltage, in 
  volts.
  
\end{packed_itemize}

%------------------------------------------------------------------
\subsection{Variables Subscribed for by pExample}
\label{sec_pex_subs}

The \app{pExample} always subscribes for appcasting events:

\begin{packed_itemize}[2]
	
\item \mvar{APPCAST\_REQ}: A request to generate and post a new
  apppcast report, with reporting criteria, and expiration.
	
\item \mvar{SETUP\_INFO}: Information regarding the network setup. See
  Section \ref{sec_pex_setup_mail}.
	
\end{packed_itemize}


%===========================================================
\section{Terminal and AppCast Output}
%===========================================================
\label{sec_pex_appcast}

The \app{pExample} application produces some useful information to the
terminal on every iteration of the application. An example is shown in
Listing \ref{lst_pex_appcast} below. This application is also appcast
enabled, meaning its reports are published to the MOOSDB and viewable
from any \app{uMAC} application or \app{pMarineViewer}. The counter on
the end of line 2 is incremented on each iteration of \app{pExample},
and serves a bit as a heartbeat indicator.  The \var{"0/0"} also on
line 2 indicates there are no configuration or run warnings detected.

\vspace{0.1in}
\begin{listing}{Example terminal or appcast output for \app{pExample}}
\label{lst_pex_appcast}
\footnotesize
\begin{verbatim}
  1  ===================================================================
  2  pExample alpha                                             0/0(442)
  3  ===================================================================
  4  Configuration Summary: 
  5  ======================================
  6    ip_addres = 128.30.4.221
  7    port      =  9011
  8  
  9  Setup Messages
 10  ======================================
 11          Total Received: 11
 12                   VName: henry 
 13                    Mode: alpha
 14  
 15  Vehicle Summary
 16  ======================================
 17  VName  Speed  Mode   
 18  -----  -----  -----  
 19  henry  2.3    alpha      
 20  gilda  2.1    gamma    
 21  luke   0.3    delta   
\end{verbatim}
\end{listing}
\normalsize
\vspace{0.1in}

\noindent
The first few lines (6-7) show the configuration settings for
\app{pExample}.  The setup status of \app{pExample} is shown in Lines
9-13. The second status block, lines 15-21, indicate last reported
speed and mode for each vehicle.

\end{document}

</pre></body></html>