<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{uFldContactRangeSensor: Detecting Contact Ranges}
\vspace{0.1in}
\labdate{June 2018}
\vspace{0.1in}
\labauth{Michael Benjamin, mikerb@mit.edu}
\labauth{Department of Mechanical Engineering}
\labauth{MIT, Cambridge MA 02139}
\labtoc{small}
\end{labcover}

\wikidoc{file=IvPTools.UFldContactRangeSensor}
\wikidoc{bugz=uFldContactRangeSensor}
\wikidoc{auth=mikerb@mit.edu}

%=================================================================
\section{Overview}
%=================================================================
\label{sec_ufld_contact_rsensor}
\index{uFldContactRangeSensor}

The \app{uFldContactRangeSensor} application is a tool for simulating range
measurements to off-board contacts, as a proxy for an on-board active
sonar sensor. The range-only measurements are provided conditionally,
depending on the range between the pinging vehicle and the
contact. The simulator may optionally be configured to provide range
measurements with noise.

\pskip

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.45\textwidth]{figures/crs_overview.png}
  \caption{{\bf Simulated Active Sonar:} A vehicle determines its
    range to another vehicle by producing a simulated sonar ping (a
    range request to the simulator), and the simulator conditionally
    responds to the querying vehicle with a report containing the
    range to nearby vehicles. All vehicles send frequent and regular
    node reports to the simulator so the simulator can report the
    range between any two vehicles at any time. The simulator may or
    may not reply to the range request depending on the range between
    the two vehicles and thresholds configured by the user.}
\label{fig_crs_overview}
\end{figure}
\vspace{0.1in}

\noindent
In the \app{uFldContactRangeSensor} application, the beacon and vehicle
locations are known to the simulator, and a tidy \mvar{RANGE\_REPORT}
message is sent to the vehicle(s) as a proxy to the actual range
sensor and calculations that would otherwise reside on the vehicle.
The MOOS app may be configured to have beacons provide a range report
either (a) solicited with a range request, or (b) unsolicited. One may
also configure the range at which a range request will be heard, and
the range at which a range report will be heard. The app may be 
further configured to either (1) include the beacon location and ID, 
or (2) not include the beacon location or ID. 

%=================================================================
\section{Using uFldContactRangeSensor}
%=================================================================

%=================================================================
\subsection{Typical Topology}

The typical module topology is shown in Figure \ref{fig_crs_topology}
below. Multiple vehicles may be deployed in the field, each periodically
communicating with a shoreside MOOS community running a single instance
of \app{uFldContactRangeSensor}. Each vehicle regularly sends a node report
noted by the simulator to keep an updated calculation of each vehicle 
to each simulated beacon. When a vehicle wants to simulate a ping, or
range request, it generates the \mvar{CRS\_RANGE\_REQUEST} message 
sent to the shore. After the simulator calculates the range, a reply
message, \mvar{CRS\_RANGE\_REPORT} message is sent to the vehicle, using
\app{pShare} or similar app.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/crs_topology.png}
  \caption{{\bf Typical uFldContactRangeSensor Topology:} The
    simulator runs in a shoreside computer MOOS community.  All
    deployed vehicles periodically send node reports to the shoreside
    community. The simulator maintains a running estimate of the range
    between vehicles, modulo latency. A vehicle simulates a ping by
    sending a range request to shore and receiving a range report in
    return from the simulator. The simulator also posts visual
    artifacts (\mvvar{VIEW\_RANGE\_PULSE} messages) read by the
    pMarineViewer app optionally running shoreside.}
\label{fig_crs_topology}
\end{figure}

\vspace{0.1in}
\noindent
If running a pure simulation (no physically deployed vehicles), both
MOOS communities may simply be running on the same machine configured
with distinct ports. The \app{pShare} application is shown here
for communication between MOOS communities, but there are other
alternatives for inter-community communication and the operation of
\app{uFldContactRangeSensor} is not dependent on the manner of
inter-communication communications.

%=================================================================
\subsection{Required MOOS Variable Bridges}

Using \app{uFldContactRangeSensor} requires certain information flowing 
between the shoreside and vehicles communities as shown in Figure
\ref{fig_crs_topology}. From the vehicle to the shoreside, three
variables need to be bridged. The below three lines should appear in
the \app{uFldNodeBroker} configuration block on all vehicles. 

\prevblue
\begin{verbatim}
  // Bridges from Vehicle to Shoreside - in uFldNodeBroker configuration

  bridge =  src=APPCAST
  bridge =  src=NODE_REPORT_LOCAL,  alias=NODE_REPORT
  bridge =  src=CRS_RANGE_REQUEST
\end{verbatim}
\postverb

\noindent
The first two lines above would likely already be present due to their
use in other applications. The \mvar{CRS\_RANGE\_REQUEST} is generated
locally on the vehicle and sent to the shoreside community running
\app{uFldContactRangeSensor}.  The above three lines may also be found
in the Hugo example mission discussed in Section \ref{sec_crs_hugo}.

\pskip

The below two lines should appear in the \app{uFldShoreBroker} configuration
block in the shoreside MOOS community. 

\prevblue
\begin{verbatim}
  // Bridges from Shoreside to Vehicle - in uFldShore Broker configuration

  bridge =  src=APPCAST_REQ
  bridge =  src=CRS_RANGE_REPORT_$V, alias=CRS_RANGE_REPORT
\end{verbatim}
\postverb

\noindent
The first line deals with appcasting and would likely be present
anyway due to its use in other applications as well. The second line
ensures that a separate bridge is made for all distinct known
vehicles, as they become known to the shoreside. A range report 
posted by \app{uFldContactRangeSensor} to be sent to archie
would be posted locally in the shoreside to the variable 
\msvar{CRS\_RANGE\_REPORT\_ARCHIE} which would be sent only to the
archie vehicle by \app{pShare}.

%=================================================================
\subsection{Range Requests and Range Reports}
\label{sec_crs_reqs_reps}

\mivar{CRS\_RANGE\_REQUEST}
Range requests are made from vehicles to the simulator of the form:

\prevgreen
\begin{verbatim}
   CRS_RANGE_REQUEST = "name=archie"
\end{verbatim}
\postverb    

\noindent
The simulator only needs to know the requesting vehicle's name. It is
also aware of the requesting and other vehicles' locations via
incoming \mvar{NODE\_REPORT} messages.  When a range request is made,
the simulator applies range and other criteria, discussed in the
following sections. For a request from a vehicle named archie for
example, the simulator may reply with a range report similar to:

\prevgreen
\begin{verbatim}
   CRS_RANGE_REPORT_ARCHIE = "range=126.54,target=jackal,time=19656022406.44"
\end{verbatim}
\postverb

\noindent
If the \pvar{ground\_truth} is set to true (the default), ground truth
reports are also published of the form:

\prevgreen
\begin{verbatim}
   CRS_RANGE_REPORT_GT_ARCHIE = "range=127.12,target=jackal,time=19656022406.44"
\end{verbatim}
\postverb

\noindent
These reports have the simulated range noise removed and are not
typically sent to the vehicles. If the simulator is configured with 
\pvar{report\_vars} set to \var{"short"}, the above to posts are made
with the following form instead:

\prevgreen
\begin{verbatim}
   CRS_RANGE_REPORT_   = "vname=archie,range=126.54,target=jackal,time=19656022406.44"
   CRS_RANGE_REPORT_GT = "vname=archie,range=127.12,target=jackal,time=19656022406.44"
\end{verbatim}
\postverb

\noindent
The name of the requesting vehicle is embedded in the report content
rather than the MOOS variable. The default setting for
\pvar{report\_vars} is \var{"long"}, producing the first style of
reports above.

%=================================================================
\subsection{Configuring the Range Criteria}
\label{sec_crs_range_params}

When a ping is received by the simulator, via
\mvar{CRS\_RANGE\_REQUEST}, the simulator may or may not reply with an
range report depending on the range between the two vehicles.  The
\app{uFldContactRangeSensor} simulator has two range configuration
parameters:

\prevblue
\begin{verbatim}
   reach_distance = default = &lt;meters&gt;    // or "nolimit"
   reply_distance = default = &lt;meters&gt;    // or "nolimit"
\end{verbatim}
\postverb    

\noindent
Two separate range parameters are used so that the simulator can
support scenarios where some vehicles have a more powerful sonar than
others, and some targets are harder to detect (absorb or deflect more
energy) than others. Both parameters are given in meters.  If the user
provides no configuration parameters, all vehicles will default to
have the same reach and reply distances of 100 meters. The default
values may be overridden with something like:

\prevblue
\begin{verbatim}
   reach_distance = default = 120
   reply_distance = default = 80
\end{verbatim}
\postverb    

\noindent
The above two lines, in effect, are the same as \var{reach\_distance =
  100} and \pvar{reply\_distance = 100}. Things become interesting
when individual vehicles are given values different from the
default. Consider the more advantageously configured vehicle, {\em
  victor}, below:

\prevblue
\begin{verbatim}
   reach_distance = victor = 250
   reply_distance = victor = 20
\end{verbatim}
\postverb      

\noindent
If either the reach or reply distance for a given pair of vehicles is
set to \var{nolimit}, then a range report will always be generated
regardless of current range between the two vehicles.  Future
enhancements to this simulator module may include the factoring of
vehicle speed and relative bearing to one another in the threshold
determination of sending range reports.

%=================================================================
\subsection{Adding Exponentially Decaying Detection Probability Beyond Range}
\label{sec_crs_exp_decay}

If one desires an additional probability to as to whether or not the
pinging vehicle receives a ping from the pinged vehicle beyond the
\var{reach\_distance} + \var{reply\_distance} specified in the MOOS
configuration file.  This is normally off unless configured in the
application's configuration file.  In order to use this feature, the
following configuration parameter must be set:

\prevblue
\begin{verbatim}
   exponential_decay = true =   // default is "false"
\end{verbatim}
\postverb

\noindent
When the \var{exponential\_decay} configuration parameter is turned
on, and the vehicle requesting the range report is within the
\var{reach\_distance} + \var{reply\_distance} range of the requested
vehicle, this configuration will have no effect.  However, if the
vehicles are beyond this range, this assign a probability, which
decays exponentially with increasing range a probability that a range
report will still be received.  The actual probability is calculated
by the following equation:

\begin{equation} \label{eqn:range_sensor_prob}
Probability = e^{\left( \dfrac{3(Max - Range)}{Max} \right)}
\end{equation}

\noindent
where $Probability$ is the probability that a range report will be
received, $Max$ is the \var{reach\_distance} + \var{reply\_distance},
and $Range$ is the Range between the two vehicles.
Figure~\ref{fig_crs_exp_decay} is a graphical representation of the
probability of detection as a function of range when this
configuration is turned on.

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/crs_exp_decay.png}
  \caption{{\bf Exponential Decay Configuration:}  If the
  \var{exponential\_decay} configuration parameter is set to true, the
  requesting vehicle will have an additional probability of detecting
  the requested vehicle even when beyond the \var{reach\_distance} +
  \var{reply\_distance} range, which is set to 50 in this example.}
\label{fig_crs_exp_decay}
\end{figure}

%=================================================================
\subsection{Limiting the Arcs of Vehicle Range Requests}
\label{sec_crs_sensor_arcs}

This feature allows a vehicle to limit the range sensing capability to
use specified arcs with respect to the relative heading of the
vehicle.  For instance a user could limit the sensor to only detect
vehicles that are within 45 degrees of directly ahead, or 315 degrees
relative to 45 degrees relative.  

\noindent
Multiple sensor arcs can be specified, in one degree increments. The
default is 360 degree coverage.  To specify a range arc, two numbers
must be specified, separated by a colon.  The first number specifies
the left side of the arc, and the second represents the right side of
the arc.  Valid values for relative headings are between 0 and 359
degrees. Multiple arcs can be separated by commas, or by multiple
lines.  Figure~\ref{fig_crs_sensor_arcs} shows some example arcs of
where requesting vehicles can detect requested vehicles.  Some example are configurations are as follows:

\prevblue
\begin{verbatim}
   sensor_arc = 360 // default, 360 degree coverage
   sensor_arc = 315:45  // 90 degree coverage for front.
   sensor_arc = 45:135,225:315 // two 90 degree arcs centered broadside
\end{verbatim}
\postverb

\begin{figure}[H]
  \centering 
  \includegraphics[width=0.7\textwidth]{figures/crs_sensor_arcs.png}
  \caption{{\bf Example Sensor Arc Configurations:}  Two possible
  range sensor arc configurations.}
\label{fig_crs_sensor_arcs}
\end{figure}

%=================================================================
\subsection{Limiting the Frequency of Vehicle Range Requests}
\label{sec_crs_ping_freq}

From the perspective of operating a vehicle, one may ask: why not
request a range report (ping) as often as possible? There may be
reasons why this is not feasible outside simulation. Limits may exist
due to power budgets of the vehicle, and there may be prevailing
protocols that make it at least impolite to be frequently pinging.

\pskip

To reflect this limitation, the \app{uFldContactRangeSensor} utility
may be configured to limit the frequency in which a vehicle's range
request (or ping) will be honored with a range report reply. By
default this frequency is set to once every 30 seconds for all
vehicles. The default for all vehicles may be changed with the
following configuration in the \var{.moos} file:

\prevblue
\begin{verbatim}
  ping_wait = default = 60
\end{verbatim}
\postverb

\noindent
The limits for a particular vehicle may be set with a similar configuration line:

\prevblue
\begin{verbatim}
  ping_wait = henry = 90
\end{verbatim}
\postverb[0in]

%=================================================================
\subsection{Producing Range Measurements with Noise}
\label{sec_crs_noise}

In the default configuration of \app{uFldContactRangeSensor}, range
reports are generated with the most precise range estimate as
possible, with the only error being due to the latency of the
communications generating the range request and range report.
Additional noise/error may be added in the simulator for each range
report with the following configuration parameter:

\prevblue
\begin{verbatim}
  rn_algorithm   = uniform,pct=0.12     // Values in the range [0,1] 
\end{verbatim}
\postverb

\noindent
or

\prevblue
\begin{verbatim}
  rn_algorithm   = gaussian,sigma=20     // Values in the range [0,inf] 
\end{verbatim}
\postverb

\noindent
For uniform random noise, the noise level, $\theta$, set with the
parameter \var{pct} subfield, will generate a noisy range from an
otherwise exact range measurement $r$, by choosing a value in the
range $[{\theta}{r}, r + {\theta}{r} ]$. The range without noise,
i.e., the ground truth, may also be reported by the simulator if
desired by setting the configuration parameter:

\prevblue
\begin{verbatim}
  ground_truth = true
\end{verbatim}
\postverb

\noindent 
This will result in an additional MOOS variables posted,
\mvar{CRS\_RANGE\_REPORT\_GT}, with the same format as
\mvar{CRS\_RANGE\_REPORT}, except the reported range will be given
without noise.

%=================================================================
\section{Configuration Parameters of uFldContactRangeSensor}
%=================================================================
\index{uFldContactRangeSensor!Configuration Parameters}
\index{Configuration Parameters!uFldContactRangeSensor}

The following parameters are defined for
\app{uFldContactRangeSensor}. A more detailed description is provided
in other parts of this section. Parameters having default values are
indicated so.

\vspace{0.15in}
\refstepcounter{listing}
\noindent {\em Listing \thesection.\arabic{listing}: Configuration
    Parameters for uFldContactRangeSensor.}
\label{lst_crs_params}
\renewcommand{\arraystretch}{1.1}
\begin{longtable}{rp{0.73\textwidth}} 

  \pvar{allow\_echo\_types}: &amp; A list of platform types for which an
  reply will be generated from another source. Legal values:
  \var{auv}, \var{uuv}, \var{usv}, \var{asv}, \var{kayak},
  \var{kingfisher}, \var{glider}, and \var{ship}. The default is the
  empty set, indicating that all types are honored. \\

  \pvar{ground\_true}: &amp; If true, ground truth reports are also
  published alongside the normal range reports, with noise
  removed. This information is not bridge to the vehicles
  however. Legal values: true, false. The default is true. Section
  \ref{sec_crs_reqs_reps}.\\

  \pvar{ignore\_group}: &amp; If specified, incoming node reports that
  match this group will be ignored. Introduced after Release 19.8.x. \\

  \pvar{ping\_color}: &amp; Visual preference: color of initiating ping
  message. Legal values: any color in the Colore Appendix. The
  default is white. \\

  \pvar{ping\_wait}: &amp; Minimum seconds enforced between pings. The
  default is 30. Section \ref{sec_crs_ping_freq}.  \\

  \pvar{reach\_distance}: &amp; Distance out to which the pinging vehicle
  will be heard. Legal values: any numerical value or the keyword
  \var{"nolimit"}. The default is 100. Section
  \ref{sec_crs_range_params}. \\

  \pvar{reply\_distance}: &amp; Distance out to which the pinged vehicle
  will be heard. Legal values: any numerical value or the keyword
  \var{"nolimit"}. The default is 100. Section
  \ref{sec_crs_range_params}. \\
  
  \pvar{exponential\_decay}: &amp; Determines if the there is an
  exponentially decaying with range probability of detection beyond
  the \var{reach\_distance} + \var{reply\_distance}. Default is false.
  Section
  \ref{sec_crs_exp_decay}. \\

  \pvar{reply\_color}: &amp; Visual preference: color of replying message
  Legal values: any color in Color Appendix. The default is
  chartreuse. \\
  
  \pvar{report\_vars}: &amp; Determines if \mvar{CRS\_RANGE\_REPORT} or 
  \mvar{CRS\_RANGE\_REPORT\_VNAME}, or both are published for individual
  range reports. Legal settings are \var{short}, \var{long}, or \var{both}.
  The default is \var{short}. \\
  
  \pvar{sensor\_arcs}: &amp; Set arcs relative to the heading of the vehicle
  in which the range sensor is able to detect vehicles.  The default
  is 360 degrees. Section
  \ref{sec_crs_sensor_arcs}. \\

  \pvar{rn\_algorithm}: &amp; Algorithm for adding random noise to the
  range measurement. Legal parameter values discussed in Section
  \ref{sec_crs_noise}. The default is no noise. \\

  \pvar{report\_vars}: &amp; Determines variable name style used for range
  reports. Legal values: short, long, both. The default is long. Section
  \ref{sec_crs_reqs_reps}. \\
  
  
\end{longtable}

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

To see an example MOOS configuration block, enter the following from
the command line:

\begin{consoleverb}
 $ uFldContactRangeSensor --example or -e
\end{consoleverb}

\noindent
This will show the output shown in Listing \ref{lst_crs_econfig} below.

\vspace{0.25in}
\begin{listing}{Example configuration of the \app{uFldContactRangeSensor} application}
\label{lst_crs_econfig}
\footnotesize
\begin{verbatim}
   1  =============================================================== 
   2  uFldContactRangeSensor Example MOOS Configuration                      
   3  =============================================================== 
   4                                                                  
   5  ProcessConfig = uFldContactRangeSensor                                 
   6  {                                                               
   7    AppTick   = 4                                                 
   8    CommsTick = 4                                                 
   9                                                                  
  10    // Configuring aspects of the vehicles in the sim             
  11    reach_distance = default = 100  // in meters or {nolimit}     
  12    reply_distance = default = 100  // in meters or {nolimit}     
  13    ping_wait      = default = 30   // in seconds                 
  14
  15    push_distance  = jackal  = 50
  16    push_distance  = archie  = 190
  17    ping_wait      = archie  = 32
  18                                                                  
  19    // Configuring manner of reporting                            
  20    report_vars    = short // or {long, both}                     
  21    ground_truth   = true  // or {false}                          
  22                                                                  
  23    // Configuring visual artifacts                               
  24    ping_color     = white                                        
  25    reply_color    = chartreuse                                   
  26                                                                  
  27    // Configuring Artificial Noise                               
  28    rn_algorithm   = uniform,pct=0.04                            
  29
  31    // Configuring Probability Detection with Exponential Decay
  32    exponential_decay = false   // default is false
  33   	
  34    // Configuring Sensor Arcs
  35    sensor_arc = 45:135,225:315 // for two side arcs
  36    // sensor_arc = 315:45      // just for front
  37    // sensor_arc = 360         // default, sets full circle
  38  }                                                           
\end{verbatim}
\end{listing}
\normalsize    

%=================================================================
\section{Publications and Subscriptions for uFldContactRangeSensor}
%=================================================================
\index{uFldContactRangeSensor!Publications and Subscriptions}
\index{Publications and Subscriptions!uFldContactRangeSensor}
\label{sec_crs_interface}

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

\begin{consoleverb}
 $ uFldContactRangeSensor --interface or -i
\end{consoleverb}

%=================================================================
\subsection{Variables Published by uFldContactRangeSensor}
\label{sec_crs_pubs}
\index{uFldContactRangeSensor!Publications}
\index{Publications!uFldContactRangeSensor}

The primary output of \app{uFldContactRangeSensor} to the MOOSDB is
the posting of range reports and visual cues for the range reports.

\begin{packed_itemize}[2]
\item \mvar{APPCAST}: Contains an appcast report identical to the
  terminal output. Appcasts are posted only after an appcast request
  is received from an appcast viewing utility. Section
  \ref{sec_crs_appcast}.

\item \mvar{CRS\_RANGE\_REPORT}: A report on the range from a
  particular vehicle to the pinging vehicle.  Section
  \ref{sec_crs_range_params}.

\item \mvar{CRS\_RANGE\_REPORT\_NAMEJ}: A report on the range from a
  particular named NAMEJ, to the pinging vehicle.

\item \mvar{VIEW\_RANGE\_PULSE}: A description for visualizing the
  beacon range report. Section \ref{sec_crs_range_pulse}.
\end{packed_itemize}

%=================================================================
\subsection{Variables Subscribed for by uFldContactRangeSensor}
\label{sec_crs_subs}

The \app{uFldContactRangeSensor} application will subscribe for the
following MOOS variables:

\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{CRS\_RANGE\_REQUEST}: A request to generate range reports
    for all targets to all vehicles within range of the target.
    
\item \mvar{NODE\_REPORT}: A report on a vehicle location and status.

\item \mvar{NODE\_REPORT\_LOCAL}: A report on a vehicle location and
  status. \\
\end{packed_itemize}

%=================================================================
\subsection*{Command Line Usage of uFldContactRangeSensor}
\label{sec_crs_cmdline}
\index{Command Line Usage!uFldContactRangeSensor}
\index{uFldContactRangeSensor!Command Line Usage}

The \app{uFldContactRangeSensor} application is typically launched as a part
of a batch of processes by pAntler, but may also be launched from the
command line by the user.  To see command-line options enter the
following from the command-line:

\begin{consoleverb}
 $ uFldContactRangeSensor --help or -h
\end{consoleverb}

\noindent
This will show the output shown in Listing \ref{lst_crs_usage} below.

\refstepcounter{listing}
\vspace{0.1in}
\noindent {\em Listing \arabic{listing} - Command line usage for the
uFldContactRangeSensor tool.}
\label{lst_crs_usage}
\footnotesize
\begin{verbatim}
  1  Usage: uFldContactRangeSensor file.moos [OPTIONS]                
  2                                                           
  3  Options:                                               
  4    --alias=&lt;ProcessName&gt;                                
  5        Launch uFldContactRangeSensor with the given process    
  6        name rather than uFldContactRangeSensor.                
  7    --example, -e                                        
  8        Display example MOOS configuration block         
  9    --help, -h                                           
 10        Display this help message.                       
 11    --version,-v                                         
 12        Display the release version of uFldContactRangeSensor.     
\end{verbatim}
\normalsize

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

The \app{uFldContactRangeSensor} application produces some useful
information to the terminal and identical content through
appcasting. An example is shown in Listing \ref{lst_crs_appcast}
below.  On line 2, the name of the local community or vehicle name is
listed on the left. On the right, \var{"0/0(848)} indicates there are
no configuration or run warnings, and the current iteration of
\app{uFldContactRangeSensor} is 848. Lines 4-10 convey the prevailing
configuration settings. They may reflect the default values or values
read from the configuration block like the one shown previously in
Listing \ref{lst_crs_econfig}.

\vspace{0.1in}
\refstepcounter{listing}
\vspace{0.1in}
\noindent {\em Listing \arabic{listing} - Example uFldContactRangeSensor
    console or appcast output.}
\label{lst_crs_appcast}
\scriptsize
\begin{verbatim}
   1  ===================================================================
   2  uFldContactRangeSensor shoreside                           0/0(848)
   3  ===================================================================
   4  Default Ping Wait:        30
   5  Random Noise Algorithm:   uniform
   6  Random Noise Uniform Pct: 0.04
   7  Gaussian Noise:           0
   8  Ping Color:               white
   9  Echo Color:               chartreuse
  10  Ground Truth Reporting:   true
  11  Allow Echo Types:         all types
  12  
  13  Vehicles(3):
  14          Node  Ping  Push  Pull  Pings  Echos  Too   Too  Echos
  15  VName   Reps  Wait  Dist  Dist  Gen'd  Rec'd  Freq  Far  Sent 
  16  ------  ----  ----  ----  ----  -----  -----  ----  ---  -----
  17  archie  411   32    190   100   11     5      6     0    0    
  18  betty   410   30    100   100   0      0      0     0    0    
  19  jackal  411   30    50    100   0      0      0     0    5    
  20  
  21  ===================================================================
  22  Most Recent Events (8):
  23  ===================================================================
  24  [211.60]: ARCHIE  &lt;--   JACKAL
  25  [211.60]: ARCHIE  ----))
  26  [181.40]: ARCHIE  ----))  XXX too frequent. (4.03)
  27  [177.37]: ARCHIE  &lt;--   JACKAL
  28  [177.37]: ARCHIE  ----))
  29  [146.23]: ARCHIE  ----))  XXX too frequent. (30.66)
  30  [144.22]: ARCHIE  ----))  XXX too frequent. (28.64)
  31  [115.58]: ARCHIE  &lt;--   JACKAL
\end{verbatim}
\normalsize
  
\vspace{0.15in}
\noindent
In the block of output beginning on line 13, the information is
organized by vehicle name in each row. The first two columns show the
vehicle name and number of node reports received for that vehicles. 

The next three columns reflect configuration settings for particular
vehicles. For example, the {\em Ping Wait} time of 32 seconds reflects
line 17 in Listing \ref{lst_crs_econfig}. The {\em Push Dist} value
reflects line 16 in Listing \ref{lst_crs_econfig}. The last five
columns reflect the results of pings generated by vehicles. THe 
{\em Pings Gen'd} column shows how many \mvar{CRS\_SENSOR\_REQUEST}
messages have been received by that vehicle. The next column shows how
many replies were sent back to the vehicle. The {\em Too Freq} and 
{\em Too Far} columns explain why a ping may not have been replied. 
The {\em Echos Sent} column shows how many echos were sent to others
about that vehicle. In this snapshot, archie has receieved five
ping echos about the jackal vehicle.

\pskip

The last block, lines 21-31 show the most recent events with their
timestamps. Line 28 shows an example where a ping was generated by 
archie, followed by a reply about jackal on line 27. Lines like 26
indicate that a ping was rejected by the simulator as being too soon
after the previous ping.

%=================================================================
\section{Interaction between uFldContactRangeSensor and pMarineViewer}
%=================================================================
\label{sec_crs_range_pulse}

The \app{uFldContactRangeSensor} application will post certain
messages to the MOOSDB that may be subscribed for by GUI based
applications like \app{pMarineViewer} for visualizing the posting of
\mvar{CRS\_RANGE\_REPORT} and \mvar{CRS\_RANGE\_REQUEST} messages.  A
     {\em range pulse} message conveys visually the generation of a
     range report, or the receipt of a range request. The pulse is
     rendered as a ring with a growing radius having the vehicle at
     the center.  Range pulses are posted to the MOOS variable
     \mvar{VIEW\_RANGE\_PULSE} with a form similar to:

\prevgreen
\begin{verbatim}
   VIEW_RANGE_PULSE = "x=-40,y=-150,radius=40,duration=15,fill=0.25,fill_color=green,
                      label=04,edge_color=green,time=3892830128.5,edge_size=1"
\end{verbatim}
\postverb
 
\noindent
The \var{x} and \var{y} parameters convey the center of the pulse. The 
\var{radius} parameter indicates the radius of the circle at its maximum.
The \var{duration} parameter is the number of seconds the pulse will be 
rendered. The pulse will grow its radius linearly from zero meters at zero
seconds to \var{radius} meters at \var{duration} seconds. The \var{fill}
parameter is in the range $[0,1]$, where $0$ is full transparency (clear)
and $1$ is fully opaque. The pulse transparency increases linearly as the
range ring is rendered. The starting transparency at $radius=0$ is given 
by the \var{fill} parameter. The transparency at the maximum radius is
zero. The \var{fill\_color} parameter specifies the color rendered to the
internal part of the range pulse. The choice of legal colors is described
in the Color Appendix. The \var{label} is a string that uniquely 
identifies the range instance to consumers like \app{pMarineViewer}. As 
with other objects in \app{pMarineViewer}, if it receives an object the same
label and type as one previously received, it will replace the old object
with the new one in its memory. The \var{edge\_color} parameter describes
the color of the ring rendered in the range pulse. The \var{edge\_size}
likewise describes the line width of the rendered ring. The \var{time}
parameter indicates the UTC time at which the range pulse object was
generated.

\pskip

One further note to developers of other apps perhaps wishing to also
generate a range pulse for viewing - the recommended manner to
generate a range pulse string is to create an instance of the
\var{XYRangePulse} class using the defined class interface. The string
should be obtained by invoking the serialization method for that
class. This will better ensure compatibility as the software
evolves. The class is defined in \var{lib\_geometry} in the MOOS-IvP
tree.


%=================================================================
\section{The Hugo Example Mission Using uFldContactRangeSensor}
%=================================================================
\label{sec_crs_hugo}

The {\em hugo} mission is distributed with the MOOS-IvP source code
and contains a ready example of the \app{uFldContactRangeSensor}
application.  Assuming the reader has downloaded the source code
available at \var{www.moos-ivp.org} and built the code according to
the documentation, the {\em hugo} mission may be launched by:

\vspace{0.05in} 
\small
\begin{verbatim}
   $ cd moos-ivp/ivp/missions/m8_hugo/
   $ ./launch.sh 10
\end{verbatim}
\normalsize    
\vspace{0.05in} 

\noindent
The argument, $10$, in the line above will launch the simulation in
\var{10x} real time.  Once this launches, the \app{pMarineViewer} GUI
application should launch and the mission may be initiated by hitting
the \var{DEPLOY} button. Two vehicles should be visibly moving, one
surface vehicle labeled \var{"archie"} and one UUV labeled
\var{"jackal"}, as shown in Figure \ref{fig_crs_hugo}.

\vspace{0.1in}
\begin{figure}[H]
  \centering 
  \includegraphics[width=0.88\textwidth]{figures/crs_hugo.png}
  \caption{{\bf The Hugo Example Mission:} The Hugo example mission
    involves two simulated vehicles. The first vehicle is a surface
    vehicle, {\em archie}, traversing a lawnmower shaped search
    pattern. The second vehicle, is a UUV, {\em jackal}, traversing a
    polygon pattern overlapping the first pattern. Periodically {\em
      archie} emits a ping (range request). This example contains
    three distinct MOOS communities - one for each simulated vehicle,
    and one for the shoreside community running
    \vvar{uFldContactRangeSensor}.}
\label{fig_crs_hugo}
\end{figure}
\vspace{0.1in}

The surface vehicle will traverse a survey pattern over the region
shown in Figure \ref{fig_crs_hugo}, periodically generating a range
request (ping).  With each range request, a white range pulse should
be visible around the vehicle. Almost immediately afterwards, a range
report for each neighboring vehicle within range is generated and a
green range pulse around each ``target'' vehicle is rendered.  The
snapshot in Figure \ref{fig_crs_hugo} depicts a moment in time where
the range request visual pulses are around both vehicles. The larger
pulse around the surface vehicle indicates it was generated just prior
to the reply pulse around the UUV.

\pskip

\index{uTimerScript}
\index{uTimerScript!Simulated Range Requests}
How does the simulated vehicle generate a range request? In practice
a user may implement an intelligent module to reason about when to 
generate requests, but in this case the \app{uTimerScript} application
is used by creating a script that repeats endlessly, generating a 
range request once every 25-35 seconds. The script is also conditioned
on \var{(NAV\_SPEED &gt; 0)}, so the pinging doesn't start until the 
vehicle is deployed. The configuration for the script can be seen in 
the \app{uTimerScript} configuration block in the \var{shoreside.moos}
file. More on the \app{uTimerScript} application can be found in 

\urlxx{http://oceanai.mit.edu/ivpman/apps/uTimerScript}

\end{document}

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